Конвейер: собираем next() и понимаем, откуда взялся Express

У нас есть таблица маршрутов и три обработчика. Каждый обязан сделать одно и то же: записать запрос в журнал — иначе разбирать будущий инцидент будет не по чему — и убедиться, что клиент показал токен. Обязанность общая, а код у каждого свой, и пишут его в разное время разные люди.

Прогноз: какой из трёх запросов сервер выполнит вообще без токена?

// Разборщик и маршрутизатор — в подложке
const router = new Router();

router.add("GET", "/notes", (params, query, request) => {
  console.log(`журнал: GET /notes от ${request.headers["user-agent"]}`);
  if (request.headers.authorization === undefined) return { status: 401, body: "нужен токен" };
  return { status: 200, body: `страница ${query.get("page") ?? 1}` };
});

router.add("GET", "/notes/:id", (params, query, request) => {
  console.log(`журнал: GET /notes/${params.id} от ${request.headers["user-agent"]}`);
  if (request.headers.authorization === undefined) return { status: 401, body: "нужен токен" };
  return { status: 200, body: `заметка ${params.id}` };
});

router.add("POST", "/notes", (params, query, request) => {
  console.log(`журнал: POST /notes от ${request.headers["user-agent"]}`);
  return { status: 201, body: JSON.parse(request.body).title };
});

const parser = new RequestParser();
parser.onRequest = (request) => {
  const found = router.find(request.method, request.target);
  const answer = found.handler
    ? found.handler(found.params, found.query, request)
    : { status: found.status, body: "нет такого адреса" };
  console.log(`${request.method} ${request.target} → ${answer.status} ${answer.body}`);
};

parser.feed("GET /notes HTTP/1.1\r\nhost: java-script.pro\r\nuser-agent: chrome\r\n\r\n");
parser.feed("GET /notes/17 HTTP/1.1\r\nhost: java-script.pro\r\nuser-agent: chrome\r\nauthorization: Bearer 123\r\n\r\n");
parser.feed(RAW);

Первые два ответа такие, как задумано: гостю 401, читателю с токеном — заметка. А POST /notes создал заметку неизвестно кому: в третьем обработчике проверки просто нет. Дыра при этом не в маршрутизаторе и не в разборщике — оба отработали честно, маршрут найден, ответ отдан, код 201. Дыра в том, что общее дело размножено копиями: копий три, а забыть достаточно в одной.

И дел этих больше, чем два. Журнал, токен, разбор тела, время ответа, заголовки ответа, перевод исключения в 500 — шесть. Обработчиков в небольшом API — десятка полтора. Девяносто мест, которые надо не забыть, а потом одинаково поменять. Так не выходит ни у кого, и лечится это не внимательностью, а устройством: общее дело должно лежать в одном месте, через которое проходит каждый запрос.

Забытая строка не падает и не светится в тестах маршрутизатора: маршрут найден, ответ отдан, код 201. Такую дыру находят по журналу, в котором её как раз и нет.

Присмотримся к общим делам внимательнее. У каждого есть часть до обработчика и часть после: журнал пишет строку о запросе до и строку об ответе после, таймер засекает до и считает после, проверка токена — только до, а заголовки ответа — только после. Значит, звену мало «выполниться перед обработчиком»: ему нужно место с обеих сторон.

Договор будет такой. Звено — функция трёх аргументов: запрос, ответ и next. Вызов next() передаёт управление следующему звену и возвращается сюда же, когда всё, что стоит дальше, отработало. Последнее звено next() не зовёт: за ним никого нет. Сам конвейер — восемь строк, которые не знают ни про HTTP, ни про маршруты.

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

// Звено получает запрос, ответ и next: вызвал next() — пустил запрос дальше по цепочке
function runPipeline(chain, request, response) {
  const step = (i) => {
    const link = chain[i];
    // звеньев больше нет: дальше по конвейеру идти некому
    if (link === undefined) return;
    link(request, response, () => step(i + 1));
  };
  step(0);
}

