Express: req.params, req.query i req.body wyjaśnione

W Express req.params zawiera wartości nazwanych segmentów ścieżki trasy (/users/:id daje req.params.id), req.query zawiera query string po ? (/search?q=node daje req.query.q), a req.body zawiera dane wysłane w body żądania. req.params i req.query są wypełniane przy każdym żądaniu, ale req.body zostaje undefined, dopóki nie odczyta go parser body, np. app.use(express.json()). Wartości w params i query to zawsze stringi.

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);

Pierwsze żądanie odpowiada {"params":{"userId":"7"},"query":{"sort":"new","limit":"2"}}. Zwróć uwagę na cudzysłowy: 7 i 2 to stringi, więc zamień je przez Number(), zanim zaczniesz liczyć albo porównywać z liczbami. Teraz zmień metodę na POST, zostaw ścieżkę /users/7/posts i wyślij body {"title": "Hello", "draft": true}: odpowiedź to 201 z "body":{"title":"Hello","draft":true}, gdzie true to prawdziwy boolean, bo przyszedł z JSON.

req.params vs req.query vs req.body

Trasa może mieć kilka parametrów, a każda nazwa staje się kluczem w req.params: /teams/:teamId/members/:memberId daje oba identyfikatory. Rozdziela je też myślnik lub kropka, więc /flights/:from-:to zamienia /flights/LAX-SFO w { from: 'LAX', to: 'SFO' }.

req.query z powtórzonymi i brakującymi kluczami

Klucz, który występuje dwa razy, staje się tablicą, a brakujący klucz to undefined, więc daj opcjom wartość domyślną:

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);

Odpowiedź to {"page":1,"tags":["red","sale"],"raw":{"tag":["red","sale"]}}. Wyślij GET /products?tag=red&page=3, a tags nadal jest tablicą, ["red"], bo [].concat() zamienia string albo tablicę w tablicę. Express 5 parsuje query stringi prostym parserem Node, więc ?filter[size]=m daje klucz "filter[size]", a nie zagnieżdżony obiekt; Express 4 go zagnieżdżał.

req.body wymaga express.json()

Node dostarcza body jako strumień bajtów. express.json() czyta go, parsuje i ustawia req.body, ale tylko wtedy, gdy żądanie ma Content-Type: application/json. Formularze HTML wysyłają application/x-www-form-urlencoded, do którego potrzebny jest 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);

Wyślij POST /signup z body {"email": "ada@example.com"}, a dostaniesz 201 z {"email":"ada@example.com","name":"anonymous"}. Wyślij puste body, a dostaniesz 400. ?? {} ma znaczenie: bez niego destrukturyzacja undefined rzuca TypeError przy każdym żądaniu bez body w JSON. Do prawdziwej walidacji kształtu i typów użyj biblioteki schematów, np. zod.

req.headers i req.get()

req.headers to obiekt ze wszystkimi nagłówkami żądania, z nazwami zapisanymi małymi literami. req.get(name) czyta jeden nagłówek i ignoruje wielkość liter, więc req.get('Content-Type') i req.get('content-type') zwracają tę samą wartość. Kilka innych właściwości, których będziesz używać:

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 to /whoami, a originalUrl to /whoami?debug=1. Dodaj w pasku żądania nagłówek Authorization: Bearer abc i wyślij jeszcze raz: token zmieni się na "Bearer abc". W routerze podpiętym przez app.use('/api', router) req.path traci prefiks /api, a req.originalUrl go zachowuje (routing w Express wyjaśnia podpinanie).

Częste błędy

Odczytywanie req.body w żądaniu GET. Przeglądarki i większość klientów nie wysyłają body z GET. Opcje dla GET umieszczaj w query stringu.

Sprawdzanie flagi z query jako wartości truthy. ?admin=false daje string 'false', który jest truthy, więc if (req.query.admin) przechodzi. Porównuj stringi: req.query.admin === 'true'.

Wysyłanie JSON bez nagłówka. Klient, który wysyła JSON jako text/plain, dostaje req.body === undefined. Ustaw Content-Type: application/json po stronie klienta.