Express Router i routing: trasy, parametry, prefiksy

Routing w Express przypisuje metodę HTTP i ścieżkę do funkcji handlera: app.get('/users', handler) odpowiada na żądania GET do /users, a app.post(), app.put() i app.delete() robią to samo dla innych metod. Segment zaczynający się od dwukropka, jak w /users/:id, to parametr trasy, którego wartość trafia do req.params. Żeby rosnąca aplikacja nie zamieniła się w bałagan, umieszczaj powiązane trasy w express.Router() i podpinaj go pod prefiks przez 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 odpowiada {"id":2,"name":"Linus"}. Parametry trasy to zawsze stringi, dlatego handler porównuje z Number(req.params.id). Wyślij POST /users z body {"name": "Grace"}, żeby dostać 201, a potem DELETE /users/1 i GET /users, żeby zobaczyć, jak zmienia się lista.

express.Router() z prefiksem

Router to mini aplikacja z własnymi trasami i middleware. Jego ścieżki są względne: trasa zapisana jako /:id w routerze podpiętym pod /api/books odpowiada na /api/books/:id. W prawdziwym projekcie każdy router siedzi w osobnym pliku i kończy się 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 zwraca {"id":1,"title":"Dune"}. router.route('/:id') zapisuje ścieżkę raz i łączy po jednym handlerze na metodę; wyślij PUT /api/books/1, a dostaniesz {"updated":"1"}. Zmień ścieżkę podpięcia na /v2/books, a ten sam router odpowie tam.

Kolejność tras: wygrywa pierwsze dopasowanie

Express sprawdza trasy w kolejności rejestracji i zatrzymuje się na pierwszej, która wyśle odpowiedź. Trasa z parametrem łapie wszystko na swojej pozycji, więc stała ścieżka zarejestrowana po niej nigdy nie zostanie osiągnięta:

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 odpowiada {"route":"/users/:id","id":"new"}: trasa z parametrem była zarejestrowana pierwsza i przejęła żądanie. Przenieś trasę /users/new nad /users/:id i uruchom ponownie, żeby dostać {"route":"/users/new"}. Potem wyślij GET /books, żeby trafić do handlera 404 na samym dole.

Handler 404

Na żądanie bez pasującej trasy Express odpowiada własną stroną HTML, Cannot GET /books. W API zwykle chcesz JSON, więc dodaj app.use() bez ścieżki jako ostatnią trasę, jak w bloku powyżej. Wykonuje się tylko wtedy, gdy każda wcześniejsza trasa przepuściła żądanie dalej. Błędy rzucane przez handlery to inna sprawa, z własnym handlerem z czterema argumentami, opisanym w obsłudze błędów w Express.

Ścieżki tras w Express 5

Express 5 zmienił składnię ścieżek, a większość fragmentów kodu w sieci jest napisana pod Express 4:

Samo * albo ? po parametrze rzuca TypeError przy rejestracji trasy, więc aplikacja się nie uruchomi.

Częste błędy

Rejestrowanie handlera 404 jako pierwszego. app.use() bez ścieżki pasuje do wszystkiego, więc każde żądanie dostaje 404. Trzymaj go na samym dole.

Zapominanie, że prefiks jest usuwany. W routerze podpiętym pod /api req.path nie zawiera /api. Użyj req.originalUrl, gdy potrzebujesz pełnej ścieżki.

Porównywanie parametru z liczbą. req.params.id === 1 zawsze daje false, bo req.params.id to string '1'.