// Два одинаковых звена: печатают «до», зовут next() и печатают «после»
const around = (name) => (request, response, next) => {
  console.log(`${name}: до`);
  next();
  console.log(`${name}: после, код ${response.status}`);
};

const handler = (request, response) => {
  console.log("обработчик: отвечаю");
  response.status = 200;
  response.body = "список";
};

const response = { status: 404, body: "нет такого адреса" };
runPipeline([around("журнал"), around("счётчик"), handler], { method: "GET", target: "/notes" }, response);
console.log(`ответ: ${response.status} ${response.body}`);

Вышла матрёшка, а не очередь. Звено, которое стоит первым, начинает раньше всех и заканчивает позже всех: его «после» выполняется последним, когда ответ уже сложен, — потому и код в нём 200, а не 404, с которым конвейер начинался. Обработчик оказался в середине конструкции, хотя в массиве он последний.

Стоит заметить, чего в runPipeline нет. Он не знает, что такое запрос: для него это объект, который он передаёт дальше. Не знает, что такое ответ. Не знает, сколько звеньев и что они делают. Всё его устройство — «позвать следующего и дать ему способ позвать следующего за ним», и этого хватает, чтобы из отдельных функций собралась одна обработка запроса.

Звено не знает ни своих соседей, ни своего номера в цепочке. Поэтому цепочку можно пересобрать в другом порядке, и ни одно звено об этом не узнает — а поведение сервера изменится.

Синхронный конвейер годится ровно до первого настоящего обработчика. Настоящий идёт в базу, дочитывает тело из сокета, стучится в почту — и возвращается не сразу. Значит, next() обязан вернуть промис, а звено — его дождаться. Переделка мелкая: step становится async, а вызов звена — с await. И на этой мелочи появляется ловушка: await перед самим next() внутри звена легко не написать, а код при этом не падает и даже что-то печатает.

Прогноз: какой код ответа напечатает журнал и когда напечатается строка «обработчик: ответил»?

// Тот же конвейер, но умеющий ждать: next() возвращает промис
async function runPipeline(chain, request, response) {
  const step = async (i) => {
    const link = chain[i];
    if (link === undefined) return;
    await link(request, response, () => step(i + 1));
  };
  await step(0);
}

const handler = async (request, response) => {
  console.log("обработчик: пошёл в базу");
  // на месте этой строки в жизни — запрос в базу или чтение тела запроса
  await new Promise((resolve) => setTimeout(resolve, 0));
  response.status = 200;
  response.body = "список";
  console.log("обработчик: ответил");
};

const journal = async (request, response, next) => {
  console.log("журнал: до");
  next(); // await забыт
  console.log(`журнал: после, код ${response.status}`);
};

async function main() {
  const response = { status: 404, body: "нет такого адреса" };
  await runPipeline([journal, handler], { method: "GET", target: "/notes" }, response);
  console.log(`ответ: ${response.status} ${response.body}`);
}

main();

Пять строк, и три из них не на своём месте. Звено напечатало «после» с кодом 404, хотя обработчик в этот момент только пошёл в базу, и весь конвейер закончился раньше, чем ответ был собран. Причина знакомая: вызов асинхронной функции без await просто возвращает промис и мгновенно идёт дальше. Промис, который вернул next(), никто не забрал, и звено продолжило свой код так, будто внизу уже всё сделано.

В консоли это выглядит как перепутанные строки. На сервере это ответ, который ушёл клиенту раньше, чем обработчик его собрал: код 404 вместо 200, пустое тело — и попытка обработчика ответить второй раз, когда он наконец закончит. Поэтому в конвейере не бывает «почти синхронных» звеньев: звено объявляется async, а next() пишется с await. Годится и return next() — но только там, где после него в звене ничего нет: промис тогда забирает тот, кто звено позвал. Даже если сегодня за звеном стоит синхронный обработчик — завтра за ним будет база.

