Архитектура Node-бэкенда
Первые эндпоинты пишутся почти без решений: маршрут, обработчик, запрос в базу — и всё работает. Проблемы начинаются позже, когда правило про права доступа живёт в трёх местах, тест на бизнес-логику требует поднять HTTP и PostgreSQL, а выделить один модуль в отдельный сервис нельзя, потому что он импортирует половину проекта. Архитектура серверного Node-приложения — это ответы на три вопроса: где живёт правило, от чего зависит модуль и что нужно поднять, чтобы проверить изменение.
Содержание
- Зачем сервису архитектура
- Слои: transport, controller, service, repository
- Контроллер: граница HTTP
- Сервис: инварианты и транзакция
- Репозиторий: единственное место с SQL
- Типы и данные между слоями
- Валидация на границах
- DI без фреймворка: composition root
- DI в NestJS
- Границы модулей
- Модульный монолит и микросервисы
- Версионирование API и совместимость
- Практика: TaskFlow
- Частые ошибки
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Зачем сервису архитектура
Архитектуру полезно мерить не количеством слоёв и папок, а стоимостью следующего изменения. Если добавить поле в ответ API — это правка в одном месте, архитектура работает. Если нужно найти все места, где собирается объект задачи, — нет.
Симптомы обычно выглядят как технические мелочи, но указывают на одно: у правила нет владельца, а у модуля нет границы.
| Симптом | Что на самом деле |
|---|---|
| Тест на бизнес-правило требует базы и HTTP | зависимости жёсткие, сценарий не отделён от транспорта |
| Одно правило продублировано в HTTP, воркере и cron | нет сервисного слоя, логика живёт в обработчиках |
| Поле БД меняется в пяти файлах | схема и доменная модель не разделены |
| Модуль нельзя вынести в пакет | он импортирует внутренности соседей |
| Релиз API ломает клиентов | контракт не отделён от кода и схемы данных |
| Непонятно, что сломается при замене ORM | ORM-типы и query builder протекли в бизнес-логику |
Архитектура отвечает сразу на трёх уровнях:
- код — как разложены ответственности и куда направлены зависимости;
- процесс — один монолит, несколько модулей или несколько сервисов;
- контракт — что именно сервис обещает клиентам и как это обещание меняется.
Слои не нужно вводить «на всякий случай». Для пяти эндпоинтов и одной команды плоская структура может быть честнее. Но как только появляется второй транспорт (воркер очереди, cron, WebSocket), второе правило с теми же данными или второй человек в коде, разделение на сценарии и доступ к данным перестаёт быть церемонией.
Слои: transport, controller, service, repository
Классическая серверная раскладка — четыре роли. Важно, что это именно роли, а не обязательные четыре папки: иногда controller и transport сливаются в route handler, иногда репозиторий и сервис живут в одном модуле. Ответственности при этом остаются разными.
| Слой | За что отвечает | Что знает | Чего не знает |
|---|---|---|---|
| transport | приём соединений, парсинг протокола, middleware, маршрутизация | HTTP, WebSocket, формат очереди | бизнес-правила |
| controller | перевод запроса в вызов сценария и результата обратно в ответ | DTO, сервис, коды и заголовки | SQL, транзакции, устройство БД |
| service | правила, инварианты, права, граница транзакции | доменные типы, интерфейсы репозиториев, unit of work | req/res, SQL, фреймворк |
| repository | чтение и запись данных, маппинг строк | драйвер БД, схему таблиц | HTTP, права, бизнес-правила |
Главное правило — направление зависимостей: transport знает controller, controller знает service, service знает интерфейс repository, repository знает базу. Обратное движение — только через результат вызова, событие или внедрённый интерфейс. Если сервис импортирует express, а репозиторий бросает 404, слои уже поехали.
Типовая структура небольшого, но растущего сервиса:
src/
app.js # composition root: собирает зависимости
server.js # listen, сигналы, жизненный цикл
transport/
http/
middleware/ # request-id, auth, error mapper
routes/ # регистрация маршрутов
queue/
handlers/ # те же сервисы, другой транспорт
modules/
tasks/
tasks.controller.js
tasks.service.js
tasks.repository.js
tasks.schema.js # схемы входа и ответа
index.js # публичный API модуля
projects/
...
lib/
db.js
logger.js
errors.js
Почему модули, а не папки controllers/, services/, repositories/ на весь проект: при росте числа сущностей горизонтальные папки превращаются в свалку, где tasks.service.js и billing.service.js лежат рядом, но не связаны. Вертикальный срез держит всё про задачу в одном месте и позволяет провести границу модуля.
При этом не каждый эндпоинт обязан проходить все четыре слоя. GET /health/live отвечает прямо в транспорте, простой справочник может читаться query-функцией. Отклонение нормально, если оно осознанное и не превращается в правило «иногда пишем SQL в контроллере».
Контроллер: граница HTTP
Контроллер — переводчик. Он принимает уже разобранный запрос, превращает его в аргументы сценария, вызывает сервис и упаковывает результат в HTTP-ответ. Всё, что связано с бизнесом, остаётся ниже.
// modules/tasks/tasks.controller.js
import { createTaskSchema, listTasksSchema, toTaskResponse } from './tasks.schema.js';
export function createTasksController({ tasks }) {
return {
async create(req, res) {
const input = createTaskSchema.parse(req.body);
const task = await tasks.create({ ...input, userId: req.auth.userId });
res
.status(201)
.location(`/v1/tasks/${task.id}`)
.json(toTaskResponse(task));
},
async list(req, res) {
const query = listTasksSchema.parse(req.query);
const page = await tasks.list(query);
res.json({
items: page.items.map(toTaskResponse),
nextCursor: page.nextCursor,
});
},
};
}
Что здесь важно:
- Валидация на входе.
parseлибо возвращает типизированный объект, либо бросает ошибку, которую централизованно превращает error middleware. В Fastify эту роль играетschemaмаршрута, в Nest —ValidationPipe. - Никаких правил. Проверка «пользователь состоит в проекте» не живёт в контроллере, иначе воркер, вызывающий тот же сценарий, её обойдёт.
- Явный ответ. Наружу уходит
toTaskResponse(task), а не доменный объект и тем более не строка из базы: иначе внутренние поля (passwordHash,deletedAt,tenantId) утекут в API. - Коды и заголовки.
201иLocationпри создании,204при удалении,ETag/Cache-Controlтам, где это часть контракта, — работа контроллера, а не сервиса. - Один маппер ошибок. Доменная ошибка
project_not_foundпревращается в404в одном месте. Если каждый контроллер сам решает, какой код вернуть наAppError, ответы начнут расходиться.
Грубая авторизация может стоять на маршруте: router.post('/tasks', requireAuth, controller.create). Но проверка «может ли этот пользователь менять именно эту задачу» — уже бизнес-правило, и её место в сервисе. Маршрут отвечает на вопрос «кто ты», сервис — «что тебе можно».
Контроллер не должен быть тонким до бессмысленности. Разбор пагинации, выбор формата ошибки, установка заголовков кеша — законная работа. Плохо не количество строк, а протекание ответственности: SQL или req внутри сервиса, бизнес-правило в контроллере.
Сервис: инварианты и транзакция
Сервис — место, где живёт вариант использования. Его методы называют по действию: createTask, completeTask, archiveProject, а не handle или process. Один метод — один сценарий, который можно вызвать из HTTP, из очереди и из CLI.
// modules/tasks/tasks.service.js
import { AppError } from '../../lib/errors.js';
export function createTasksService({ tasks, projects, events, db, logger }) {
return {
async create({ projectId, title, userId }) {
const project = await projects.findById(projectId);
if (!project) {
throw new AppError('project not found', { status: 404, code: 'project_not_found' });
}
if (!project.hasMember(userId)) {
throw new AppError('forbidden', { status: 403, code: 'forbidden' });
}
const task = await db.transaction(async (tx) => {
const created = await tasks.insert({ projectId, title, createdBy: userId }, tx);
await events.record({ type: 'task.created', payload: { taskId: created.id } }, tx);
return created;
});
logger.info({ taskId: task.id, projectId }, 'task created');
return task;
},
};
}
Несколько решений, которые здесь видны:
Граница транзакции — в сервисе. Один сценарий может включать несколько записей: создать задачу, записать событие в outbox, обновить счётчик проекта. Все они должны попасть в одну транзакцию. Контроллер не знает, из каких шагов состоит сценарий, репозиторий видит только свой запрос — значит, открывать транзакцию может только сервис.
Событие пишется в той же транзакции. Если отправить его в брокер до commit, потребитель может получить событие о задаче, которой ещё нет, или не получить его вовсе при откате. Outbox-таблица фиксирует намерение вместе с данными, а отдельный диспетчер публикует запись после коммита. Подробнее — в статье «Redis и фоновые задачи».
Побочные эффекты — после коммита. Письмо, вызов внешнего API и публикация события не должны случаться, если транзакция откатилась. Лог — исключение: он полезен и при откате.
Сервис не знает про HTTP. Он принимает доменные значения, возвращает доменный объект и бросает AppError с кодом. Превращение кода в статус — задача транспорта. Благодаря этому тот же сценарий вызывается из воркера, где 404 не имеет смысла, а ошибка должна привести к ретраю или в DLQ.
Про базу сервис знает ровно столько, сколько нужно для границы сценария: он владеет транзакцией, но работает с абстракцией db.transaction, а не с драйвером и не с SQL. Эта абстракция (unit of work) скрывает, как открывается соединение, и позволяет подменить её в тесте.
Права проверяются здесь. Сервис — единственная точка, через которую проходит сценарий, поэтому проверка членства в проекте, владения задачей и лимитов тарифа живёт тут. Проверка в контроллере — удобная ранняя отсечка, но не замена.
Сервис не должен превращаться в «божественный объект» на весь домен. Разумно делить его по агрегатам и сценариям: TasksService, ProjectsService, BillingService. Вызов сервиса из сервиса допустим, но если между ними появляется цикл, это сигнал, что граница агрегата выбрана неверно или часть логики должна стать событием.
Репозиторий: единственное место с SQL
Репозиторий отвечает за данные: выполняет запросы, маппит строки в доменные объекты и прячет схему. Его интерфейс — язык домена, а не язык SQL.
// modules/tasks/tasks.repository.js
export function createTasksRepository(db) {
return {
async findById(id, tx = db) {
const { rows } = await tx.query(
`select id, project_id, title, status, created_by, created_at
from tasks
where id = $1 and deleted_at is null`,
[id],
);
return rows[0] ? toTask(rows[0]) : null;
},
async insert({ projectId, title, createdBy }, tx = db) {
const { rows } = await tx.query(
`insert into tasks (project_id, title, created_by)
values ($1, $2, $3)
returning id, project_id, title, status, created_by, created_at`,
[projectId, title, createdBy],
);
return toTask(rows[0]);
},
};
}
function toTask(row) {
return {
id: row.id,
projectId: row.project_id,
title: row.title,
status: row.status,
createdBy: row.created_by,
createdAt: row.created_at,
};
}
Три вещи, которые даёт такой слой:
- Единое место для запросов к агрегату. Все
selectиupdateзадач собраны здесь, и при добавленииdeleted_atне нужно искать их по всему проекту. - Маппинг, а не сырые строки. Наружу уходят
camelCase-объекты сDate, а неsnake_case-строки иnumericв виде строк. Сервис не зависит от того, как драйвер представилcount. - Транзакционный контекст как параметр.
tx = dbпозволяет вызвать метод и вне транзакции, и внутри неё, не создавая второй пул и не открывая отдельное соединение. Это же решение закрывает проблему «репозиторий внутри транзакции взял другой клиент».
Чего репозиторий делать не должен:
- Проверять бизнес-правила. «Нельзя завершить задачу в архивированном проекте» — правило сервиса. Репозиторий может проверить только то, что является инвариантом хранения: уникальность, внешний ключ,
check. - Бросать HTTP-ошибки.
404и403— язык транспорта. Репозиторий возвращаетnullили бросает ошибку драйвера. - Превращаться в универсальный
Repository<T>.find(criteria)с произвольным объектом условий — это тот же query builder, только с другим названием. Доменные методы (findActiveForProject,listOverdue) читаются лучше и не дают собрать случайный запрос из данных клиента. - Скрывать N+1. Репозиторий с методом
getProjectTasksможет тянуть связи лениво; счётчик запросов и план запроса проверяют на границе, а не в сервисе. Об этом — в статье «Доступ к базам данных».
Для сложных чтений — отчётов, списков с фильтрами и агрегатами — иногда честнее отдельная query-функция, которая сразу возвращает read-модель, без доменного объекта и репозитория. Это нормальное отклонение, если оно названо явно и не используется для записи: гонять сложный join через «универсальный репозиторий» дороже и запутаннее.
Типы и данные между слоями
Один и тот же объект в сервисе выглядит по-разному на трёх границах. Если не разделять эти представления, схема базы начнёт диктовать контракт API, а клиент — влиять на устройство хранения.
| Граница | Что приходит | Что внутри | Что уходит |
|---|---|---|---|
| HTTP | DTO из схемы (unknown → тип) | доменный объект | response DTO |
| Очередь | сообщение по схеме | доменный объект | событие по схеме |
| База | строка драйвера | доменный объект | строка для записи |
Разделение стоит денег: нужны мапперы и отдельные типы. Оно окупается, когда контракт API и схема БД меняются с разной скоростью. Поле passwordHash не должно попасть в ответ только потому, что оно есть в таблице; project_id не должен стать projectId в API сам собой; numeric из PostgreSQL не должен превратиться в строку в JSON без решения.
В TypeScript есть дополнительная ловушка: типы стираются в рантайме. JSON.parse возвращает any, который компилятор считает чем угодно, и ошибка всплывает не на границе, а через три слоя в виде TypeError. Поэтому на входе данные принимают как unknown и сужают схемой:
const body: unknown = JSON.parse(raw);
const input = createTaskSchema.parse(body); // здесь unknown → CreateTaskInput
Полезны branded-типы для идентификаторов, чтобы TaskId нельзя было передать туда, где ждут ProjectId:
type Brand<T, B extends string> = T & { readonly __brand: B };
export type TaskId = Brand<string, 'TaskId'>;
export type ProjectId = Brand<string, 'ProjectId'>;
На границе с клиентом такие типы не нужны — достаточно строки и схемы. Внутри они ловят перепутанные аргументы, которые иначе находятся только тестом.
Ошибки тоже часть модели. Один AppError с полями status, code, retryable и cause даёт сервису язык отказа, а транспорту — материал для маппинга. Ошибка драйвера, ошибка валидации и доменная ошибка не должны смешиваться в одно throw new Error('something went wrong').
Валидация на границах
Валидация — это не одна проверка в контроллере, а набор границ, где недоверенные данные входят в приложение:
- тело, query и параметры HTTP-запроса;
- сообщение из очереди;
- конфигурация при старте;
- ответ внешнего API;
- данные из cookie и заголовков.
На каждой такой границе данные проверяют схемой и только потом превращают в доменный объект. Внутри приложения повторно проверять форму не нужно — за это отвечают типы и инварианты, — но инварианты вроде «сумма позиций равна итогу» проверяются в сервисе, потому что это уже правило, а не форма.
// modules/tasks/tasks.schema.js
import { z } from 'zod';
export const createTaskSchema = z
.object({
projectId: z.string().uuid(),
title: z.string().trim().min(1).max(200),
dueDate: z.coerce.date().optional(),
})
.strict(); // лишние поля — ошибка, а не молчаливое присваивание
Что даёт схема, кроме проверки типов:
- Отсечение лишнего.
.strict()не пропускаетrole: 'admin'иownerId, которые клиент добавил «на всякий случай». Без этого mass assignment превращает тело запроса в команду изменения прав. - Приведение типов. Query всегда строки,
?limit=20нужно превратить в число, а?done=false— вfalse, а не вtrueчерезBoolean('false'). - Единый формат ошибки. Все issues собираются в один ответ
400/422с полем и сообщением, а не в пять разных текстов из разных обработчиков. - Тип из схемы.
z.infer<typeof createTaskSchema>даёт тип DTO, и он не расходится с проверкой во время выполнения.
Ответы тоже полезно описывать схемой — хотя бы в тестах и на этапе разработки. Это ловит утечку внутренних полей и случайное изменение формата, которое клиент заметит раньше вас. Подробнее про конфиг, unknown и DTO — в статье «Конфигурация и валидация».
DI без фреймворка: composition root
Внедрение зависимостей не требует библиотеки. Достаточно одного места, где создаются все объекты и связываются между собой, — composition root. Обычно это app.js, который вызывает server.js.
// src/app.js
import express from 'express';
import { createDb } from './lib/db.js';
import { createOutbox } from './lib/outbox.js';
import { createTasksRepository } from './modules/tasks/tasks.repository.js';
import { createProjectsRepository } from './modules/projects/projects.repository.js';
import { createTasksService } from './modules/tasks/tasks.service.js';
import { createTasksRouter } from './modules/tasks/tasks.routes.js';
import { requestId } from './transport/http/middleware/request-id.js';
import { errorMapper } from './transport/http/middleware/error-mapper.js';
export function createApp({ config, logger }) {
const db = createDb(config.DATABASE_URL);
const tasksRepo = createTasksRepository(db);
const projectsRepo = createProjectsRepository(db);
const outbox = createOutbox(db);
const tasks = createTasksService({
tasks: tasksRepo,
projects: projectsRepo,
events: outbox,
db,
logger,
});
const app = express();
app.use(requestId);
app.use('/v1/tasks', createTasksRouter({ tasks }));
app.use(errorMapper(logger));
return { app, close: () => db.end() };
}
Почему это лучше импорта синглтона:
- Граф виден целиком. Открыв один файл, можно понять, какие зависимости есть у сервиса и в каком порядке они создаются.
- Тест собирает свой граф. Не нужно мокать модули: достаточно передать фейковый репозиторий и фейковые часы.
- Нет скрытого состояния. Модуль, который на import создаёт пул соединений, делает тесты медленными и мешает запускать два приложения в одном процессе.
- Жизненный цикл под контролем.
createAppвозвращаетclose, и сервер закрывает пул, Redis и очередь в обратном порядке создания. Об этом — в статье «Таймауты, ретраи и graceful shutdown».
Три антипаттерна, которые выглядят как DI, но им не являются:
- Service locator.
container.get('tasksService')внутри функции прячет зависимость: её не видно в сигнатуре, и тест не знает, что подменять. - Глобальный контейнер на весь процесс. Он удобен, пока приложение одно; в тестах и в нескольких инстансах начинается борьба за состояние.
- Инъекция всего подряд. Если сервису нужны логгер, конфиг, пять репозиториев и три клиента, это сигнал, что сценарий слишком большой, а не что DI плохой.
Контекст запроса (пользователь, request-id, тенант) не стоит тащить через все слои аргументом. Его кладут в AsyncLocalStorage и читают в логгере и трейсере, а в сервис передают явно только то, что влияет на бизнес-правило. Так граница остаётся видимой, а инфраструктурный шум не протекает в домен.
DI в NestJS
NestJS делает ту же работу, но через модули, провайдеры и токены. Вместо явного createApp граф собирает контейнер, а зависимости приходят в конструктор.
// modules/tasks/tasks.module.ts
@Module({
controllers: [TasksController],
providers: [
TasksService,
{ provide: TASKS_REPOSITORY, useClass: PgTasksRepository },
{ provide: CLOCK, useValue: systemClock },
],
exports: [TasksService],
})
export class TasksModule {}
@Injectable()
export class TasksService {
constructor(
@Inject(TASKS_REPOSITORY) private readonly tasks: TasksRepository,
@Inject(CLOCK) private readonly clock: Clock,
private readonly projects: ProjectsService,
) {}
}
Что меняется по сравнению с ручной сборкой:
- Граф проверяется на старте. Если провайдер не зарегистрирован или образовался цикл, приложение не поднимется, а не упадёт на первом запросе.
- Токены позволяют подменять реализацию.
useClass,useValueиuseFactoryописывают, что именно попадёт в зависимость; в тестеoverrideProviderзаменяет её без изменения кода сервиса. - Модуль — единица экспорта. Провайдер виден другим модулям только через
exports, что дисциплинирует границы лучше, чем договорённость. - Scope имеет цену. По умолчанию провайдер — singleton. Request-scoped провайдер создаётся на каждый запрос и поднимает scope по цепочке потребителей; для stateless-сервиса это лишняя работа, и брать его стоит только ради контекста запроса.
Обратная сторона — церемонии: декораторы, метаданные, рефлексия, больше файлов и требование TypeScript. Для сервиса из десяти эндпоинтов ручной createApp короче и прозрачнее. Nest оправдан, когда модулей и людей много, а единые слои, guards, pipes и interceptors экономят больше, чем стоит контейнер. Сравнение подходов — в статье «Fastify и NestJS».
Границы модулей
Слои отвечают на вопрос «кто за что», модули — «что можно менять независимо». Модуль — вертикальный срез: свои контроллеры, сервисы, репозитории и схемы, объединённые одним доменным понятием.
modules/tasks/
index.js # публичный API: только то, что можно импортировать снаружи
tasks.controller.js
tasks.service.js
tasks.repository.js
tasks.schema.js
tasks.errors.js
// modules/tasks/index.js
export { createTasksService } from './tasks.service.js';
export { createTasksRouter } from './tasks.routes.js';
// repository, row-мапперы, внутренние схемы и типы не экспортируются
Правило простое: снаружи импортируют только публичный API модуля. Глубокий импорт modules/tasks/tasks.repository.js из billing создаёт связь с внутренностью и делает невозможным рефакторинг без правки чужого кода. Если двум модулям нужен один запрос к таблице, это либо общий репозиторий с явным владельцем, либо отдельный модуль данных, но не копипаста и не импорт внутренностей.
Границу держат не договорённостью, а инструментом:
eslint-plugin-boundariesилиdependency-cruiserзапрещают импорт изmodules/*/кромеindex;- тест на архитектуру проверяет, что модуль не тянет соседа;
- code review смотрит не на стиль, а на направление зависимости.
Цикл между модулями — почти всегда сигнал неверной границы. Если tasks нужен projects, а projects нужен tasks, вариантов обычно три: вынести общее понятие в отдельный модуль, передавать данные через аргумент, а не тянуть сервис, или заменить обратный вызов событием.
Общий код живёт отдельно: lib/logger.js, lib/db.js, lib/errors.js, lib/config.js. В shared/ не должно быть бизнес-логики: как только там появляется «общий сервис задач», он становится скрытым центром, от которого зависят все.
В монорепозитории модуль может стать пакетом. Workspace’ы и локальные зависимости позволяют версионировать контракт между пакетами и собирать только затронутые — об этом в статье «Монорепозитории» и в «npm и экосистема пакетов».
Модульный монолит и микросервисы
Монолит не является синонимом плохой архитектуры, а микросервисы — синонимом хорошей. Разница между ними — не размер кода, а граница процесса и сети.
Модульный монолит — одно приложение, один деплой, но с явными модулями и запретом на импорт внутренностей. Внутри — обычные вызовы функций, одна транзакция и один процесс для отладки.
Микросервисы — несколько процессов, каждый со своей базой и контрактом. Внутри — сеть, таймауты, частичные отказы и распределённая согласованность.
| Что появляется | Монолит | Микросервисы |
|---|---|---|
| Вызов между модулями | вызов функции | HTTP/gRPC: таймауты, ретраи, сериализация |
| Согласованность | одна транзакция БД | saga, outbox, идемпотентные потребители |
| Деплой | один артефакт | N артефактов, N контрактов, порядок выката |
| Данные | одна схема | своя БД у сервиса, дублирование и синхронизация |
| Наблюдаемость | один процесс и один трейс | сквозной trace-id, корреляция логов и метрик |
| Тесты | интеграционные в одном процессе | контрактные, e2e, стенд из нескольких сервисов |
| Команда | одна | по сервису, с ответственностью за эксплуатацию |
Микросервисы стоит выделять, когда есть причина, которую не решить внутри процесса:
- независимое масштабирование — один сценарий требует в десять раз больше ресурсов, чем остальные;
- независимый релиз — разные части меняются с разной скоростью и разными командами;
- изоляция отказа — падение некритичной части не должно ронять весь API;
- разные требования — например, CPU-bound обработка изображений рядом с лёгким API;
- организационная граница — команда владеет сервисом целиком.
Плохие причины: «код стал большим», «модно», «хотим микросервисы, как у крупных». Размер кода сам по себе лечится модулями, а не сетью.
Главная ловушка перехода — распределённый монолит: сервисы выделили, но оставили общую базу, синхронные вызовы по цепочке и общий деплой. В итоге получили все минусы сети и ни одного плюса автономности. Если два сервиса не могут меняться независимо и ходят в одну таблицу, это один сервис, разрезанный по ошибке.
Практический путь — strangler fig: сначала модульный монолит с явными границами, затем выделение по одной границе, с проверкой, что она действительно stable. Для событий между сервисами нужен outbox и идемпотентный потребитель; для вызовов — таймауты, ретраи и breaker из статьи «Таймауты, ретраи и graceful shutdown». Наблюдаемость без сквозного trace-id в микросервисах не работает — см. «Логирование и наблюдаемость».
Версионирование API и совместимость
Публичный API — это обещание. Клиенты обновляются не одновременно с сервером: мобильное приложение живёт в сторах месяцами, партнёрская интеграция — годами, а чужой скрипт может ходить в ваш эндпоинт без всякой документации. Поэтому совместимость — не вежливость, а условие работы.
Изменения делятся на две группы.
| Изменение | Совместимо | Комментарий |
|---|---|---|
| Добавить необязательное поле в ответ | да | старые клиенты его игнорируют |
| Добавить новый эндпоинт | да | старый контракт не меняется |
| Добавить необязательный query-параметр | да | поведение по умолчанию сохраняется |
| Удалить или переименовать поле | нет | клиент читает undefined |
Поменять тип (number → string) | нет | ломается парсинг и сравнение |
| Сделать необязательное поле обязательным | нет | старые запросы начнут падать |
| Изменить смысл значения или код ошибки | нет | клиент принимает решение по старой логике |
| Добавить значение в enum | рискованно | строгий клиент может не знать новый вариант |
Последняя строка — частая ошибка. Формально новое значение enum ничего не удаляет, но клиент с switch без default падает или показывает пустой экран. Если enum публичный, новое значение — это изменение контракта, и его либо анонсируют, либо добавляют в новую версию.
Когда нужна версия. Только для несовместимого изменения. Версионировать каждый релиз — значит плодить /v2, /v3 без причины и заставлять клиентов обновляться там, где можно было просто добавить поле. Версия API и версия деплоя — разные вещи: сервис может выкатываться десять раз в день, оставаясь на /v1.
Основные стратегии:
- URI-версия —
/v1/tasks,/v2/tasks. Проста, видна в логах и кеше, легко маршрутизируется. Самый частый выбор. - Заголовок —
Accept: application/vnd.taskflow.v2+jsonили свойX-API-Version. Гибче, но сложнее для отладки, кеша и ручных проверок. - Параметр —
?version=2. Прост, но легко потерять при копировании URL и трудно кешировать. - Версия через клиента —
X-Client-Version, с серверной адаптацией. Полезно, когда версий много и они соответствуют релизам приложения, но требует дисциплины на сервере.
Практичный минимум: URI-версия для ломающих изменений, additive-изменения внутри текущей, явный процесс deprecation.
Deprecation — это не удаление, а объявленный период, когда старая версия ещё работает. Клиенту сообщают заголовками и документацией, а команда смотрит метрики использования.
// v1 — тонкий адаптер над текущим сервисом
router.get('/v1/tasks/:id', async (req, res) => {
const task = await tasks.getById(req.params.id);
res.set('Deprecation', '@1798761600'); // 2027-01-01T00:00:00Z, структурированная дата
res.set('Sunset', 'Fri, 01 Jan 2027 00:00:00 GMT');
res.set('Link', '</v2/tasks>; rel="successor-version"');
res.json({ id: task.id, title: task.title, done: task.status === 'done' });
});
Заголовок Sunset (RFC 8594) сообщает дату отключения, Deprecation — с какой даты эндпоинт считается устаревшим, Link указывает замену. Это не заменяет письмо партнёру, но даёт машиночитаемый сигнал и попадает в логи.
Процесс выглядит так:
- Новая версия появляется рядом со старой, обе обслуживаются одним сервисом.
- Старая версия получает заголовки deprecation и запись в changelog.
- Метрики считают долю запросов к старой версии по клиентам.
- После миграции и окончания
Sunsetстарая версия удаляется.
Контрактные тесты ловят расхождение раньше клиента. OpenAPI-схема в репозитории, сравнение версий (oasdiff), тест, который проверяет, что ответ соответствует схеме, и тест на совместимость с сохранённым примером старого клиента — всё это дешевле, чем разбор инцидента с мобильным приложением.
Для событий между сервисами действует то же правило, только строже: сообщение живёт в очереди дольше, чем длится деплой, а потребитель может быть старой версии. Схема события версионируется отдельно, новые поля добавляются необязательными, а удаление — только после того, как все потребители обновились.
Практика: TaskFlow
Соберём структуру TaskFlow из предыдущих статей: Express, PostgreSQL, Redis, BullMQ и воркер уведомлений. Цель — показать, как слои соединяются в одном приложении, не превращаясь в церемонию.
src/
app.js
server.js
lib/
db.js
logger.js
errors.js
outbox.js
transport/http/
middleware/request-id.js
middleware/auth.js
middleware/error-mapper.js
modules/
tasks/
tasks.controller.js
tasks.service.js
tasks.repository.js
tasks.schema.js
tasks.routes.js
index.js
projects/
projects.service.js
projects.repository.js
index.js
notifications/
notifications.worker.js
index.js
1. Сборка. app.js — единственное место, где создаются пул, репозитории и сервисы. server.js только вызывает createApp, делает listen и вешает обработчики сигналов. Тест импортирует createApp и не занимает порт.
2. Слои. Контроллер разбирает req и вызывает tasks.create. Сервис проверяет членство в проекте, открывает транзакцию, пишет задачу и событие в outbox. Репозиторий выполняет SQL и маппит строку в доменный объект. Ни один слой не знает про внутренности другого.
3. Валидация. Схемы zod описывают body, query и ответ. Контроллер применяет parse, error middleware превращает ZodError в 422 с полями. В сервис попадают только проверенные данные.
4. Права. requireAuth на маршруте отвечает за аутентификацию. Проверка «пользователь состоит в проекте» и «задачу можно менять» — в сервисе, потому что тот же сценарий вызывает воркер.
5. Транзакция и событие. Задача и запись outbox коммитятся вместе. Диспетчер забирает неотправленные события и публикует их в BullMQ; воркер уведомлений идемпотентен по eventId. Если процесс упал между коммитом и публикацией, событие останется в outbox и уйдёт после рестарта.
6. Тест без инфраструктуры. Сервис собирается с фейковыми репозиториями и outbox:
// tests/tasks.service.test.js
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { createTasksService } from '../src/modules/tasks/tasks.service.js';
function createFakes({ member = true } = {}) {
const inserted = [];
return {
tasks: {
async insert(task) {
const created = { id: 't1', ...task };
inserted.push(created);
return created;
},
},
projects: {
async findById() {
return { id: 'p1', hasMember: () => member };
},
},
events: { async record() {} },
db: { async transaction(fn) { return fn({}); } },
logger: { info() {} },
inserted,
};
}
test('создаёт задачу, если пользователь состоит в проекте', async () => {
const fakes = createFakes();
const service = createTasksService(fakes);
const task = await service.create({ projectId: 'p1', title: 'Первая', userId: 'u1' });
assert.equal(task.title, 'Первая');
assert.equal(fakes.inserted.length, 1);
});
test('отказывает, если пользователь не состоит в проекте', async () => {
const service = createTasksService(createFakes({ member: false }));
await assert.rejects(
() => service.create({ projectId: 'p1', title: 'Первая', userId: 'u2' }),
{ status: 403, code: 'forbidden' },
);
});
7. Границы. modules/tasks/index.js экспортирует сервис и роутер. billing не импортирует tasks.repository.js; если нужны данные задачи, он получает их через публичный метод или событие.
Что закрыто: правило живёт в сервисе, SQL — в репозитории, HTTP — в контроллере, зависимости собираются в одном месте, тест проверяет сценарий без базы и порта, а контракт API отделён от схемы хранения. Дальше остаётся эксплуатация: тесты на границах, безопасность и деплой — статьи «Тестирование Node-приложений», «Безопасность Node API» и «Docker и деплой Node.js».
Частые ошибки
- SQL в контроллере. Сценарий нельзя переиспользовать из воркера, а тест требует базы.
- Бизнес-правило в репозитории. Права и инварианты начинают зависеть от способа хранения.
- Транзакция на каждый запрос репозитория. Несколько записей одного сценария не атомарны.
- Транзакция в контроллере. Контроллер знает шаги сценария и ломает границу.
- Доменный объект в
res.json. Внутренние поля утекают в API. - Строка БД в сервисе.
snake_case, строковыйnumericи лишние поля таблицы расползаются по бизнес-логике. - Универсальный
Repository<T>. Возвращает query builder под другим именем и не даёт доменных методов. - Импорт
poolиз модуля. Скрытая зависимость, тесты с реальной базой и невозможность собрать два приложения. - Service locator. Зависимость не видна в сигнатуре, подмена требует знания внутренностей.
- Инъекция всего в один сервис. «Божественный сервис» на двадцать зависимостей — это не DI, а отсутствие границ.
- Глубокий импорт между модулями.
modules/billingтянетmodules/tasks/tasks.repository.js. - Цикл модулей. Признак неверной границы, а не повод для
import()внутри функции. - Общий
shared/с бизнес-логикой. Скрытый центр, от которого зависят все модули. - Валидация только в TypeScript. В рантайме
JSON.parseдаётany, и без схемы никто не проверяет форму. req.bodyв сервис целиком. Mass assignment: клиент добавляетrole,ownerId,tenantId.- Версия API на каждый релиз.
/v2без ломающих изменений плодит поддержку. - Удаление поля без deprecation. Клиент получает
undefinedи падает в проде. - Enum без стратегии. Новое значение ломает строгих клиентов, хотя формально ничего не удалено.
- Микросервисы до стабильных границ. Распределённый монолит с сетью, общей базой и общим деплоем.
- Общая база у нескольких сервисов. Схема становится неявным контрактом, менять её независимо нельзя.
- Синхронная цепочка из пяти сервисов. Задержки складываются, а вероятность отказа перемножается.
- Событие до
commit. Потребитель видит данные, которых ещё нет, или не видит их при откате.
Ключевые тезисы для интервью
- Слои — это направление зависимостей, а не набор папок: transport → controller → service → repository, а обратное движение идёт через результат, событие или внедрённый интерфейс.
- Контроллер переводит HTTP в вызов сценария и обратно; бизнес-правил, SQL и транзакций в нём нет, иначе второй транспорт обойдёт логику.
- Сервис владеет инвариантами, правами и границей транзакции; он не знает про
req/res, поэтому один сценарий работает и из HTTP, и из очереди, и из CLI. - Репозиторий — единственное место с SQL: интерфейс на языке домена, маппинг строк и транзакционный контекст, а не универсальный query builder.
- DI без фреймворка — это composition root и фабрики: граф виден в одном месте, тесты подставляют фейки, а не мокают модули; контейнер и NestJS делают то же, но через рефлексию и токены.
- Модульный монолит с явными границами дешевле микросервисов, пока независимый деплой, масштабирование и изоляция отказа не перевесят сеть, распределённые транзакции и стоимость эксплуатации.
- Совместимость API — это добавление без удаления и объявленный deprecation; версия нужна для ломающих изменений, а контрактные тесты ловят расхождение раньше клиента.
Заключение
Архитектура Node-бэкенда начинается с границ: где живёт правило, кто владеет данными и что можно менять независимо. Слои transport → controller → service → repository дают ответ на первый вопрос, модули с публичным API — на второй, а контракт и версионирование — на третий.
Слоистость не требует фреймворка: composition root и фабрики дают явный граф зависимостей и тестируемость, а NestJS добавляет к этому контейнер, модули и проверку графа на старте. Цена — церемонии и рефлексия, выгода — единые правила в большом проекте.
Микросервисы — не следующий шаг после монолита, а инструмент под конкретную причину. Пока границы не устоялись, модульный монолит дешевле и честнее; выделять стоит по одной границе, когда независимость действительно нужна. А публичный API меняется добавлением и deprecation, а не удалением и надеждой, что клиенты обновятся.
Полезные ссылки
- Martin Fowler: MonolithFirst — почему начинать с монолита разумно
- Martin Fowler: Strangler Fig Application — постепенное выделение сервисов
- Martin Fowler: Patterns of Enterprise Application Architecture — слои, репозиторий, unit of work
- NestJS: Modules — провайдеры, exports и границы модулей
- NestJS: Custom providers —
useClass,useValue,useFactoryи токены - Fastify: Encapsulation — плагины и изоляция контекста
- Node.js:
AsyncLocalStorage— контекст запроса без протаскивания через слои - zod — схемы, вывод типов и разбор ошибок
- RFC 8594: The Sunset HTTP Header — объявление даты отключения API
- RFC 9745: The Deprecation HTTP Response Header Field — структурированная дата устаревания
- OpenAPI Specification — контракт API как источник истины
- oasdiff — сравнение версий OpenAPI и поиск ломающих изменений
- Валидация и конфигурация — схемы входа,
unknownи DTO - Доступ к базам данных — пул, транзакции, N+1 и репозитории
- Тестирование Node-приложений — unit, интеграционные тесты и testcontainers
- Таймауты, ретраи и graceful shutdown — надёжность вызовов и остановка сервиса
- Логирование и наблюдаемость — request-id, метрики и трассировка между сервисами
- Redis и фоновые задачи — outbox, очереди и идемпотентные воркеры
- REST — ресурсы, идемпотентность и коды ответов
- Монорепозитории — workspace’ы и пакеты для общих контрактов