req.params, req.query e req.body in Express spiegati

In Express, req.params contiene i valori dei segmenti con nome nel path della route (/users/:id dà req.params.id), req.query contiene la query string dopo il ? (/search?q=node dà req.query.q) e req.body contiene i dati inviati nel body della richiesta. req.params e req.query vengono riempiti a ogni richiesta, ma req.body resta undefined finché un body parser come app.use(express.json()) non lo legge. I valori di params e query sono sempre stringhe.

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 prima richiesta risponde {"params":{"userId":"7"},"query":{"sort":"new","limit":"2"}}. Nota le virgolette: 7 e 2 sono stringhe, quindi convertile con Number() prima di fare calcoli o confronti con numeri. Ora cambia il metodo in POST, lascia il path /users/7/posts e invia il body {"title": "Hello", "draft": true}: la risposta è 201 con "body":{"title":"Hello","draft":true}, dove true è un vero booleano perché arriva dal JSON.

req.params, req.query e req.body a confronto

Una route può avere più parametri, e ogni nome diventa una chiave di req.params: /teams/:teamId/members/:memberId dà entrambi gli id. Anche un trattino o un punto li separano, quindi /flights/:from-:to trasforma /flights/LAX-SFO in { from: 'LAX', to: 'SFO' }.

req.query con chiavi ripetute o mancanti

Una chiave che compare due volte diventa un array, e una chiave che manca è undefined, quindi dai un valore di default alle opzioni:

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 risposta è {"page":1,"tags":["red","sale"],"raw":{"tag":["red","sale"]}}. Invia GET /products?tag=red&page=3 e tags è comunque un array, ["red"], perché [].concat() trasforma sia una stringa sia un array in un array. Express 5 analizza le query string con il parser semplice di Node, quindi ?filter[size]=m dà la chiave "filter[size]", non un oggetto annidato; Express 4 lo annidava.

req.body ha bisogno di express.json()

Node consegna il body come uno stream di byte. express.json() lo legge, lo analizza e imposta req.body, ma solo quando la richiesta ha Content-Type: application/json. I form HTML inviano application/x-www-form-urlencoded, che richiede invece 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);

Invia POST /signup con il body {"email": "ada@example.com"} e ottieni 201 con {"email":"ada@example.com","name":"anonymous"}. Invia un body vuoto e ottieni 400. Il ?? {} è importante: senza, destrutturare undefined lancia un TypeError su ogni richiesta senza body JSON. Per validare davvero forma e tipi, usa una libreria di schemi come zod.

req.headers e req.get()

req.headers è un oggetto con tutti gli header della richiesta, con i nomi in minuscolo. req.get(name) legge un header ignorando maiuscole e minuscole, quindi req.get('Content-Type') e req.get('content-type') restituiscono lo stesso valore. Qualche altra proprietà che userai:

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 è /whoami e originalUrl è /whoami?debug=1. Aggiungi l'header Authorization: Bearer abc nella barra della richiesta e inviala di nuovo: token diventa "Bearer abc". Dentro un router montato con app.use('/api', router), req.path perde il prefisso /api mentre req.originalUrl lo mantiene (il routing di Express spiega il montaggio).

Errori comuni

Leggere req.body in una richiesta GET. I browser e la maggior parte dei client non inviano un body con GET. Metti le opzioni di una GET nella query string.

Controllare un flag della query come se fosse un booleano. ?admin=false dà la stringa 'false', che è truthy, quindi if (req.query.admin) passa. Confronta stringhe: req.query.admin === 'true'.

Inviare JSON senza l'header. Un client che invia JSON come text/plain ottiene req.body === undefined. Imposta Content-Type: application/json sul client.