Капстоун: проектируем и закаляем production Node-сервис

Чек-лист и есть архитектура

К концу этого урока ты сможешь проследить один запрос через полностью закалённый сервис и назвать инцидент, который порождает каждый пропущенный слой — так что в следующий раз, когда pull request срежет угол, ты распознаешь это до того, как оно попадёт в production.

Путь от прототипа к production — это не переписывание, а применение каждого юнита этого трека к одному маленькому HTTP-сервису и отказ хоть один из них пропустить. Полезная линза — чек-лист жизненного цикла запроса: для каждой сквозной заботы назови что ты делаешь и конкретный сигнал готово, когда. Пропусти строку — и получишь не сервис поменьше, а будущий инцидент с именем. Манифест 12factor и репозиторий node-best-practices — это под капотом ровно этот список: конфиг в окружении, зависимости объявлены и залочены, процессы одноразовые, логи как потоки событий.

Сеньорский ход — относиться к этому как к слоям, которые компонуются, а не к бэклогу фич. Ошибки, event loop, порядок middleware, shutdown, валидация, конфиг и наблюдаемость — не независимые галочки, они сцеплены. Graceful shutdown бесполезен, если балансировщик так и не узнал, что ты сливаешься (это readiness-проба). Граница ошибок бесполезна, если заблокированный loop означает, что граница вообще не выполнится. Ниже — чек-лист готовности, который защищает весь этот урок.

Жизненный цикл запроса, закалённый из конца в конец

Проследи один запрос — и увидишь, как каждый юнит делает свою работу. Ingress или балансировщик маршрутизирует в процесс, у HTTP-сервера которого уже выставлены таймауты — server.requestTimeout, headersTimeout и таймаут обработчика на маршрут, — так что ни один клиент не удержит соединение открытым вечно (юнит 05). Запрос входит в упорядоченный стек middleware, и порядок несущий: сначала логирование (чтобы логировать даже отклонённые запросы), затем парсер тела с лимитом размера (чтобы тело в 4 МБ не разорвало память и не заблокировало парс), затем auth, затем валидация по схеме, затем обработчик. Обработчик зовёт тонкий слой сервисов, тот — репозиторий, выдающий параметризованные запросы (никакой конкатенации строк), а доменный сбой становится типизированной ошибкой (юнит 07, юнит 03).

Сквозь всё это продёрнут контекст запроса. Структурный логгер pino несёт request/trace ID через AsyncLocalStorage (встроенный Node.js API для хранения данных, изолированных по async-цепочке), так что каждая строка лога из глубины стека скоррелирована со своим запросом без ручной передачи ID. diagnostics_channel (встроенный pub/sub-канал Node.js для низкоуровневой инструментации без жёсткой связности) даёт публиковать точки инструментирования (старт/конец запроса к БД, попадание в кэш), на которые экспортёры подписываются без связности. В самом конце стоит единая граница ошибок: middleware обработки ошибок, которая мапит тип ошибки в HTTP-статус (ValidationError→400, NotFoundError→404, всё неизвестное→500), отправляет безопасное JSON-тело без стека и логирует полный объект ошибки с цепочкой cause. Это стратегия юнита 03, выраженная как ровно одно место в проводке.

Bootstrap и shutdown: проводка, решающая аптайм

Два куска сантехники решают, будут деплои невидимыми или разрушительными: bootstrap, который ставит страховочную сеть до того, как что-либо начнёт обслуживать, и shutdown, который сливает работу до выхода. Когда смотришь на index.js нового сервиса, спроси себя: сеть процесса установлена до listen, а SIGTERM обработан до первого возможного запроса? На SIGTERM ты не захлопываешь сервер — ты переключаешь readiness в не готов (чтобы балансировщик перестал слать новые запросы), прекращаешь принимать соединения, даёшь запросам в полёте дойти, закрываешь пул БД и взводишь жёсткий таймаут, чтобы зависший запрос не блокировал shutdown вечно. Пропуск этого — инцидент с потерянными заказами из хука.

import { createServer } from "node:http";
import { app } from "./app.js";          // упорядоченный middleware + граница ошибок
import { logger } from "./logger.js";
import { closePool } from "./db.js";

let ready = false;
const server = createServer(app);
server.requestTimeout = 30_000;          // юнит 05: ограничь каждый запрос
server.headersTimeout = 10_000;

// юнит 03: сеть процесса — зафиксируй, потом умри; супервизор перезапустит чистым
process.on("uncaughtException", (err) => { logger.fatal({ err }); shutdown(1); });
process.on("unhandledRejection", (err) => { logger.fatal({ err }); shutdown(1); });

async function shutdown(code = 0) {
  ready = false;                         // readiness переключился → LB сливает нас
  server.close(async () => {             // прекрати принимать; доделай в полёте
    await closePool();
    process.exit(code);
  });
  setTimeout(() => process.exit(code), 10_000).unref(); // жёсткий кэп
}
process.on("SIGTERM", () => shutdown(0));

server.listen(3000, () => { ready = true; logger.info("listening"); });
// liveness = процесс жив; readiness = флаг `ready` (одноразовость по 12-factor)