Навигация

Архитектура Node-бэкенда

Первые эндпоинты пишутся почти без решений: маршрут, обработчик, запрос в базу — и всё работает. Проблемы начинаются позже, когда правило про права доступа живёт в трёх местах, тест на бизнес-логику требует поднять HTTP и PostgreSQL, а выделить один модуль в отдельный сервис нельзя, потому что он импортирует половину проекта. Архитектура серверного Node-приложения — это ответы на три вопроса: где живёт правило, от чего зависит модуль и что нужно поднять, чтобы проверить изменение.

Содержание

  1. Зачем сервису архитектура
  2. Слои: transport, controller, service, repository
  3. Контроллер: граница HTTP
  4. Сервис: инварианты и транзакция
  5. Репозиторий: единственное место с SQL
  6. Типы и данные между слоями
  7. Валидация на границах
  8. DI без фреймворка: composition root
  9. DI в NestJS
  10. Границы модулей
  11. Модульный монолит и микросервисы
  12. Версионирование API и совместимость
  13. Практика: TaskFlow
  14. Частые ошибки
  15. Ключевые тезисы для интервью
  16. Заключение
  17. Полезные ссылки

Зачем сервису архитектура

Архитектуру полезно мерить не количеством слоёв и папок, а стоимостью следующего изменения. Если добавить поле в ответ API — это правка в одном месте, архитектура работает. Если нужно найти все места, где собирается объект задачи, — нет.

Симптомы обычно выглядят как технические мелочи, но указывают на одно: у правила нет владельца, а у модуля нет границы.

СимптомЧто на самом деле
Тест на бизнес-правило требует базы и HTTPзависимости жёсткие, сценарий не отделён от транспорта
Одно правило продублировано в HTTP, воркере и cronнет сервисного слоя, логика живёт в обработчиках
Поле БД меняется в пяти файлахсхема и доменная модель не разделены
Модуль нельзя вынести в пакетон импортирует внутренности соседей
Релиз API ломает клиентовконтракт не отделён от кода и схемы данных
Непонятно, что сломается при замене ORMORM-типы и query builder протекли в бизнес-логику

Архитектура отвечает сразу на трёх уровнях:

  • код — как разложены ответственности и куда направлены зависимости;
  • процесс — один монолит, несколько модулей или несколько сервисов;
  • контракт — что именно сервис обещает клиентам и как это обещание меняется.

Слои не нужно вводить «на всякий случай». Для пяти эндпоинтов и одной команды плоская структура может быть честнее. Но как только появляется второй транспорт (воркер очереди, cron, WebSocket), второе правило с теми же данными или второй человек в коде, разделение на сценарии и доступ к данным перестаёт быть церемонией.


Слои: transport, controller, service, repository

Классическая серверная раскладка — четыре роли. Важно, что это именно роли, а не обязательные четыре папки: иногда controller и transport сливаются в route handler, иногда репозиторий и сервис живут в одном модуле. Ответственности при этом остаются разными.

СлойЗа что отвечаетЧто знаетЧего не знает
transportприём соединений, парсинг протокола, middleware, маршрутизацияHTTP, WebSocket, формат очередибизнес-правила
controllerперевод запроса в вызов сценария и результата обратно в ответDTO, сервис, коды и заголовкиSQL, транзакции, устройство БД
serviceправила, инварианты, права, граница транзакциидоменные типы, интерфейсы репозиториев, unit of workreq/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,
  };
}

Три вещи, которые даёт такой слой:

  1. Единое место для запросов к агрегату. Все select и update задач собраны здесь, и при добавлении deleted_at не нужно искать их по всему проекту.
  2. Маппинг, а не сырые строки. Наружу уходят camelCase-объекты с Date, а не snake_case-строки и numeric в виде строк. Сервис не зависит от того, как драйвер представил count.
  3. Транзакционный контекст как параметр. tx = db позволяет вызвать метод и вне транзакции, и внутри неё, не создавая второй пул и не открывая отдельное соединение. Это же решение закрывает проблему «репозиторий внутри транзакции взял другой клиент».

Чего репозиторий делать не должен:

  • Проверять бизнес-правила. «Нельзя завершить задачу в архивированном проекте» — правило сервиса. Репозиторий может проверить только то, что является инвариантом хранения: уникальность, внешний ключ, check.
  • Бросать HTTP-ошибки. 404 и 403 — язык транспорта. Репозиторий возвращает null или бросает ошибку драйвера.
  • Превращаться в универсальный Repository<T>. find(criteria) с произвольным объектом условий — это тот же query builder, только с другим названием. Доменные методы (findActiveForProject, listOverdue) читаются лучше и не дают собрать случайный запрос из данных клиента.
  • Скрывать N+1. Репозиторий с методом getProjectTasks может тянуть связи лениво; счётчик запросов и план запроса проверяют на границе, а не в сервисе. Об этом — в статье «Доступ к базам данных».

Для сложных чтений — отчётов, списков с фильтрами и агрегатами — иногда честнее отдельная query-функция, которая сразу возвращает read-модель, без доменного объекта и репозитория. Это нормальное отклонение, если оно названо явно и не используется для записи: гонять сложный join через «универсальный репозиторий» дороже и запутаннее.


Типы и данные между слоями

Один и тот же объект в сервисе выглядит по-разному на трёх границах. Если не разделять эти представления, схема базы начнёт диктовать контракт API, а клиент — влиять на устройство хранения.

ГраницаЧто приходитЧто внутриЧто уходит
HTTPDTO из схемы (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, но им не являются:

  1. Service locator. container.get('tasksService') внутри функции прячет зависимость: её не видно в сигнатуре, и тест не знает, что подменять.
  2. Глобальный контейнер на весь процесс. Он удобен, пока приложение одно; в тестах и в нескольких инстансах начинается борьба за состояние.
  3. Инъекция всего подряд. Если сервису нужны логгер, конфиг, пять репозиториев и три клиента, это сигнал, что сценарий слишком большой, а не что 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 указывает замену. Это не заменяет письмо партнёру, но даёт машиночитаемый сигнал и попадает в логи.

Процесс выглядит так:

  1. Новая версия появляется рядом со старой, обе обслуживаются одним сервисом.
  2. Старая версия получает заголовки deprecation и запись в changelog.
  3. Метрики считают долю запросов к старой версии по клиентам.
  4. После миграции и окончания 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, а не удалением и надеждой, что клиенты обновятся.

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