Files
it-smi/docs/50-developing/01-api-layers.md
T
arswarog dbd5762ecf docs: документация по архитектуре, данным и деплою
Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой
миграций, а также оглавление документации и README шаблона.
2026-10-27 10:43:49 +03:00

11 KiB

Слои API

Модуль — единица организации кода в apps/api: внутри него код разложен по слоям, а наружу он поставляет только то, что осознанно экспортирует.

Слоёв три, и зависимости между ними идут строго в одну сторону:

Controller → Service → Data Access Layer

Сквозь все три слоя проходят два контракта данных:

  • DTO — форма данных на границе HTTP: что приходит в запросе и что уходит в ответе.
  • Entities — форма данных на границе БД: из чего состоит таблица.

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

Controllers

Тонкий контроллер.

Контроллер — точка входа HTTP. Он принимает запрос, объявляет контракт ручки для Swagger, проверяет формат входных данных и делегирует работу сервису. При этом контроллер не принимает доменных решений, не вычисляет и не агрегирует данные: почти всё тело метода занимает объявление API.

Контроль доступа на этом уровне декларативный: JwtAuthGuard, RolesGuard с @Roles(...), ProjectAccessGuard с декоратором роли в проекте. Проверка «пользователь — админ?» или «есть ли доступ к проекту?» читается из декораторов, а не вычисляется в теле метода. Валидация формата подключается пайпом на конкретный параметр (@Body(...), @Query(...)), а не на весь метод: у проекта нет глобального ValidationPipe.

Входит:

  • Контроль доступа на основе декларативных систем (guards, роли, декораторы)
  • Описание API (Swagger-декораторы, HTTP-статусы ответов)
  • Проверка формата входных данных (пайпы, DTO)

Не входит:

  • Бизнес-логика
  • Проверка входных данных на основе бизнес-правил
  • Транзакции
  • Запросы к БД

Services

Бизнес-логика и оркестрация.

Сервис — место, где принимаются решения. Здесь проверяются бизнес-правила, бросаются доменные ошибки, оркестрируются вызовы DAL и публичных сервисов других модулей, открываются транзакции и пишутся бизнес-события. Сложный домен делится на вложенные модули — по одному на поддомен (пример — billing/modules/*), а не разрастается в один сервис на весь домен.

В публичный API модуля попадают сервисы, но не обязательно все: exports перечисляет их явно. Другие модули импортируют только сервисы, поэтому правило «доступ к данным чужого домена — через его публичный сервис» выполняется именно здесь, на уровне сервисов.

Входит:

  • Бизнес-логика
  • Оркестрация: вызовы своего DAL и публичных сервисов других модулей
  • Транзакции (через DataSource — единственное исключение из правила «TypeORM только в DAL»)
  • Контроль доступа на основе сложных бизнес-правил
  • Проверка входных данных на основе бизнес-правил
  • Логирование бизнес-событий
  • Вызовы внешних систем — после коммита транзакции

Не входит:

  • Выполнение запросов к БД
  • Прямой доступ к репозиториям и QueryBuilder TypeORM
  • HTTP-специфика (объекты Request/Response, HTTP-статусы)

Data Access Layer

Абстракция над БД.

DAL знает о бизнес-сущностях и предоставляет к ним удобный API. Сервис вызывает осмысленный метод и получает данные, не зная, как именно они достаются. DAL возвращает сущности как есть — отдельного слоя доменных моделей и мапперов в проекте нет.

Минимум бизнес-логики: решения принимает сервис. Исключение — логика, которую необходимо выполнять на стороне БД: агрегаты, массовые UPDATE/upsert, выборки с блокировкой, оконные функции. Ради них DAL может выполнять чужую таблицу через join вместо похода в чужой сервис.

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

Высокоуровневый API к данным выглядит так: findById, getActiveProjects, softRemoveComment, getCommentsWithAuthors — за именем стоит намерение, а не способ выборки (имена условные, они показывают уровень абстракции, а не конкретный модуль). Методы добавляются по мере необходимости, а не заранее «чтобы было». Метод принимает опциональный manager?: EntityManager: открывать транзакцию или нет — решает вызывающий, DAL лишь работает с тем контекстом, который ему передали.

Транзакции, приватность модуля и логика на стороне БД разобраны подробно в слое доступа к данным.

Входит:

  • Выполнение запросов
  • Логика, которую необходимо выполнять на стороне БД

Не входит:

  • Бизнес-логика (кроме логики, выполняемой в БД)
  • Открытие транзакций
  • Знание о HTTP и о том, кто его вызвал

DTO

Контракт входа и валидация формата.

DTO описывает форму данных на границе HTTP: тело запроса, query-параметры, тело ответа. В нём объявлены поля, Swagger-описание (@ApiProperty) и class-validator-декораторы формата. Это описание данных, а не поведение: своих методов у DTO нет, кроме статической фабрики from — она переводит в форму ответа то, что вернул сервис, и держит белый список полей рядом с контрактом. Один DTO — один контракт ручки.

Валидация формата (тип, обязательность, диапазон, формат строки) живёт здесь; проверка на основе бизнес-правил — уже в сервисе. DTO описывает и вход, и выход: response-модели вроде *-response.dto.ts кладутся в те же dto/ и подставляются в @ApiOkResponse({ type: ... }). Отдельного слоя ответов нет; часть модулей держит свои read-модели плоскими интерфейсами в *.types.ts.

Входит:

  • Форма входных и выходных данных
  • Валидация формата
  • Swagger-описание полей
  • Перевод данных в форму ответа — статическая фабрика from у response-моделей

Не входит:

  • Бизнес-логика
  • Обращения к БД
  • Решения на основе бизнес-правил
  • Собственные методы, кроме from: входной DTO заполняет ValidationPipe, а не код самого DTO, а считать и решать, что отдавать, — дело сервиса

Entities

Схема таблицы, а не модель поведения.

TypeORM-сущность описывает таблицу: колонки, типы, связи, индексы и имя таблицы. Имя таблицы — константа *_TABLE_NAME, объявленная рядом с сущностью и используемая в коде приложения. Сущность содержит только поля и связи — Active Record не используется, методов сохранения или поиска на ней нет.

Бизнес-логики и валидации в сущности тоже нет: и то, и другое живёт в сервисе, а структура таблицы — здесь. Соглашения об именовании, расположении и связях описаны в сущностях, таблицах и колонках.

Входит:

  • Схема таблицы: колонки и типы
  • Связи и правила onDelete
  • Индексы
  • Имя таблицы

Не входит:

  • Бизнес-логика
  • Методы save/find и любой доступ к данным
  • Валидация входных данных
  • Правила доступа