Строку «журнал: после» в жизни печатают не в консоль, а в журнал сервера, и код ответа в ней — тот, по которому потом разбирают инциденты. Забытый await превращает такой журнал в выдумку.

Третье правило: звено не обязано звать next(). Проверка токена, ограничитель частоты, кеш, нашедший готовый ответ, — все они иногда обрывают путь запроса и отвечают сами. Обрыв не ошибка, а обычный исход: до обработчика запрос просто не доходит.

Заодно доведём конвейер до конца — в нём появится защёлка в три строки, и о ней сразу после примера. Прогноз: напечатает ли журнал своё «после», если страж не пустил гостя дальше?

// Конвейер, доведённый до конца: индекс звена только растёт
async function runPipeline(chain, request, response) {
  let last = -1;
  const step = async (i) => {
    // второй next() в одном звене — это второй проход по хвосту конвейера и второй ответ
    if (i <= last) throw new Error("next() в этом звене уже вызван");
    last = i;
    const link = chain[i];
    // звеньев больше нет: дальше по конвейеру идти некому
    if (link === undefined) return;
    await link(request, response, () => step(i + 1));
  };
  await step(0);
}

const journal = async (request, response, next) => {
  console.log(`журнал: ${request.method} ${request.target}`);
  await next();
  console.log(`журнал: ответ ${response.status} ${response.body}`);
};

// Страж отвечает сам: обработчик о госте не узнает
const guard = async (request, response, next) => {
  if (request.headers.authorization === undefined) {
    response.status = 401;
    response.body = "нужен токен";
    return;
  }
  await next();
};

const handler = async (request, response) => {
  console.log("обработчик: работаю");
  response.status = 200;
  response.body = "список";
};

async function main() {
  for (const headers of [{}, { authorization: "Bearer 123" }]) {
    const request = { method: "GET", target: "/notes", headers };
    await runPipeline([journal, guard, handler], request, { status: 404, body: "нет такого адреса" });
  }
}

main();

Два запроса — два пути. У гостя цепочка оборвалась на страже: обработчик не выполнился и о запросе не узнал. Но журнал, который стоит перед стражем, свою вторую строку напечатал, и код в ней — 401, поставленный стражем. «Не пустил дальше» не значит «прервал всё»: конвейер сворачивается назад ровно так же, как разворачивался, и каждое звено получает управление обратно. Поэтому журнал, таймер и заголовки ответа работают одинаково и на 200, и на 401 — они их не различают.

Страж на входе — это экономия, а не охрана: он не пускает гостя к базе. Но привратник, которого можно обойти, охраной не считается, а обойти конвейер нетрудно: обработчик могут позвать мимо него — из фоновой задачи, из соседнего модуля, из другого транспорта. Настоящая проверка прав живёт там, где лежат данные. В главе про свои усилители страж станет отдельным видом звена, у которого вместо ответа — «пускать» или «нет».

Теперь про защёлку. Индекс звена в step только растёт: конвейер помнит, до какого звена он уже дошёл, и на попытку вернуться назад бросает исключение. Три строки написаны против одной-единственной ошибки — двух вызовов next() в одном звене.

// Конвейер — в подложке
const handler = async (request, response) => {
  console.log("обработчик: отвечаю");
  response.status = 200;
  response.body = "список";
};

const retry = async (request, response, next) => {
  await next();
  // «на всякий случай»: показалось, что первый вызов ничего не сделал
  await next();
};

async function main() {
  const response = { status: 404, body: "нет такого адреса" };
  try {
    await runPipeline([retry, handler], { method: "GET", target: "/notes" }, response);
  } catch (err) {
    console.log(`конвейер остановлен: ${err.message}`);
  }
  console.log(`ответ: ${response.status} ${response.body}`);
}

main();

Звено, которое ответило само, обязано вернуться, а не просто «не звать next()»: без return выполнение пойдёт по звену дальше — то есть как раз в next(), и гость проедет внутрь с готовым 401 в ответе.

