Express Router e routing: route, parametri e prefissi

Il routing in Express associa un metodo HTTP e un path a una funzione handler: app.get('/users', handler) risponde alle richieste GET su /users, e app.post(), app.put() e app.delete() fanno lo stesso per gli altri metodi. Un segmento che inizia con i due punti, come in /users/:id, è un parametro di route il cui valore finisce in req.params. Per tenere in ordine un'app che cresce, metti le route correlate in un express.Router() e montalo sotto un prefisso con 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 risponde {"id":2,"name":"Linus"}. I parametri di route sono sempre stringhe, per questo l'handler confronta con Number(req.params.id). Invia POST /users con il body {"name": "Grace"} per ottenere 201, poi DELETE /users/1 e GET /users per vedere la lista cambiare.

express.Router() con un prefisso

Un router è una mini app con le sue route e i suoi middleware. I suoi path sono relativi: una route scritta come /:id dentro un router montato su /api/books risponde a /api/books/:id. In un progetto vero ogni router sta nel suo file e finisce con 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 restituisce {"id":1,"title":"Dune"}. router.route('/:id') scrive il path una volta e concatena un handler per metodo; invia PUT /api/books/1 e ottieni {"updated":"1"}. Cambia il path di montaggio in /v2/books e lo stesso router risponde lì.

Ordine delle route: vince la prima che corrisponde

Express prova le route nell'ordine in cui le registri e si ferma alla prima che invia una risposta. Una route con parametro cattura qualsiasi cosa in quella posizione, quindi un path fisso registrato dopo non viene mai raggiunto:

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 risponde {"route":"/users/:id","id":"new"}: la route con parametro è stata registrata prima e l'ha presa lei. Sposta la route /users/new sopra /users/:id ed esegui di nuovo per ottenere {"route":"/users/new"}. Poi invia GET /books per arrivare all'handler 404 in fondo.

L'handler 404

Express risponde a una richiesta senza route corrispondente con la sua pagina HTML, Cannot GET /books. Per un'API di solito vuoi JSON, quindi aggiungi un app.use() senza path come ultimissima route, come nel blocco qui sopra. Viene eseguito solo quando tutte le route precedenti hanno lasciato passare la richiesta. Gli errori lanciati dagli handler sono un caso diverso, con il loro handler a quattro argomenti, trattato in gestione degli errori in Express.

I path delle route in Express 5

Express 5 ha cambiato la sintassi dei path, e la maggior parte degli snippet che trovi online è scritta per Express 4:

Un * da solo o un ? dopo un parametro lancia un TypeError quando la route viene registrata, quindi l'app non parte.

Errori comuni

Registrare per primo l'handler 404. app.use() senza path corrisponde a tutto, quindi ogni richiesta riceve il 404. Tienilo in fondo.

Dimenticare che il prefisso viene tolto. Dentro un router montato su /api, req.path non include /api. Usa req.originalUrl quando ti serve il path completo.

Confrontare un parametro con un numero. req.params.id === 1 è sempre falso perché req.params.id è la stringa '1'.