Навигация

Express и middleware

Express остаётся самым распространённым фреймворком для Node-бэкенда, и почти весь его код — это небольшие функции, которые по очереди обрабатывают запрос. За кажущейся простотой скрываются жёсткие правила: кто вызывает следующего, где заканчивается цепочка и почему ошибка из async-функции иногда не доходит до обработчика. Разберём, как Express устроен поверх node:http, как работает конвейер middleware и как из него собрать структуру, которую не страшно поддерживать.

Содержание

  1. Что Express добавляет к node:http
  2. Приложение, маршрут и обработчик
  3. Middleware: конвейер запроса
  4. next() и порядок регистрации
  5. Router и монтирование
  6. Параметры, query и body
  7. Обработка ошибок: четыре аргумента
  8. Асинхронные ошибки в Express 4 и 5
  9. express.json(), лимиты и статика
  10. Практика: TaskFlow на Express
  11. Слои: routes, controllers, services
  12. Частые ошибки
  13. Ключевые тезисы для интервью
  14. Заключение
  15. Полезные ссылки

Что 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.methodHTTP-запросвсегда в верхнем регистре
req.pathпуть без queryвычисляется из req.url
req.paramsпараметры маршрутавсегда строки
req.queryquery-строкав 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,     // только объекты и массивы, без примитивов
}));
ОпцияПо умолчаниюЗачем менять
limit100kbбольше — только осознанно, под конкретный маршрут
stricttrueзапрещает "text" и 42 на верхнем уровне
typeapplication/jsonпринимать свой MIME-тип
inflatetrueподдержка 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.

Полезные ссылки