docs: документация по архитектуре, данным и деплою
Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой миграций, а также оглавление документации и README шаблона.
This commit is contained in:
1 parent
9d5478ddeb
commit
dbd5762ecf
10 files changed
+1308
-87
No files matched your search
@@ -0,0 +1,167 @@
|
||||
# Слои 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 лишь работает с тем контекстом, который ему передали.
|
||||
|
||||
Транзакции, приватность модуля и логика на стороне БД разобраны подробно в
|
||||
[слое доступа к данным](30-data-access.md).
|
||||
|
||||
**Входит:**
|
||||
|
||||
- Выполнение запросов
|
||||
- Логика, которую необходимо выполнять на стороне БД
|
||||
|
||||
**Не входит:**
|
||||
|
||||
- Бизнес-логика (кроме логики, выполняемой в БД)
|
||||
- Открытие транзакций
|
||||
- Знание о 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` не используется, методов сохранения или поиска на ней
|
||||
нет.
|
||||
|
||||
Бизнес-логики и валидации в сущности тоже нет: и то, и другое живёт в сервисе, а структура таблицы —
|
||||
здесь. Соглашения об именовании, расположении и связях описаны в
|
||||
[сущностях, таблицах и колонках](10-persistence.md).
|
||||
|
||||
**Входит:**
|
||||
|
||||
- Схема таблицы: колонки и типы
|
||||
- Связи и правила `onDelete`
|
||||
- Индексы
|
||||
- Имя таблицы
|
||||
|
||||
**Не входит:**
|
||||
|
||||
- Бизнес-логика
|
||||
- Методы `save`/`find` и любой доступ к данным
|
||||
- Валидация входных данных
|
||||
- Правила доступа
|
||||
Reference in new issue
Block a user