Rotas no Express e express.Router: parâmetros e prefixos

O roteamento no Express liga um método HTTP e um caminho a uma função handler: app.get('/users', handler) responde requisições GET para /users, e app.post(), app.put() e app.delete() fazem o mesmo para os outros métodos. Um segmento que começa com dois pontos, como em /users/:id, é um parâmetro de rota, e o valor dele vai para req.params. Para manter um app em crescimento organizado, coloque rotas relacionadas em um express.Router() e monte com um prefixo usando 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 responde {"id":2,"name":"Linus"}. Parâmetros de rota são sempre strings, por isso o handler compara com Number(req.params.id). Envie POST /users com o body {"name": "Grace"} para receber 201, depois DELETE /users/1 e GET /users para ver a lista mudar.

express.Router() com prefixo

Um router é um mini app com rotas e middleware próprios. Os caminhos dele são relativos: uma rota escrita como /:id dentro de um router montado em /api/books responde /api/books/:id. Em um projeto real cada router fica no próprio arquivo e termina com 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 retorna {"id":1,"title":"Dune"}. router.route('/:id') escreve o caminho uma vez e encadeia um handler por método; envie PUT /api/books/1 e você recebe {"updated":"1"}. Mude o caminho de montagem para /v2/books e o mesmo router passa a responder ali.

Ordem das rotas: o primeiro match ganha

O Express testa as rotas na ordem em que você as registra e para na primeira que envia uma resposta. Uma rota com parâmetro pega qualquer coisa naquela posição, então um caminho fixo registrado depois dela nunca é alcançado:

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 responde {"route":"/users/:id","id":"new"}: a rota com parâmetro foi registrada primeiro e ficou com a requisição. Mova a rota /users/new para cima de /users/:id e rode de novo para receber {"route":"/users/new"}. Depois envie GET /books para chegar ao handler 404 no final.

O handler 404

O Express responde uma requisição sem rota correspondente com a própria página HTML, Cannot GET /books. Para uma API você normalmente quer JSON, então adicione um app.use() sem caminho como a última rota de todas, como no bloco acima. Ele só roda quando todas as rotas anteriores deixaram a requisição passar. Erros lançados pelos handlers são outro caso, com um handler próprio de quatro argumentos, explicado em tratamento de erros no Express.

Caminhos de rota no Express 5

O Express 5 mudou a sintaxe dos caminhos, e a maioria dos trechos de código na internet foi escrita para o Express 4:

Um * sozinho ou um ? depois de um parâmetro lança TypeError quando a rota é registrada, então o app não sobe.

Erros comuns

Registrar o handler 404 primeiro. app.use() sem caminho casa com tudo, então toda requisição recebe o 404. Deixe ele no final.

Esquecer que o prefixo é removido. Dentro de um router montado em /api, req.path não inclui /api. Use req.originalUrl quando precisar do caminho completo.

Comparar um parâmetro com um número. req.params.id === 1 é sempre falso, porque req.params.id é a string '1'.