Ещё одно дело, которое лежало копиями в обработчиках, — try..catch. Обработчик падает не потому, что программист плох, а потому, что база отвалилась, в теле оказалось не то, а в коде — опечатка, которую не поймал ни один тест. Клиенту в этот момент нужен честный 500, а не оборванное соединение и не зависший запрос.

В конвейере для этого хватает одного звена, и стоять оно должно первым: try вокруг await next() накрывает всё, что конвейер позовёт после. Прогноз: какие из двух строк «после» напечатаются, если обработчик бросит исключение?

// Конвейер — в подложке
const catcher = async (request, response, next) => {
  try {
    await next();
  } catch (err) {
    // одно место на все 500: ловец стоит первым и видит всё, что зовёт после себя
    console.log(`ловец: поймал ${err.name}`);
    response.status = 500;
    response.body = "внутренняя ошибка";
  }
};

const journal = async (request, response, next) => {
  console.log("журнал: до");
  await next();
  console.log("журнал: после");
};

const timer = async (request, response, next) => {
  console.log("таймер: до");
  try {
    await next();
  } finally {
    console.log("таймер: после");
  }
};

const handler = async (request, response) => {
  const notes = { rows: [] };
  response.body = notes.map((note) => note.title);
};

async function main() {
  const response = { status: 404, body: "нет такого адреса" };
  await runPipeline([catcher, journal, timer, handler], { method: "GET", target: "/notes" }, response);
  console.log(`ответ: ${response.status} ${response.body}`);
}

main();

Напечаталась одна. Исключение из обработчика поднимается сквозь await next() вверх по конвейеру, как по обычному стеку вызовов, — и код, стоящий после next(), при этом не выполняется вовсе: строка «журнал: после» пропала. Таймер свою вторую строку напечатал, потому что написал её в finally. Разница ровно та же, что у обычного try..catch: «после» — это продолжение звена, а не обещание конвейера.

Отсюда правило. Всё, что должно случиться при любом исходе — закрыть транзакцию, снять блокировку, вернуть соединение в пул, дописать строку в журнал, — пишется в finally. Всё, что имеет смысл только для удавшегося ответа, — после next(). Путать эти два места дорого: журнал, который ведётся только для удачных запросов, молчит ровно тогда, когда он нужнее всего.

Наш ловец переводит в 500 что угодно, и пока это честно: ошибка, о которой мы ничего не знаем, — наша. Но большая часть ошибок настоящего сервера знает о себе больше: «нет такой заметки» — это 404, «чужая заметка» — 403, «в теле мусор» — 400. Как перевести доменную ошибку в код ответа одним местом, разберём в главе про свой конвейер; сейчас важно, что место для такого перевода в сервере уже есть и оно ровно одно.

Ловец не всесилен: если ответ уже ушёл в сокет, а исключение случилось после этого, поменять код ответа нельзя — остаётся закрыть соединение и записать строку в журнал.

Соберём главу целиком. Разборщик превращает байты в запросы. Конвейер проводит запрос через журнал и стража. Маршрутизатор становится последним звеном: он выбирает обработчик, зовёт его и кладёт результат в ответ. Никакого главного кода, который всем этим руководит, в сервере больше нет — есть список звеньев.

Одна тонкость на стыке. Разборщик отдаёт запросы синхронно, прямо из feed: получил кусок байтов — тут же позвал onRequest. А конвейер асинхронный. Поэтому запросы складываются в очередь и проходят конвейер по одному: на настоящем сервере у каждого соединения свой поток запросов и одновременность получается сама, а здесь хватает цикла.

Прогноз: какой из пяти запросов не дойдёт до маршрутизатора и что ответит DELETE /notes?

// Разборщик, маршрутизатор и конвейер — в подложке
const router = new Router();
router.add("GET", "/notes", (params, query) => `страница ${query.get("page") ?? 1}`);
router.add("POST", "/notes", (params, query, request) => `создана «${JSON.parse(request.body).title}»`);

