Express Router et routing : routes, paramètres, préfixes

Le routing dans Express associe une méthode HTTP et un chemin à une fonction handler : app.get('/users', handler) répond aux requêtes GET sur /users, et app.post(), app.put() et app.delete() font de même pour les autres méthodes. Un segment qui commence par deux-points, comme dans /users/:id, est un paramètre de route dont la valeur arrive dans req.params. Pour garder une application qui grandit en ordre, placez les routes liées dans un express.Router() et montez-le sous un préfixe avec app.use('/api', router).

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 répond {"id":2,"name":"Linus"}. Les paramètres de route sont toujours des chaînes, c'est pourquoi le handler compare avec Number(req.params.id). Envoyez POST /users avec le corps {"name": "Grace"} pour obtenir 201, puis DELETE /users/1 et GET /users pour voir la liste changer.

express.Router() avec un préfixe

Un router est une mini-application avec ses propres routes et middlewares. Ses chemins sont relatifs : une route écrite /:id dans un router monté sur /api/books répond à /api/books/:id. Dans un vrai projet, chaque router vit dans son propre fichier et se termine par 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 renvoie {"id":1,"title":"Dune"}. router.route('/:id') écrit le chemin une seule fois et enchaîne un handler par méthode ; envoyez PUT /api/books/1 et vous obtenez {"updated":"1"}. Remplacez le chemin de montage par /v2/books et le même router y répond à la place.

L'ordre des routes : la première qui correspond gagne

Express essaie les routes dans l'ordre d'enregistrement et s'arrête à la première qui envoie une réponse. Une route à paramètre attrape tout ce qui se trouve à sa position, donc un chemin fixe enregistré après elle n'est jamais atteint :

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 répond {"route":"/users/:id","id":"new"} : la route à paramètre a été enregistrée en premier et l'a prise. Déplacez la route /users/new au-dessus de /users/:id et relancez pour obtenir {"route":"/users/new"}. Envoyez ensuite GET /books pour atteindre le handler 404 tout en bas.

Le handler 404

Express répond à une requête sans route correspondante avec sa propre page HTML, Cannot GET /books. Pour une API, on veut en général du JSON, donc ajoutez un app.use() sans chemin comme toute dernière route, comme dans le bloc ci-dessus. Il ne s'exécute que si toutes les routes précédentes ont laissé passer la requête. Les erreurs levées par les handlers sont un autre cas, avec leur propre handler à quatre arguments, présenté dans la gestion des erreurs Express.

Les chemins de route dans Express 5

Express 5 a changé la syntaxe des chemins, et la plupart des extraits de code en ligne sont écrits pour Express 4 :

Un * seul ou un ? après un paramètre lève une TypeError à l'enregistrement de la route, donc l'application ne démarre pas.

Erreurs fréquentes

Enregistrer le handler 404 en premier. app.use() sans chemin correspond à tout, donc toutes les requêtes reçoivent le 404. Gardez-le tout en bas.

Oublier que le préfixe est retiré. Dans un router monté sur /api, req.path n'inclut pas /api. Utilisez req.originalUrl quand vous avez besoin du chemin complet.

Comparer un paramètre avec un nombre. req.params.id === 1 est toujours faux, car req.params.id est la chaîne '1'.