Express Router und Routing: Routen, Parameter, Präfixe

Routing in Express ordnet einer HTTP-Methode und einem Pfad eine Handler-Funktion zu: app.get('/users', handler) beantwortet GET-Anfragen an /users, und app.post(), app.put() und app.delete() machen dasselbe für die anderen Methoden. Ein Segment, das mit einem Doppelpunkt beginnt, wie in /users/:id, ist ein Routenparameter, dessen Wert in req.params landet. Damit eine wachsende App übersichtlich bleibt, packst du zusammengehörige Routen in einen express.Router() und hängst ihn mit app.use('/api', router) unter einem Präfix ein.

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

const users = [
    { id: 1, name: 'Ada' },
    { id: 2, name: 'Linus' },
];
let nextId = 3;

app.get('/users', (req, res) => {
    res.json(users);
});

// GET /users/2
app.get('/users/:id', (req, res) => {
    const user = users.find((u) => u.id === Number(req.params.id));
    if (!user) return res.status(404).json({ error: 'User not found' });
    res.json(user);
});

app.post('/users', (req, res) => {
    const user = { id: nextId++, name: req.body.name };
    users.push(user);
    res.status(201).json(user);
});

app.delete('/users/:id', (req, res) => {
    const index = users.findIndex((u) => u.id === Number(req.params.id));
    if (index === -1) return res.status(404).json({ error: 'User not found' });
    users.splice(index, 1);
    res.status(204).end();
});

app.listen(3000);

GET /users/2 antwortet mit {"id":2,"name":"Linus"}. Routenparameter sind immer Strings, deshalb vergleicht der Handler mit Number(req.params.id). Sende POST /users mit dem Body {"name": "Grace"}, um 201 zu bekommen, dann DELETE /users/1 und GET /users, um zu sehen, wie sich die Liste ändert.

express.Router() mit Präfix

Ein Router ist eine Mini-App mit eigenen Routen und eigener Middleware. Seine Pfade sind relativ: Eine Route /:id in einem Router, der unter /api/books eingehängt ist, beantwortet /api/books/:id. In einem echten Projekt steht jeder Router in einer eigenen Datei und endet mit module.exports = router.

const express = require('express');

// routes/books.js
const books = express.Router();
const list = [{ id: 1, title: 'Dune' }];

books.get('/', (req, res) => {
    res.json(list);
});

books
    .route('/:id')
    .get((req, res) => {
        res.json(list.find((b) => b.id === Number(req.params.id)) ?? null);
    })
    .put((req, res) => {
        res.json({ updated: req.params.id });
    })
    .delete((req, res) => {
        res.json({ deleted: req.params.id });
    });

// server.js
const app = express();
app.use('/api/books', books);

// GET /api/books/1
app.listen(3000);

GET /api/books/1 liefert {"id":1,"title":"Dune"}. router.route('/:id') schreibt den Pfad einmal und hängt pro Methode einen Handler an; sende PUT /api/books/1, und du bekommst {"updated":"1"}. Ändere den Einhängepfad in /v2/books, und derselbe Router antwortet stattdessen dort.

Reihenfolge der Routen: Der erste Treffer gewinnt

Express probiert Routen in der Reihenfolge, in der du sie registrierst, und hört bei der ersten auf, die eine Antwort sendet. Eine Parameter-Route fängt alles an ihrer Position ab, ein fester Pfad, der danach registriert wird, wird also nie erreicht:

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

app.get('/users/:id', (req, res) => {
    res.json({ route: '/users/:id', id: req.params.id });
});

app.get('/users/new', (req, res) => {
    res.json({ route: '/users/new' });
});

// Runs only when no route above answered.
app.use((req, res) => {
    res.status(404).json({ error: `Cannot ${req.method} ${req.path}` });
});

// GET /users/new
app.listen(3000);

GET /users/new antwortet mit {"route":"/users/:id","id":"new"}: Die Parameter-Route wurde zuerst registriert und hat die Anfrage übernommen. Schieb die Route /users/new über /users/:id und führ es noch einmal aus, um {"route":"/users/new"} zu bekommen. Sende dann GET /books, um den 404-Handler ganz unten zu erreichen.

Der 404-Handler

Express beantwortet eine Anfrage ohne passende Route mit seiner eigenen HTML-Seite, Cannot GET /books. Für eine API willst du meist JSON, also füg wie im Block oben ein app.use() ohne Pfad als allerletzte Route hinzu. Es läuft nur, wenn jede Route davor die Anfrage weitergereicht hat. Fehler, die Handler werfen, sind ein anderer Fall mit einem eigenen Handler mit vier Argumenten, beschrieben unter Express Error Handling.

Routenpfade in Express 5

Express 5 hat die Pfadsyntax geändert, und die meisten Snippets im Netz sind für Express 4 geschrieben:

Ein einzelnes * oder ein ? nach einem Parameter wirft beim Registrieren der Route einen TypeError, die App startet also nicht.

Häufige Fehler

Den 404-Handler zuerst registrieren. app.use() ohne Pfad passt auf alles, also bekommt jede Anfrage die 404. Lass ihn ganz unten.

Vergessen, dass das Präfix entfernt wird. In einem Router, der unter /api eingehängt ist, enthält req.path kein /api. Nimm req.originalUrl, wenn du den vollständigen Pfad brauchst.

Einen Parameter mit einer Zahl vergleichen. req.params.id === 1 ist immer false, weil req.params.id der String '1' ist.