Пишем middleware: сигнатуры, next() и три модели фреймворков

Middleware, добавляющий request ID, работает идеально. Его копия, которая ещё и вызывает асинхронный аудит-лог, начинает кидать Cannot set headers after they are sent под нагрузкой — но лишь иногда. Баг не в вызове аудита. Он в том, что асинхронная ошибка ускользает из middleware, дефолтный обработчик фреймворка отвечает, а потом отвечает и исходный путь кода. Два ответа, один сокет. Контракт middleware нарушен самым частым способом из существующих.

Сигнатура Express

В Express middleware — это (req, res, next) => {}. У него ровно три законных окончания:

• Пропустить дальше — вызвать next(), чтобы передать управление следующему middleware.
• Завершить — отправить ответ (res.json(...), res.end()) и не вызывать next(). Это коротит цепочку.
• Упасть — вызвать next(err), чтобы перепрыгнуть к middleware обработки ошибок.

Два режима отказа — сделать оба (отправить ответ и вызвать next(), ведя к двойной отправке) или ни одного (нет ответа, нет next() — запрос висит до таймаута).

Error-middleware — другая форма

Express распознаёт middleware обработки ошибок по арности: оно должно объявлять четыре параметра, (err, req, res, next). Уберите неиспользуемый next — и Express сочтёт его обычным middleware и никогда не направит туда ошибки — тихий, бесящий баг. Error-middleware также должно быть зарегистрировано последним, после всех маршрутов, потому что цепочка достигает его лишь через next(err) из ранних слоёв.

Koa: асинхронная луковица

Koa заменяет колбэк с тремя аргументами на async (ctx, next) => {} и настоящую луковичную модель. Код до await next() выполняется на пути внутрь; код после — на пути наружу, в обратном порядке. Это делает обёрточный тайминг тривиальным:

async (ctx, next) => {
  const start = Date.now();      // внутрь
  await next();                  // выполнить всё внутри
  ctx.set('X-Time', `${Date.now() - start}`); // наружу
}

Поскольку модель на промисах, throw где угодно естественно распространяется к вышестоящему try/catch-middleware — обработка ошибок это просто middleware, оборачивающий остальное в try/catch вокруг await next().

Fastify: хуки, а не один примитив, плюс инкапсуляция

Fastify разбивает единую идею middleware на именованные хуки жизненного цикла, срабатывающие в фиксированном порядке:

onRequest → preParsing → preValidation → preHandler → handler → onSend → onResponse

Это даёт отклонить рано на onRequest (до парсинга тела — самая дешёвая точка отказа) или выполнить логику на preHandler, когда уже есть валидированное тело. Бо́льшая разница — инкапсуляция: хуки (и декораторы), зарегистрированные внутри плагина, применяются лишь к маршрутам этого плагина, не глобально. Express-middleware, напротив, протекает вниз по всей цепочке от точки монтирования. Инкапсуляция — причина, по которой большие приложения Fastify остаются ограниченными по области, тогда как большие Express-приложения накапливают глобальный middleware.