Middleware в Express: как работает next(), с примерами

Middleware в Express это функция с сигнатурой (req, res, next), которая выполняется между моментом, когда приходит запрос, и моментом, когда отправляется ответ. Каждый middleware может прочитать или изменить req и res, завершить запрос, отправив ответ, или вызвать next(), чтобы передать запрос следующей функции в очереди. app.use(fn) добавляет middleware для каждого запроса, и Express выполняет всё в том порядке, в котором вы это зарегистрировали.

const express = require('express');
const app = express();

function logger(req, res, next) {
    req.startedAt = Date.now();
    console.log('1. logger:', req.method, req.url);
    next();
}

app.use(logger);

app.use((req, res, next) => {
    console.log('2. second middleware');
    next();
});

app.get('/', (req, res) => {
    console.log('3. route handler');
    res.json({ ok: true, tookMs: Date.now() - req.startedAt });
});

app.listen(3000);

Для каждого запроса Console по порядку показывает три шага, а маршрут читает req.startedAt, свойство, которое добавил логгер. Отправьте GET /missing: оба middleware всё равно пишут в лог, потому что app.use() подходит для любого пути, а затем Express отвечает 404, так как ни один маршрут не совпал.

Забытый next()

Middleware, который не отправляет ответ и не вызывает next(), оставляет запрос висеть. Клиент ждёт до таймаута, а в логах ничего не появляется, поэтому это частая ошибка с middleware. Удалите next(); из logger выше и снова отправьте GET /: запрос так и не получит ответа.

Правило простое: каждый путь через middleware заканчивается ровно одним из этого:

• next(), чтобы продолжить,
• next(err), чтобы перейти к обработчику ошибок (см. Обработка ошибок в Express),
• ответ, например res.json() или res.status(401).send().

Вызов next() после отправки ответа тоже ошибка. Следующий обработчик пытается отправить второй ответ, и Express выбрасывает ERR_HTTP_HEADERS_SENT. Пишите return res.status(401).json(...), чтобы функция на этом остановилась.

Проверка авторизации, которая останавливает запрос

Middleware, который отклоняет запрос, сам отправляет ответ и никогда не вызывает next(). Передайте его маршруту дополнительным аргументом, чтобы защитить только этот маршрут:

const express = require('express');
const app = express();

function requireApiKey(req, res, next) {
    if (req.get('x-api-key') !== 'secret123') {
        return res.status(401).json({ error: 'Missing or wrong API key' });
    }
    req.client = 'reporting-app';
    next();
}

app.get('/public', (req, res) => {
    res.json({ message: 'Anyone can read this' });
});

app.get('/admin/stats', requireApiKey, (req, res) => {
    res.json({ users: 42, caller: req.client });
});

// GET /admin/stats
app.listen(3000);

Первый запрос получает 401 с {"error":"Missing or wrong API key"}. Добавьте в строке запроса заголовок x-api-key: secret123 и отправьте снова: теперь ответ {"users":42,"caller":"reporting-app"}. На /public проверка не выполняется никогда.

Где выполняется middleware

Порядок входит в смысл. Логгер, зарегистрированный после маршрутов, никогда не запишет запросы, на которые эти маршруты ответили, потому что маршрут, отправивший ответ, не вызывает next(). Сначала регистрируйте middleware для всего приложения, такие как логирование, разбор тела и CORS, затем маршруты, затем обработчики 404 и ошибок.

Встроенные middleware

В Express есть несколько функций middleware, которые подключаются через app.use(). Парсеры тела заполняют req.body; без них там undefined.

const express = require('express');
const app = express();

app.use(express.json());
app.use(express.urlencoded());

app.get('/', (req, res) => {
    res.send('Send POST /echo with a body');
});

app.post('/echo', (req, res) => {
    res.json({ type: req.get('content-type'), body: req.body });
});

app.listen(3000);

Отправьте POST /echo с телом {"name": "Ada"}, и в ответе будет "body":{"name":"Ada"}. Удалите строку с express.json(), отправьте снова, и body в ответе пропадёт: req.body равен undefined, а JSON.stringify выбрасывает значения undefined. Пакеты cors, helmet и morgan тоже middleware: вы ставите их через npm install и так же передаёте в app.use(). Отдачу файлов описывает страница про express.static.

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

Вызов middleware вместо передачи. app.use(logger()) выполняет logger один раз при запуске и регистрирует то, что он вернул. Пишите app.use(logger). (У express.json() есть скобки, потому что он возвращает функцию middleware.)

Парсер тела добавлен после маршрутов. Маршруты выполняются первыми и видят req.body как undefined.

Ожидание, что app.use('/admin', fn) совпадает с одним путём. Он срабатывает и для /admin/users, и для любого другого пути под /admin, для всех методов. Чтобы защитить один маршрут, передайте middleware в app.get('/admin', fn, handler).