Express и middleware
Express остаётся самым распространённым фреймворком для Node-бэкенда, и почти весь его код — это небольшие функции, которые по очереди обрабатывают запрос. За кажущейся простотой скрываются жёсткие правила: кто вызывает следующего, где заканчивается цепочка и почему ошибка из async-функции иногда не доходит до обработчика. Разберём, как Express устроен поверх node:http, как работает конвейер middleware и как из него собрать структуру, которую не страшно поддерживать.
Содержание
- Что Express добавляет к node:http
- Приложение, маршрут и обработчик
- Middleware: конвейер запроса
- next() и порядок регистрации
- Router и монтирование
- Параметры, query и body
- Обработка ошибок: четыре аргумента
- Асинхронные ошибки в Express 4 и 5
- express.json(), лимиты и статика
- Практика: TaskFlow на Express
- Слои: routes, controllers, services
- Частые ошибки
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Что Express добавляет к node:http
В статье «HTTP-сервер на чистом Node» сервер собирался из пары стримов и ручных решений: разбор req.url, чтение тела с лимитом, таблица маршрутов, обработка 404 и обёртка try/catch вокруг каждого обработчика. Express не отменяет эти задачи, а прячет их за четырьмя идеями:
- маршрутизация — метод и путь описываются декларативно, параметры пути разбираются автоматически;
- middleware — общая логика (логирование, тело, аутентификация) выносится в отдельные слои;
- расширенные
reqиres—req.params,req.query,req.body,res.json(),res.status(); - единая обработка ошибок — исключение из любого слоя попадает в один error middleware.
При этом Express остаётся тонкой надстройкой: app.listen() возвращает обычный http.Server, req и res — те же IncomingMessage и ServerResponse, а keep-alive, таймауты сокетов и TLS по-прежнему настраиваются на уровне Node. Поэтому проблемы из предыдущей статьи — забытый res.end(), огромное тело, keepAliveTimeout меньше прокси — в Express никуда не исчезают.
Важно и то, чего Express не делает. Он не валидирует данные, не ограничивает бизнес-правила, не управляет транзакциями и не защищает от всех атак. express.json() разбирает тело, но не проверяет поля; res.json() сериализует объект, но не гарантирует его форму. Всё, что касается контракта API, остаётся задачей приложения.
Приложение, маршрут и обработчик
Приложение создаётся вызовом express(), а маршрут — методом, названным по HTTP-методу:
import express from 'express';
const app = express();
app.get('/health', (req, res) => {
res.json({ ok: true });
});
app.post('/tasks', (req, res) => {
res.status(201).json({ id: 1, title: 'первая задача' });
});
app.listen(3000, () => console.log('http://localhost:3000'));
Обработчик маршрута — обычная функция (req, res, next). Внутри неё доступны:
| Что | Откуда | Особенность |
|---|---|---|
req.method | HTTP-запрос | всегда в верхнем регистре |
req.path | путь без query | вычисляется из req.url |
req.params | параметры маршрута | всегда строки |
req.query | query-строка | в Express 5 парсер simple |
req.body | парсер тела | undefined, если тело не разобрано |
res.status(code) | Express | в Express 5 принимает только 100–999 |
res.json(obj) | Express | ставит content-type и вызывает end() |
res.json() и res.send() завершают ответ. После них нельзя вызывать next() «на всякий случай»: следующий слой попытается отправить второй ответ и получит ERR_HTTP_HEADERS_SENT. Если обработчик только подготавливает данные, он вызывает next(), а не пишет в res.
Express 5 требует Node.js 18+ и поменял часть сигнатур: res.send(obj, status) и res.json(obj, status) удалены, порядок аргументов res.redirect(status, url) изменился, а req.param(name) больше нет. Код из старых туториалов может не запуститься — при обновлении стоит свериться с гайдом миграции.
Middleware: конвейер запроса
Middleware — это функция с той же сигнатурой, которую Express вызывает до обработчика маршрута. Она может прочитать запрос, изменить req/res, ответить или передать управление дальше:
function requestId(req, res, next) {
req.id = crypto.randomUUID();
res.setHeader('x-request-id', req.id);
next(); // без этого запрос остановится
}
app.use(requestId);
app.use() подключает слой ко всем методам и путям, начинающимся с указанного префикса. app.use('/admin', auth) сработает и на /admin, и на /admin/users/42, а app.get('/admin') совпадает только с точным путём.
Типичный конвейер API выглядит так:
app.use(express.json({ limit: '100kb' })); // 1. тело
app.use(requestId); // 2. контекст запроса
app.use(requestLogger); // 3. лог
app.use('/tasks', authenticate); // 4. доступ
app.use('/tasks', tasksRouter); // 5. маршруты
app.use(notFound); // 6. 404
app.use(errorHandler); // 7. ошибки
Порядок здесь — не стилистика, а логика. Парсер тела должен стоять до маршрутов, которым нужен req.body. Аутентификация — до защищённых маршрутов, но после парсера, если ей нужен токен из тела. notFound — после всех маршрутов, иначе он перехватит запросы, до которых ещё не дошла очередь. Error middleware — строго последним.
Middleware бывает трёх видов:
- глобальный —
app.use(fn), выполняется для каждого запроса; - привязанный к префиксу —
app.use('/api', fn); - маршрутный —
app.get('/tasks', auth, listTasks), только для конкретного маршрута.
Один слой должен решать одну задачу. Функция, которая одновременно парсит тело, проверяет токен и логирует, плохо тестируется и непредсказуемо влияет на следующие слои.
next() и порядок регистрации
next() — единственный способ передать управление следующему слою. Без него Express считает, что middleware взял запрос на себя, и ждёт ответа. Если ответа нет, клиент висит до таймаута:
app.use((req, res, next) => {
if (!req.headers.authorization) {
return res.status(401).json({ error: 'unauthorized' });
}
next(); // обязателен: иначе следующий слой не запустится
});
У next() есть три режима:
| Вызов | Что происходит |
|---|---|
next() | следующий обычный middleware или обработчик |
next(err) | пропуск обычных слоёв, переход к error middleware |
next('route') | пропуск оставшихся обработчиков текущего маршрута |
next('route') работает только внутри обработчиков app.METHOD() и router.METHOD(), а не в app.use(). Практический сценарий — несколько альтернативных обработчиков одного пути: если первый решил, что не подходит, он пропускает остальные и переходит к следующему определению маршрута.
Порядок регистрации определяет и то, какие данные увидит слой. Если requestId подключён после логгера, логгер не увидит req.id. Если express.json() стоит после маршрута POST /tasks, обработчик получит req.body === undefined. Такие ошибки не падают при старте — они проявляются как «поле приходит пустым» или «заголовка нет в логах».
Отдельная ловушка — middleware, который вызывает next() после отправки ответа:
app.use((req, res, next) => {
res.json({ ok: true });
next(); // ошибка: ответ уже отправлен, следующий слой попробует ещё раз
});
Express не запрещает такой код на уровне API, но второй ответ приводит к ERR_HTTP_HEADERS_SENT. Правило простое: либо ответ, либо next() — не оба.
Router и монтирование
Router — это мини-приложение с собственными маршрутами и middleware. Он нужен, чтобы не держать все маршруты в одном файле и подключать общие проверки к группе путей:
import { Router } from 'express';
const tasksRouter = Router();
tasksRouter.get('/', listTasks);
tasksRouter.get('/:id', getTask);
tasksRouter.post('/', createTask);
tasksRouter.patch('/:id', updateTask);
export { tasksRouter };
app.use('/tasks', tasksRouter);
После монтирования внутри роутера меняется картина URL:
| Свойство | Значение для запроса GET /tasks/42?fields=title |
|---|---|
req.originalUrl | /tasks/42?fields=title |
req.baseUrl | /tasks |
req.url | /42?fields=title |
req.params.id | '42' |
Это важно при построении ссылок и логировании: req.url внутри роутера — не полный путь. Для логов и метрик берут req.originalUrl или req.baseUrl + req.path.
Параметры родительского маршрута по умолчанию не видны в дочернем роутере. Если маршрут /projects/:projectId/tasks монтирует вложенный роутер, ему нужен Router({ mergeParams: true }), иначе req.params.projectId будет undefined.
Роутер можно вкладывать сколько угодно глубоко, но у этого есть цена: чем больше слоёв, тем сложнее понять, какой middleware и в каком порядке выполнится для конкретного запроса. Практическое правило — один роутер на ресурс или на группу с общим префиксом, а не на каждый отдельный эндпоинт.
Параметры, query и body
Три источника данных приходят в разных местах и с разными типами:
app.get('/tasks/:id', (req, res) => {
req.params.id; // '42' — всегда строка
req.query.fields; // 'title' или массив при повторе ключа
req.get('authorization'); // заголовок, без учёта регистра
});
req.params разбирается из шаблона пути и всегда содержит строки. Числовой id нужно приводить явно и проверять: Number('abc') даст NaN, а Number('') — 0. В Express 5 параметры wildcard-пути (*splat) приходят массивом сегментов, а необязательные параметры при отсутствии просто исчезают из объекта.
req.query в Express 5 — геттер только для чтения, а парсер по умолчанию — simple. Он не строит вложенные объекты из a[b]=c, но повторяющиеся ключи (?tag=a&tag=b) превращает в массив. Если приложению нужен расширенный парсер, его задают явно через app.set('query parser', 'extended'), но для API обычно достаточно плоской структуры.
req.body появляется только после парсера и только если content-type совпал. В Express 5 неразобранное тело — это undefined, а не {}, поэтому req.body.title без проверки req.body бросает TypeError. Это ещё один аргумент за валидацию на границе: подробнее — в статье «Конфигурация и валидация».
app.post('/tasks', (req, res) => {
if (typeof req.body?.title !== 'string') {
return res.status(422).json({ error: 'title is required' });
}
// ...
});
Отдельно стоит помнить про app.set('trust proxy', ...). Без него req.ip показывает адрес прокси, req.protocol — http вместо https, а req.secure всегда false, даже если запрос пришёл по HTTPS. Доверять x-forwarded-* можно только после явной настройки количества прокси — иначе клиент подделает адрес и обойдёт rate limit.
Обработка ошибок: четыре аргумента
Express отличает error middleware по арности функции. Слой с тремя аргументами — обычный, с четырьмя — обработчик ошибок:
app.use((err, req, res, next) => {
if (res.headersSent) {
return next(err); // ответ уже начат: остаётся отдать дефолтному обработчику
}
const status = err.status ?? 500;
if (status >= 500) console.error({ err, requestId: req.id });
res.status(status).json({
error: status >= 500 ? 'internal error' : err.message,
});
});
Три правила, без которых обработка ошибок ломается:
- Error middleware регистрируют после маршрутов. Express ищет обработчик ошибок в том порядке, в котором слои добавлены. Если зарегистрировать его раньше, ошибки из последующих маршрутов до него не дойдут.
- Он должен быть последним. Если после него добавить обычный middleware, Express всё равно не станет вызывать его для ошибки, но порядок слоёв станет неочевидным.
- Ответ проверяют через
res.headersSent. Если заголовки уже ушли, менять статус нельзя — корректно передать ошибку дальше или оборвать соединение.
Ошибку в error middleware можно классифицировать по статусу. HttpError с полем status описывает ожидаемые случаи: 404 для ненайденной задачи, 422 для невалидного тела, 409 для конфликта. Всё остальное — 500, и наружу отдаётся одинаковый текст, а детали уходят в лог. Клиенту не нужен стек и текст ошибки базы.
export class HttpError extends Error {
constructor(status, message) {
super(message);
this.status = status;
}
}
Если error middleware сам вызывает next(err), управление переходит к следующему обработчику ошибок — вплоть до встроенного. Встроенный обработчик Express показывает стек только в режиме разработки, а в проде отдаёт общий Internal Server Error, поэтому в продакшене без своего обработчика теряется структура ответа и контекст запроса.
Асинхронные ошибки в Express 4 и 5
Разница между версиями здесь принципиальная. Express 4 ловит только синхронные исключения: throw внутри обработчика он перехватывает сам, а отклонённый промис — нет.
// Express 4: ошибка не попадёт в error middleware
app.get('/tasks/:id', async (req, res) => {
const task = await findTask(req.params.id); // reject → unhandledRejection
res.json(task);
});
В Express 4 такой код нужно оборачивать:
const asyncHandler = (fn) => (req, res, next) =>
Promise.resolve(fn(req, res, next)).catch(next);
app.get('/tasks/:id', asyncHandler(async (req, res) => {
const task = await findTask(req.params.id);
res.json(task);
}));
Express 5 передаёт rejection в error middleware автоматически:
app.get('/tasks/:id', async (req, res) => {
const task = await findTask(req.params.id); // reject → next(err)
res.json(task);
});
Это снимает большую часть обёрток, но не все. Сторонние middleware, написанные под Express 4, могут возвращать промис без обработки; колбэк внутри setTimeout или EventEmitter живёт вне промиса и его ошибка всё равно станет uncaughtException; а ошибка после res.json() уже не изменит ответ. Асинхронность сама по себе не делает код безопасным — она лишь меняет место, где ошибка превращается в next(err).
Практическое следствие для миграции: тесты на ошибки async-маршрутов стоит прогнать отдельно. Код, который «работал» на Express 4 потому, что reject просто логировался, на Express 5 начнёт отдавать 500 — и это правильное поведение, но его нужно увидеть до продакшена.
express.json(), лимиты и статика
express.json() — встроенный парсер JSON. Он читает тело только при content-type: application/json, проверяет синтаксис и кладёт результат в req.body.
app.use(express.json({
limit: '100kb', // значение по умолчанию
strict: true, // только объекты и массивы, без примитивов
}));
| Опция | По умолчанию | Зачем менять |
|---|---|---|
limit | 100kb | больше — только осознанно, под конкретный маршрут |
strict | true | запрещает "text" и 42 на верхнем уровне |
type | application/json | принимать свой MIME-тип |
inflate | true | поддержка gzip/deflate/br |
Лимит — это защита от исчерпания памяти, а не от валидации. Тело в пределах лимита всё равно может содержать неверные поля, лишние ключи и вложенные структуры. Схему проверяют отдельно: zod, joi или самописная функция, но до бизнес-логики.
Ошибки парсера тоже нужно обрабатывать. Битый JSON даёт SyntaxError со status: 400, превышение лимита — entity.too.large со status: 413. Error middleware из предыдущего раздела превращает их в нормальный JSON-ответ, но только если он зарегистрирован после парсера.
Статика подключается отдельно:
app.use(express.static('public', {
maxAge: '1h',
dotfiles: 'ignore', // значение по умолчанию в Express 5
}));
express.static() умеет MIME-типы, ETag, диапазоны и защиту от выхода за пределы каталога. В Express 5 скрытые файлы и каталоги (.well-known, .env) по умолчанию не отдаются, а опции hidden и from заменены на dotfiles и root. Для API статика чаще не нужна вовсе: её отдаёт CDN или reverse proxy.
Практика: TaskFlow на Express
Вернёмся к серверу из статьи «HTTP-сервер на чистом Node». Там на чтение тела, маршруты и ошибки уходило около восьмидесяти строк. На Express тот же контракт собирается из готовых слоёв.
// src/errors.js
export class HttpError extends Error {
constructor(status, message) {
super(message);
this.status = status;
}
}
// src/routes/tasks.js
import { Router } from 'express';
import { randomUUID } from 'node:crypto';
import { HttpError } from '../errors.js';
export const tasksRouter = Router();
const tasks = [];
tasksRouter.get('/', (req, res) => {
const done = req.query.done;
const result = done === undefined
? tasks
: tasks.filter((task) => String(task.done) === done);
res.json(result);
});
tasksRouter.get('/:id', (req, res) => {
const task = tasks.find((item) => item.id === req.params.id);
if (!task) throw new HttpError(404, 'task not found');
res.json(task);
});
tasksRouter.post('/', (req, res) => {
const title = req.body?.title;
if (typeof title !== 'string' || title.trim() === '') {
throw new HttpError(422, 'title is required');
}
const task = { id: randomUUID(), title: title.trim(), done: false };
tasks.push(task);
res.status(201).json(task);
});
// src/app.js
import express from 'express';
import { tasksRouter } from './routes/tasks.js';
export const app = express();
app.disable('x-powered-by');
app.use(express.json({ limit: '16kb' }));
app.get('/health', (req, res) => res.json({ ok: true }));
app.use('/tasks', tasksRouter);
app.use((req, res) => {
res.status(404).json({ error: 'not found' });
});
app.use((err, req, res, next) => {
if (res.headersSent) return next(err);
const status = err.status ?? 500;
if (status >= 500) console.error(err);
res.status(status).json({
error: status >= 500 ? 'internal error' : err.message,
});
});
// src/server.js
import { app } from './app.js';
app.listen(3000, (error) => {
if (error) throw error;
console.log('http://localhost:3000');
});
Что изменилось по сравнению с ручным сервером:
- лимит тела,
content-typeи разбор JSON — в одной строкеexpress.json(); - параметры пути и query разбираются фреймворком;
404и500собираются в одном месте, а не в каждом обработчике;- синхронный
throwловится Express, а в Express 5 — ещё и rejection изasync; app.listen()возвращаетhttp.Server, поэтому таймауты и graceful shutdown настраиваются как раньше.
Что не изменилось: валидация полей, проверка прав, транзакции и защита от злоупотреблений по-прежнему на приложении. Фреймворк убрал boilerplate, но не взял на себя контракт API.
Слои: routes, controllers, services
Express не навязывает структуру, и именно поэтому в проектах появляются файлы на тысячу строк. Рабочее разделение обязанностей выглядит так:
src/
app.js сборка приложения: middleware, роутеры, ошибки
server.js listen, сигналы, graceful shutdown
routes/tasks.js пути и HTTP-методы
controllers/tasks.js разбор req → вызов сервиса → res
services/tasks.js бизнес-логика
repositories/ доступ к базе
middleware/ auth, request-id, error
errors.js HttpError и доменные ошибки
Route знает только URL и метод. Controller переводит HTTP в вызов сервиса: достаёт параметры, проверяет их наличие, выбирает статус ответа. Service не знает про req и res — он принимает обычные аргументы и возвращает данные или бросает доменную ошибку. Repository отвечает за запросы к базе. Такое разделение позволяет тестировать сервис без HTTP и поднимать приложение в тестах без реальной базы.
Граница проходит по вопросу «кто отвечает за формат». Контроллер решает, что вернуть клиенту; сервис — что сделать. Если сервис начинает принимать req и писать в res, он теряет переносимость и превращается в обработчик маршрута с другим именем.
Для маленького сервиса из пяти эндпоинтов такое дерево избыточно. Начинать можно с одного файла, но момент, когда в нём появляются authenticate, express.json, десять маршрутов и обработчик ошибок, — хороший сигнал разнести слои. Подробнее про слои и границы модулей — в статье «Архитектура Node-бэкенда».
Частые ошибки
- Middleware без
next()и без ответа. Запрос висит до таймаута, сокет занят. next()послеres.json(). Второй ответ иERR_HTTP_HEADERS_SENT.- Error middleware не последним. Ошибки из более поздних слоёв до него не доходят.
- Error middleware с тремя аргументами. Express считает его обычным слоем и не вызывает для ошибок.
async-обработчик без обёртки в Express 4. Rejection становитсяunhandledRejection, а не500.req.body.titleбез проверкиreq.body. В Express 5 неразобранное тело —undefined.- Лимит
express.json()по умолчанию и большие загрузки. Тело отклоняется с413там, где его ждали. - Валидация «на глаз» вместо схемы. Лишние поля и неверные типы доходят до базы.
app.use('/admin', ...)вместо точного пути. Middleware срабатывает и на вложенных маршрутах.req.urlв логах внутри роутера. В лог попадает обрезанный путь без префикса.trust proxyне настроен.req.ip— адрес прокси, rate limit обходится заголовком.x-powered-byвключён. Лишняя информация о стеке в каждом ответе.
Ключевые тезисы для интервью
- Express — конвейер middleware поверх
node:http: каждый слой получает(req, res, next)и обязан либо ответить, либо передать управление дальше. - Порядок регистрации — это порядок выполнения: парсер тела и аутентификация до маршрутов,
404после них, error middleware последним. next(err)пропускает обычные слои и ищет обработчик с четырьмя аргументами; тот обязан проверитьres.headersSentи не светить внутренние детали в500.- Express 4 ловит только синхронные исключения, Express 5 — ещё и отклонённые промисы; обёртка
asyncHandlerостаётся нужна для старого кода и сторонних middleware. Routerизолирует маршруты и middleware: при монтированииreq.urlобрезается, префикс уходит вreq.baseUrl, а параметры родителя доступны только сmergeParams.express.json()разбирает тело и применяет лимит, но не валидирует данные;req.bodyв Express 5 равноundefined, пока парсер не сработал.- Express не отменяет правил
node:http: keep-alive, таймауты сокетов, TLS и reverse proxy настраиваются так же, как на чистом сервере.
Заключение
Express даёт три вещи: декларативные маршруты, конвейер middleware и единую точку обработки ошибок. Всё остальное — лимиты, валидация, права, транзакции — остаётся на приложении. Понимание порядка слоёв и того, как ошибка проходит через next(err), объясняет большинство «магических» багов: зависшие запросы, пустой req.body и 500, которые никто не логировал. Следующий шаг — Fastify и NestJS: те же задачи, но со схемами, плагинами и встроенным DI.
Полезные ссылки
- Express 5: Routing — маршруты, параметры и
Router - Express 5: Using middleware — виды middleware и порядок
- Express 5: Error handling — error middleware и асинхронные ошибки
- Migrating to Express 5 — изменения API и сигнатур
- Express 5: API reference —
req,res,appи опции - HTTP-сервер на чистом Node — что именно скрывает Express
- Стримы и backpressure — потоковая отдача ответа и
pipeline