Express Router и маршрутизация: маршруты, параметры

Маршрутизация в Express сопоставляет HTTP-метод и путь с функцией-обработчиком: app.get('/users', handler) отвечает на GET-запросы к /users, а app.post(), app.put() и app.delete() делают то же самое для других методов. Сегмент, начинающийся с двоеточия, как в /users/:id, это параметр маршрута, значение которого попадает в req.params. Чтобы растущее приложение оставалось в порядке, складывайте связанные маршруты в express.Router() и подключайте его под префиксом через 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 отвечает {"id":2,"name":"Linus"}. Параметры маршрута всегда строки, поэтому обработчик сравнивает с Number(req.params.id). Отправьте POST /users с телом {"name": "Grace"} и получите 201, затем DELETE /users/1 и GET /users, чтобы увидеть, как меняется список.

express.Router() с префиксом

Router это мини-приложение со своими маршрутами и middleware. Его пути относительные: маршрут /:id внутри router'а, подключённого на /api/books, отвечает на /api/books/:id. В настоящем проекте каждый router живёт в своём файле и заканчивается строкой 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 возвращает {"id":1,"title":"Dune"}. router.route('/:id') записывает путь один раз и цепочкой вешает по обработчику на каждый метод; отправьте PUT /api/books/1, и получите {"updated":"1"}. Поменяйте путь подключения на /v2/books, и тот же router будет отвечать там.

Порядок маршрутов: побеждает первое совпадение

Express пробует маршруты в том порядке, в котором вы их зарегистрировали, и останавливается на первом, который отправил ответ. Маршрут с параметром ловит всё на своей позиции, поэтому до фиксированного пути, зарегистрированного после него, дело не доходит:

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 отвечает {"route":"/users/:id","id":"new"}: маршрут с параметром зарегистрирован первым и забрал запрос. Перенесите маршрут /users/new выше /users/:id и запустите снова, чтобы получить {"route":"/users/new"}. Затем отправьте GET /books, чтобы попасть в обработчик 404 внизу.

Обработчик 404

На несовпавший запрос Express отвечает своей HTML-страницей Cannot GET /books. Для API обычно нужен JSON, поэтому добавьте app.use() без пути самым последним маршрутом, как в примере выше. Он выполняется, только если все маршруты до него передали запрос дальше. Ошибки, выброшенные обработчиками, это отдельный случай со своим обработчиком на четыре аргумента, о нём статья Обработка ошибок в Express.

Пути маршрутов в Express 5

В Express 5 изменился синтаксис путей, а большинство примеров в интернете написаны для Express 4:

Одиночная * или ? после параметра выбрасывает TypeError при регистрации маршрута, и приложение не запускается.

Частые ошибки

Обработчик 404 зарегистрирован первым. app.use() без пути совпадает со всем, поэтому каждый запрос получает 404. Держите его в самом низу.

Забыли, что префикс отрезается. Внутри router'а, подключённого на /api, req.path не содержит /api. Когда нужен полный путь, используйте req.originalUrl.

Сравнение параметра с числом. req.params.id === 1 всегда false, потому что req.params.id это строка '1'.