req.params, req.query et req.body dans Express expliqués

Dans Express, req.params contient les valeurs des segments nommés du chemin de la route (/users/:id donne req.params.id), req.query contient la query string après le ? (/search?q=node donne req.query.q), et req.body contient les données envoyées dans le corps de la requête. req.params et req.query sont remplis à chaque requête, mais req.body reste undefined tant qu'un parser comme app.use(express.json()) ne l'a pas lu. Les valeurs de params et de query sont toujours des chaînes.

const express = require('express');
const app = express();
app.use(express.json());

app.get('/users/:userId/posts', (req, res) => {
    res.json({ params: req.params, query: req.query });
});

app.post('/users/:userId/posts', (req, res) => {
    res.status(201).json({ params: req.params, body: req.body });
});

// GET /users/7/posts?sort=new&limit=2
app.listen(3000);

La première requête répond {"params":{"userId":"7"},"query":{"sort":"new","limit":"2"}}. Remarquez les guillemets : 7 et 2 sont des chaînes, donc convertissez-les avec Number() avant de faire des calculs ou de les comparer à des nombres. Passez maintenant la méthode en POST, gardez le chemin /users/7/posts et envoyez le corps {"title": "Hello", "draft": true} : la réponse est 201 avec "body":{"title":"Hello","draft":true}, où true est un vrai booléen puisqu'il vient du JSON.

req.params, req.query ou req.body

Une route peut avoir plusieurs paramètres, et chaque nom devient une clé de req.params : /teams/:teamId/members/:memberId donne les deux identifiants. Un tiret ou un point les sépare aussi, donc /flights/:from-:to transforme /flights/LAX-SFO en { from: 'LAX', to: 'SFO' }.

req.query avec des clés répétées ou absentes

Une clé qui apparaît deux fois devient un tableau, et une clé absente vaut undefined, donc donnez une valeur par défaut aux options :

const express = require('express');
const app = express();

app.get('/products', (req, res) => {
    const page = Number(req.query.page ?? 1);
    const tags = [].concat(req.query.tag ?? []);
    res.json({ page, tags, raw: req.query });
});

// GET /products?tag=red&tag=sale
app.listen(3000);

La réponse est {"page":1,"tags":["red","sale"],"raw":{"tag":["red","sale"]}}. Envoyez GET /products?tag=red&page=3 et tags reste un tableau, ["red"], car [].concat() transforme une chaîne ou un tableau en tableau. Express 5 parse les query strings avec le parser simple de Node, donc ?filter[size]=m donne la clé "filter[size]", pas un objet imbriqué ; Express 4 l'imbriquait.

req.body a besoin d'express.json()

Node fournit le corps sous forme de stream d'octets. express.json() le lit, le parse et définit req.body, mais seulement quand la requête a Content-Type: application/json. Les formulaires HTML envoient application/x-www-form-urlencoded, qui demande plutôt express.urlencoded().

const express = require('express');
const app = express();
app.use(express.json());

app.post('/signup', (req, res) => {
    const { email, name } = req.body ?? {};
    if (!email) {
        return res.status(400).json({ error: 'email is required' });
    }
    res.status(201).json({ email, name: name ?? 'anonymous' });
});

app.get('/', (req, res) => {
    res.send('Send POST /signup with a JSON body');
});

app.listen(3000);

Envoyez POST /signup avec le corps {"email": "ada@example.com"} et vous obtenez 201 avec {"email":"ada@example.com","name":"anonymous"}. Envoyez un corps vide et vous obtenez 400. Le ?? {} compte : sans lui, déstructurer undefined lève une TypeError pour toute requête sans corps JSON. Pour valider vraiment la forme et les types, utilisez une bibliothèque de schémas comme zod.

req.headers et req.get()

req.headers est un objet avec tous les en-têtes de la requête, aux noms en minuscules. req.get(name) lit un en-tête sans tenir compte de la casse, donc req.get('Content-Type') et req.get('content-type') renvoient la même valeur. Quelques autres propriétés que vous utiliserez :

const express = require('express');
const app = express();

app.get('/whoami', (req, res) => {
    res.json({
        method: req.method,
        path: req.path,
        originalUrl: req.originalUrl,
        agent: req.get('User-Agent') ?? null,
        token: req.get('authorization') ?? null,
    });
});

// GET /whoami?debug=1
app.listen(3000);

path vaut /whoami et originalUrl vaut /whoami?debug=1. Ajoutez l'en-tête Authorization: Bearer abc dans la barre de requête et renvoyez-la : token devient "Bearer abc". Dans un router monté avec app.use('/api', router), req.path perd le préfixe /api alors que req.originalUrl le garde (le routing Express explique le montage).

Erreurs fréquentes

Lire req.body dans une requête GET. Les navigateurs et la plupart des clients n'envoient pas de corps avec GET. Mettez les options d'un GET dans la query string.

Tester un flag de query comme un booléen. ?admin=false donne la chaîne 'false', qui est truthy, donc if (req.query.admin) passe. Comparez des chaînes : req.query.admin === 'true'.

Envoyer du JSON sans l'en-tête. Un client qui poste du JSON en text/plain obtient req.body === undefined. Définissez Content-Type: application/json côté client.