const journal = async (request, response, next) => {
  console.log(`${request.method} ${request.target}`);
  await next();
  console.log(`  → ${response.status} ${response.body}`);
};

const guard = async (request, response, next) => {
  if (request.method === "GET" || request.headers.authorization !== undefined) return next();
  response.status = 401;
  response.body = "нужен токен";
};

// Маршрутизатор стал последним звеном: до него запрос идёт через весь конвейер
const route = async (request, response) => {
  const found = router.find(request.method, request.target);
  if (found.handler === undefined) {
    response.status = found.status;
    response.body = found.allow ? `Allow: ${found.allow}` : "нет такого адреса";
    return;
  }
  response.status = 200;
  response.body = await found.handler(found.params, found.query, request);
};

// Разборщик отдаёт запросы синхронно, а конвейер асинхронный: складываем их в очередь
const queue = [];
const parser = new RequestParser();
parser.onRequest = (request) => queue.push(request);

parser.feed(RAW);
parser.feed('POST /notes HTTP/1.1\r\nhost: java-script.pro\r\nauthorization: Bearer 123\r\ncontent-length: 28\r\n\r\n{"title":"конвейер"}');
parser.feed("GET /notes?page=3 HTTP/1.1\r\nhost: java-script.pro\r\n\r\n");
parser.feed("DELETE /notes HTTP/1.1\r\nhost: java-script.pro\r\nauthorization: Bearer 123\r\n\r\n");
parser.feed("GET /health HTTP/1.1\r\nhost: java-script.pro\r\n\r\n");

async function main() {
  for (const request of queue) {
    await runPipeline([journal, guard, route], request, { status: 404, body: "нет такого адреса" });
  }
}

main();

Пять запросов — четыре разных исхода, и ни один обработчик не знает ни о журнале, ни о токене. POST без токена до маршрутизатора не дошёл: страж ответил сам. POST с токеном дошёл и создал заметку. DELETE /notes прошёл весь конвейер, но маршрута не нашёл — нашёл только путь, и вернул 405 со списком методов. GET /health не нашёл ничего. Журнал при этом одинаково написал по две строки на каждый запрос, включая те, что оборвались на полпути.

А теперь посмотрите на первые строки любого проекта на Express. app.use(звено) кладёт функцию в массив; app.get(путь, обработчик) кладёт в тот же массив звено, которое сначала сверяет метод и путь, а потом зовёт ваш обработчик. Когда приходит запрос, Express идёт по массиву по индексу и передаёт каждому звену третьим аргументом функцию next. Это ваш runPipeline, написанный чуть аккуратнее и обросший сахаром вокруг ответа.

Последняя строка таблицы — единственное место, где ваш конвейер и Express расходятся по существу. В Express next() ничего не возвращает: звено передаёт управление дальше и тут же продолжает свой код, не дожидаясь обработчика. Проверено 22.09.2026 на Express 5.2.1 и node 26.5.0: строка после next() печатается ещё до того, как асинхронный обработчик дошёл до ответа, и res.headersSent в ней false. Поэтому «после» в Express пишут не после next(), а в обработчике события finish. Ваш конвейер в этом месте устроен как koa: next() возвращает промис, и «после» — просто следующая строка. У перехватчика Nest место то же, но next.handle() возвращает не промис, а Observable из rxjs.

Вот и ответ на вопрос из названия. Фреймворк — это ваш же код, доведённый до конца и упакованный: тот же массив, тот же обход по индексу, та же функция третьим аргументом. Не хватает вашему серверу не абстракций, а строгости — к разбору заголовков, к размеру тела, к удержанию соединения. Следующая статья ставит рядом настоящий node:http и называет эти дыры поимённо, а в главе про каркас конвейер, маршрутизатор и контейнер соберутся в каркас целиком — миниатюру Nest, которая сама отвечает 200 и 404.

Express и koa разошлись ровно на этой строке: у koa next() возвращает промис, и «до» и «после» пишутся в одном звене. Из этого выбора выросли два разных мира middleware.