Express req.params, req.query und req.body erklärt

In Express enthält req.params die Werte benannter Segmente im Routenpfad (/users/:id ergibt req.params.id), req.query den Query-String nach dem ? (/search?q=node ergibt req.query.q) und req.body die Daten, die im Request-Body gesendet wurden. req.params und req.query sind bei jeder Anfrage gefüllt, aber req.body bleibt undefined, bis ein Body-Parser wie app.use(express.json()) ihn liest. Werte in params und query sind immer Strings.

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

Die erste Anfrage antwortet mit {"params":{"userId":"7"},"query":{"sort":"new","limit":"2"}}. Achte auf die Anführungszeichen: 7 und 2 sind Strings, wandle sie also mit Number() um, bevor du rechnest oder mit Zahlen vergleichst. Stell jetzt die Methode auf POST, lass den Pfad /users/7/posts und sende den Body {"title": "Hello", "draft": true}: Die Antwort ist 201 mit "body":{"title":"Hello","draft":true}, wobei true ein echter Boolean ist, weil er aus JSON kommt.

req.params vs. req.query vs. req.body

Eine Route kann mehrere Parameter haben, und jeder Name wird zu einem Schlüssel von req.params: /teams/:teamId/members/:memberId liefert beide IDs. Auch ein Bindestrich oder ein Punkt trennt sie, deshalb wird /flights/LAX-SFO mit /flights/:from-:to zu { from: 'LAX', to: 'SFO' }.

req.query mit doppelten und fehlenden Schlüsseln

Ein Schlüssel, der zweimal vorkommt, wird zu einem Array, und ein fehlender Schlüssel ist undefined, also gib Optionen einen Standardwert:

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

Die Antwort ist {"page":1,"tags":["red","sale"],"raw":{"tag":["red","sale"]}}. Sende GET /products?tag=red&page=3, und tags ist immer noch ein Array, ["red"], weil [].concat() aus einem String oder einem Array ein Array macht. Express 5 parst Query-Strings mit dem einfachen Parser von Node, ?filter[size]=m ergibt also den Schlüssel "filter[size]", kein verschachteltes Objekt; Express 4 hat es verschachtelt.

req.body braucht express.json()

Node liefert den Body als Stream von Bytes. express.json() liest ihn, parst ihn und setzt req.body, aber nur, wenn die Anfrage Content-Type: application/json hat. HTML-Formulare senden application/x-www-form-urlencoded, das stattdessen express.urlencoded() braucht.

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

Sende POST /signup mit dem Body {"email": "ada@example.com"}, und du bekommst 201 mit {"email":"ada@example.com","name":"anonymous"}. Sende einen leeren Body, und du bekommst 400. Das ?? {} ist wichtig: Ohne es wirft das Destructuring von undefined bei jeder Anfrage ohne JSON-Body einen TypeError. Für eine echte Prüfung von Form und Typen nimm eine Schema-Bibliothek wie zod.

req.headers und req.get()

req.headers ist ein Objekt mit allen Request-Headern, mit kleingeschriebenen Namen. req.get(name) liest einen Header und ignoriert Groß- und Kleinschreibung, req.get('Content-Type') und req.get('content-type') liefern also denselben Wert. Ein paar weitere Eigenschaften, die du brauchen wirst:

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 ist /whoami und originalUrl ist /whoami?debug=1. Füg in der Request-Leiste den Header Authorization: Bearer abc hinzu und sende noch einmal: token wird zu "Bearer abc". In einem Router, der mit app.use('/api', router) eingehängt ist, verliert req.path das Präfix /api, während req.originalUrl es behält (Express Routing erklärt das Einhängen).

Häufige Fehler

req.body bei einer GET-Anfrage lesen. Browser und die meisten Clients senden bei GET keinen Body. Pack GET-Optionen in den Query-String.

Ein Query-Flag auf Truthiness prüfen. ?admin=false ergibt den String 'false', der truthy ist, also geht if (req.query.admin) durch. Vergleich Strings: req.query.admin === 'true'.

JSON ohne den Header senden. Ein Client, der JSON als text/plain postet, bekommt req.body === undefined. Setz auf dem Client Content-Type: application/json.