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` и любой доступ к данным
|
||||
- Валидация входных данных
|
||||
- Правила доступа
|
||||
@@ -0,0 +1,150 @@
|
||||
# Слои web
|
||||
|
||||
`apps/web` — React-приложение. Его код разложен по слоям, и зависимости между слоями идут строго в
|
||||
одну сторону:
|
||||
|
||||
```
|
||||
app → pages → widgets → entities → shared
|
||||
```
|
||||
|
||||
Слой слева знает о слоях справа и пользуется ими. Обратное запрещено: `shared` не знает, где
|
||||
применён и по чьей воле вызван, а `entities` не знает о `widgets`.
|
||||
|
||||
Слой — это директория: имя слоя и есть имя директории. Одни слои существуют в проекте в одном
|
||||
экземпляре, других — столько, сколько модулей.
|
||||
|
||||
**Модуль** — не слой, а рамка. `modules/<домен>` собирает свои `entities` и `widgets` и определяет,
|
||||
что из них видно снаружи, — тем же способом, каким это делает модуль в
|
||||
[слоях API](01-api-layers.md). Поддомен — такая же рамка, вложенная внутрь модуля.
|
||||
|
||||
## app
|
||||
|
||||
**Точка входа и оболочка.**
|
||||
|
||||
`app` — внешний край приложения. Он монтирует React, объявляет маршруты и их защиту, держит
|
||||
глобальные провайдеры и рисует оболочку: шапку, подвал, лейауты, общие для целой группы страниц.
|
||||
|
||||
Сюда попадает всё, что относится к приложению целиком, а не к отдельному экрану: например, баннер
|
||||
согласия на cookie. `app` — единственный слой, который видит приложение снизу доверху, и его самого
|
||||
не импортирует никто.
|
||||
|
||||
**Входит:**
|
||||
|
||||
- Точка входа приложения
|
||||
- Маршруты и их защита
|
||||
- Глобальные провайдеры
|
||||
- Оболочка и лейауты страниц
|
||||
- Элементы, относящиеся к приложению целиком
|
||||
|
||||
**Не входит:**
|
||||
|
||||
- Конкретные страницы и их содержимое
|
||||
- Доменные данные и сценарии
|
||||
- Формы, модалки и прочие блоки интерфейса
|
||||
|
||||
## pages
|
||||
|
||||
**Общий вид страницы и расстановка блоков.**
|
||||
|
||||
`pages` отвечает за то, как страница выглядит целиком, и объявляет **хлебные крошки**. Страница
|
||||
решает, какие виджеты на ней стоят, в каком они порядке и как расположены, — и задаёт каждому
|
||||
начальные данные: идентификатор из маршрута, стартовое значение фильтра, активную вкладку.
|
||||
|
||||
Собственное состояние страницы допустимо ровно одно — то, которым страница **связывает виджеты**
|
||||
между собой. Виджеты друг о друге не знают, поэтому место их встречи — страница. Всё, что является
|
||||
бизнес-логикой или передачей сообщений между виджетами, странице не принадлежит.
|
||||
|
||||
Как и модуль, страница бывает вложенной: лейаут с вкладками — это тоже `pages`, и он объявляет
|
||||
крошки за все свои вкладки, потому что только у него есть нужные для этого данные.
|
||||
|
||||
**Входит:**
|
||||
|
||||
- Композиция виджетов и их расположение на странице
|
||||
- Хлебные крошки
|
||||
- Начальные данные виджетов
|
||||
- Состояние страницы как связь между виджетами
|
||||
|
||||
**Не входит:**
|
||||
|
||||
- Бизнес-логика
|
||||
- Собственное отображение доменных данных — это дело виджетов
|
||||
- Передача сообщений между виджетами
|
||||
- Работа с API
|
||||
|
||||
## widgets
|
||||
|
||||
**Самостоятельный блок интерфейса.**
|
||||
|
||||
Виджет сам добывает свои данные и сам держит своё состояние: открытие модалок, активную вкладку,
|
||||
раскрытые строки. Наружу он поставляет готовый блок, а внутрь принимает только параметры —
|
||||
идентификаторы и начальные значения, — поэтому страница может поставить виджет, ничего не зная о
|
||||
том, что внутри.
|
||||
|
||||
Один виджет — один законченный участок работы: `AdminCreditsSummary` рисует карточку баланса
|
||||
платёжного аккаунта и держит диалоги лотов, броней и ручного начисления.
|
||||
|
||||
Виджет собирается из `entities` и `shared` и о других виджетах на странице не знает: связать два
|
||||
виджета — задача `pages`.
|
||||
|
||||
**Входит:**
|
||||
|
||||
- Загрузка своих данных
|
||||
- Своё состояние: модалки, вкладки, раскрытия, промежуточные значения форм
|
||||
- Композиция `entities` и `shared`
|
||||
- Действия пользователя в границах блока
|
||||
|
||||
**Не входит:**
|
||||
|
||||
- Хлебные крошки и общая раскладка страницы
|
||||
- Знание о других виджетах
|
||||
- Доменные правила
|
||||
|
||||
## entities
|
||||
|
||||
**Показ доменной сущности.**
|
||||
|
||||
Entity отвечает за то, как выглядит одна доменная сущность или одно значение: `TokenValue`
|
||||
показывает значение токенов, `SummaryRow` — строку сводки. Данные приходят пропсами; entity ничего
|
||||
не загружает и ничего не меняет. Она отвечает только за вид и форматирование того, что ей передали:
|
||||
числа, даты, статусы.
|
||||
|
||||
**Входит:**
|
||||
|
||||
- Показ одной доменной сущности или значения
|
||||
- Форматирование значения: числа, даты, статусы
|
||||
- Локальное состояние отображения
|
||||
|
||||
**Не входит:**
|
||||
|
||||
- Загрузка данных
|
||||
- Действия над сущностью: создание, изменение, удаление
|
||||
- Композиция нескольких сущностей
|
||||
- Знание о странице и о том, где entity показана
|
||||
|
||||
## shared
|
||||
|
||||
**Общий слой.**
|
||||
|
||||
`shared` — фундамент: UI-примитивы (кнопка, диалог, таблица), вызовы API (`shared/api`), типы,
|
||||
утилиты форматирования, переводы. Всё это переиспользуется слоями выше и не принадлежит ни одному
|
||||
сценарию.
|
||||
|
||||
Слой ничего не знает о том, где и для чего его применили. Примитив интерфейса не подписывается на
|
||||
домен, а модуль API не решает, что показать пользователю при ошибке: решение принимает тот, кто его
|
||||
вызвал.
|
||||
|
||||
`shared` — нижний слой: его берут все, он не берёт никого.
|
||||
|
||||
**Входит:**
|
||||
|
||||
- UI-примитивы
|
||||
- Вызовы API
|
||||
- Типы и утилиты
|
||||
- Переводы
|
||||
- Форматирование значений
|
||||
|
||||
**Не входит:**
|
||||
|
||||
- Знание о том, где и в каком сценарии он применён
|
||||
- Композиция доменного интерфейса
|
||||
- Решения о том, что показать и что сделать при ошибке
|
||||
@@ -0,0 +1,99 @@
|
||||
# Сущности, таблицы и колонки
|
||||
|
||||
## Расположение сущностей
|
||||
|
||||
Все TypeORM-сущности модуля лежат в подпапке `entities/` в корне модуля:
|
||||
|
||||
```
|
||||
apps/api/src/contests/
|
||||
├── dto/
|
||||
├── entities/
|
||||
│ └── contest.entity.ts
|
||||
├── contests.controller.ts
|
||||
├── contests.module.ts
|
||||
└── contests.service.ts
|
||||
```
|
||||
|
||||
- Правило без исключений: даже если сущность в модуле одна, она всё равно в `entities/`. Иначе при
|
||||
добавлении второй сущности пришлось бы переносить первую и править все её импорты.
|
||||
- Имя файла — `<сущность>.entity.ts` в kebab-case (`project-member.entity.ts`).
|
||||
- Один файл — одна сущность.
|
||||
|
||||
## Имя таблицы — единая точка правды
|
||||
|
||||
Рядом с сущностью, в том же файле, объявляется экспортируемая константа с именем таблицы, и
|
||||
`@Entity` использует её:
|
||||
|
||||
```ts
|
||||
export const CONTESTS_TABLE_NAME = 'contests';
|
||||
|
||||
@Entity({ name: CONTESTS_TABLE_NAME })
|
||||
export class Contest {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
- Константа именуется `<СУЩНОСТЬ>_TABLE_NAME` в SCREAMING_SNAKE_CASE.
|
||||
- Значение — `snake_case`, множественное число (`contests`, `project_members`).
|
||||
- `@Entity()` без явного `name` не используется: имя таблицы не должно выводиться из имени класса —
|
||||
переименование класса тогда молча меняет схему.
|
||||
|
||||
Константа — единая точка правды об имени таблицы для кода приложения: `@Entity`, DAL, raw-SQL,
|
||||
алиасы `createQueryBuilder`, утилиты очистки в тестах. Строковый литерал с именем таблицы за
|
||||
пределами объявления константы в коде приложения не пишется.
|
||||
|
||||
### Миграции константу не используют
|
||||
|
||||
Миграция — снимок схемы на момент, когда её написали, и она обязана оставаться рабочей независимо от
|
||||
того, что стало с кодом дальше. Поэтому **в миграции имя таблицы пишется строковым литералом**.
|
||||
|
||||
Пример из репозитория: коммит `b710c1b9` удалил модуль подписок вместе с файлом
|
||||
`subscriptions/subscription-plan.entity.ts` — а миграции `1774000000000-add-subscription-plans.ts` и
|
||||
`1788825600000-drop-subscriptions-and-metrics-limits.ts` никуда не делись и по-прежнему создают и
|
||||
удаляют таблицу `subscription_plans`. Импортируй они константу из удалённого файла — сборка встала
|
||||
бы целиком: миграции попадают в бандл `data-source.js` статическими импортами.
|
||||
|
||||
Обратная сторона того же правила: значение константы менять **можно**, миграции на него не смотрят.
|
||||
Переименование таблицы — это новое значение константы плюс миграция с двумя литералами:
|
||||
|
||||
```ts
|
||||
await queryRunner.renameTable('contests', 'brand_contests');
|
||||
```
|
||||
|
||||
## Имена колонок
|
||||
|
||||
Колонки — `camelCase` (`logoId`, `totalBudget`, `createdAt`), в отличие от `snake_case` у таблиц.
|
||||
Это не разнобой, а следствие дефолтной стратегии именования TypeORM: имя колонки выводится из имени
|
||||
свойства как есть, и в `@Column()` его не дублируют. С таблицей так нельзя — её имя выводилось бы из
|
||||
имени класса, — поэтому она и задаётся явно.
|
||||
|
||||
Практическое следствие: Postgres приводит неэкранированный идентификатор к нижнему регистру, так что
|
||||
в raw-SQL такая колонка пишется только в двойных кавычках:
|
||||
|
||||
```sql
|
||||
ALTER TABLE "contests" DROP COLUMN IF EXISTS "totalBudget";
|
||||
```
|
||||
|
||||
## Nullable-колонки — явный `type`
|
||||
|
||||
Если тип свойства — объединение с `null`, тип колонки задаётся в декораторе явно:
|
||||
|
||||
```ts
|
||||
@Column({ type: 'varchar', nullable: true })
|
||||
banReason: string | null;
|
||||
|
||||
@Column({ type: 'timestamp', nullable: true })
|
||||
emailVerificationTokenExpires: Date | null;
|
||||
```
|
||||
|
||||
Без `type` TypeORM выводит тип колонки из метаданных декоратора (`design:type`), а для объединения
|
||||
`string | null` TypeScript отдаёт `Object` — вывести из него тип колонки нельзя, и приложение падает
|
||||
на старте с `ColumnTypeUndefinedError` ещё до первого запроса. Ошибка вылезает только при реальном
|
||||
поднятии контекста: юнит-тесты сервиса метаданные сущностей не строят и остаются зелёными.
|
||||
|
||||
Само объявление `string | null` при этом предпочтительнее, чем `string` у nullable-колонки: тип
|
||||
сущности должен отражать то, что лежит в базе, иначе «пустое» значение приходится проверять вопреки
|
||||
типу. Схему явный `type` не меняет — `varchar` без длины это то же `character varying`, что и в
|
||||
миграции, — так что переход на `| null` у уже существующей колонки миграции не требует.
|
||||
|
||||
Как писать сами миграции — [Написание миграций](20-migrations.md).
|
||||
@@ -0,0 +1,131 @@
|
||||
# Написание миграций
|
||||
|
||||
Здесь — как **писать** миграцию. Про то, как список миграций собирается, как они применяются на
|
||||
деплое и какие есть команды, см. [Миграции базы данных](../90-deploy/10-migrations.md).
|
||||
|
||||
## DDL пишется через API TypeORM, а не строкой SQL
|
||||
|
||||
Схема меняется методами `QueryRunner` с объектами `Table` / `TableColumn`. Строка SQL в
|
||||
`queryRunner.query()` — крайняя мера, а не способ по умолчанию.
|
||||
|
||||
```ts
|
||||
import { MigrationInterface, QueryRunner, Table } from 'typeorm';
|
||||
|
||||
export class AddContests1790000000000 implements MigrationInterface {
|
||||
name = 'AddContests1790000000000';
|
||||
|
||||
public async up(queryRunner: QueryRunner): Promise<void> {
|
||||
await queryRunner.createTable(
|
||||
new Table({
|
||||
name: 'contests',
|
||||
columns: [
|
||||
{
|
||||
name: 'id',
|
||||
type: 'int',
|
||||
isPrimary: true,
|
||||
isGenerated: true,
|
||||
generationStrategy: 'increment',
|
||||
},
|
||||
{ name: 'title', type: 'varchar', length: '255', isUnique: true },
|
||||
{ name: 'logoId', type: 'varchar', length: '64', isNullable: true },
|
||||
{ name: 'description', type: 'text' },
|
||||
{ name: 'totalBudget', type: 'int' },
|
||||
{ name: 'createdAt', type: 'timestamp', default: 'now()' },
|
||||
{ name: 'updatedAt', type: 'timestamp', default: 'now()' },
|
||||
],
|
||||
}),
|
||||
);
|
||||
}
|
||||
|
||||
public async down(queryRunner: QueryRunner): Promise<void> {
|
||||
await queryRunner.dropTable('contests');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
У `createTable` есть второй аргумент `ifNotExist`, и ставить его в `true` не надо: он глушит ровно
|
||||
ту ошибку, ради которой существует [проверка перед коммитом](#проверка-перед-коммитом) — если `down`
|
||||
отработал не полностью и оставил таблицу, повторный `up` с `ifNotExist: true` пройдёт мимо дефекта
|
||||
молча. Дважды одна и та же миграция не применяется и без флага, за этим следит таблица `migrations`.
|
||||
|
||||
Имя таблицы — строковый литерал: константа `*_TABLE_NAME` из файла сущности в миграциях не
|
||||
используется, см.
|
||||
[Миграции константу не используют](10-persistence.md#миграции-константу-не-используют).
|
||||
|
||||
### `migration:generate` — это черновик
|
||||
|
||||
`typeorm migration:generate` (запуск — в
|
||||
[Как добавить миграцию](../90-deploy/10-migrations.md#как-добавить-миграцию)) всегда выдаёт тело из
|
||||
строк `queryRunner.query(...)`, иначе он не умеет. Генератор полезен тем, что показывает полный
|
||||
список расхождений схемы с сущностями — руками их легко не заметить. Но сгенерированный файл
|
||||
дописывается до конца: DDL переписывается на методы `QueryRunner`, строкой SQL остаётся только то,
|
||||
что под них не подходит.
|
||||
|
||||
### Когда допустим `queryRunner.query()`
|
||||
|
||||
Там, где API TypeORM нужную конструкцию не выражает. Типичные случаи: частичные и функциональные
|
||||
индексы (`WHERE`, `lower(...)`), `ALTER COLUMN TYPE ... USING`, `CREATE INDEX CONCURRENTLY`,
|
||||
`CREATE EXTENSION`, любые запросы к данным. В таком месте ставится комментарий, почему используется
|
||||
строка SQL.
|
||||
|
||||
## `down` пишется всегда
|
||||
|
||||
Обратный метод обязателен для каждой миграции: `db-revert` — штатная команда проекта, и откат должен
|
||||
работать не только на бумаге.
|
||||
|
||||
Если операция необратима по природе (удаление колонки с данными, добавление значения в enum-тип), у
|
||||
`down` есть два варианта: упасть с ошибкой либо откатить схему с потерей данных. Что из этого
|
||||
уместно, решается при написании конкретной миграции и фиксируется комментарием.
|
||||
|
||||
Первый вариант — откат запрещён:
|
||||
|
||||
```ts
|
||||
export class DropContestDescription1790000001000 implements MigrationInterface {
|
||||
name = 'DropContestDescription1790000001000';
|
||||
|
||||
public async up(queryRunner: QueryRunner): Promise<void> {
|
||||
await queryRunner.dropColumn('contests', 'description');
|
||||
}
|
||||
|
||||
public async down(): Promise<void> {
|
||||
// откат невозможен: значения удалённой колонки восстановить неоткуда
|
||||
throw new Error('DropContestDescription1790000001000 необратима');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Второй — та же миграция, но откат разрешён с потерей данных:
|
||||
|
||||
```ts
|
||||
public async down(queryRunner: QueryRunner): Promise<void> {
|
||||
// колонка возвращается пустой: прежние значения теряются
|
||||
await queryRunner.addColumn(
|
||||
'contests',
|
||||
new TableColumn({ name: 'description', type: 'text', isNullable: true }),
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Проверка перед коммитом
|
||||
|
||||
Миграция считается проверенной, только если на локальной БД прошёл полный цикл:
|
||||
|
||||
```bash
|
||||
yarn nx run api:db-migrate # накатить
|
||||
yarn nx run api:db-revert # откатить
|
||||
yarn nx run api:db-migrate # накатить снова
|
||||
```
|
||||
|
||||
Все три шага должны отработать без ошибок. Второй накат ловит самый частый дефект — `down`, который
|
||||
отработал не полностью и оставил в базе объект, на который потом спотыкается `up`.
|
||||
|
||||
Исключение — миграция, `down` которой намеренно падает: для неё проверяется только накат.
|
||||
|
||||
## Data-миграции — отдельным файлом
|
||||
|
||||
Изменение схемы и перенос/заполнение данных не смешиваются в одной миграции. Причина: миграция схемы
|
||||
откатывается механически, а data-миграция часто необратима в принципе; в одном файле необратимой
|
||||
становится вся пара.
|
||||
|
||||
Порядок для задачи «добавить колонку и заполнить её»: сначала миграция схемы, затем отдельной
|
||||
миграцией — бэкфилл данных.
|
||||
@@ -0,0 +1,188 @@
|
||||
# Слой доступа к данным (DAL)
|
||||
|
||||
## Зачем
|
||||
|
||||
Цель — не абстракция «на случай смены СУБД», а независимость бизнес-кода **от методов работы с
|
||||
базой**. Сервис не должен знать, что данные достаются через `Repository.findOne`, `save` или
|
||||
`QueryBuilder`: он вызывает осмысленный метод и получает данные. Тогда изменение способа выборки —
|
||||
добавление join'а, замена двух запросов одним, кэш — остаётся внутри одного файла и не требует
|
||||
трогать бизнес-логику.
|
||||
|
||||
## Как устроено
|
||||
|
||||
DAL — это обычный Nest-провайдер, технически такой же сервис, но с суффиксом `Dal`:
|
||||
|
||||
```
|
||||
apps/api/src/contests/
|
||||
├── entities/
|
||||
│ └── contest.entity.ts
|
||||
├── contests.dal.ts
|
||||
├── contests.service.ts
|
||||
├── contests.controller.ts
|
||||
└── contests.module.ts
|
||||
```
|
||||
|
||||
```ts
|
||||
@Injectable()
|
||||
export class ContestsDal {
|
||||
constructor(
|
||||
@InjectRepository(Contest)
|
||||
private readonly repository: Repository<Contest>,
|
||||
) {}
|
||||
|
||||
public findById(id: number): Promise<Contest | null> {
|
||||
return this.repository.findOne({ where: { id } });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `@InjectRepository`, `Repository`, `DataSource`, `QueryBuilder` и любые прочие API TypeORM
|
||||
допустимы **только внутри DAL**. Сервисы, контроллеры, guard'ы и интерцепторы к ним не обращаются.
|
||||
- **Active Record не используется**: сущность содержит только поля и связи, никаких методов
|
||||
сохранения/поиска на ней не появляется.
|
||||
- **Мапперы не нужны.** DAL возвращает сущности как есть; отдельный слой доменных моделей не
|
||||
вводится.
|
||||
- Методы добавляются **по мере необходимости** — под конкретный запрос вызывающего кода. Заранее,
|
||||
«чтобы было», API не пишется.
|
||||
- Типы TypeORM в сигнатурах (`FindOptionsWhere`, `FindManyOptions` и подобные) — допустимое зло:
|
||||
ради них не городится собственный язык запросов.
|
||||
|
||||
## Бизнес-логики в DAL нет
|
||||
|
||||
DAL отвечает за «достать и положить», решения принимает сервис.
|
||||
|
||||
Единственное исключение — логика, которую **необходимо выполнять на стороне БД**: агрегаты, массовые
|
||||
`UPDATE`, `upsert`, выборки с блокировками, оконные функции. Абстрагироваться от них без потери
|
||||
смысла (и производительности) нельзя, поэтому такая логика живёт в DAL.
|
||||
|
||||
## DAL — приватная часть модуля
|
||||
|
||||
DAL не попадает в `exports` модуля и **недоступен другим модулям ни при каких условиях**.
|
||||
`TypeOrmModule.forFeature([...])` регистрируется в модуле-владельце и наружу не реэкспортируется.
|
||||
|
||||
Доступ к данным чужого модуля — только через его **публичные сервисы**.
|
||||
|
||||
Исключение — тот самый случай, когда бизнес-логика реализована в DAL (выполняется в БД). Тогда
|
||||
детали схемы одного модуля могут протечь в другой: например, запрос с join'ом на чужую таблицу
|
||||
вместо похода в чужой сервис. Это допустимо, но нежелательно — так делают, когда обход через
|
||||
публичный сервис обходится дорого (N+1, выборка заведомо лишних данных), а не по умолчанию.
|
||||
|
||||
## Транзакции
|
||||
|
||||
Транзакцию открывает **сервис — владелец сценария**, а не DAL: одна транзакция накрывает вызовы
|
||||
нескольких DAL, и ни один из них не знает о соседях.
|
||||
|
||||
Ради этого сервису разрешено внедрять `DataSource` — **зафиксированное исключение** из правила «API
|
||||
TypeORM только внутри DAL». Исключение узкое: `DataSource` в сервисе используется **исключительно**
|
||||
ради `dataSource.transaction(...)`. Репозитории и `QueryBuilder` из него не берутся — вся работа с
|
||||
данными остаётся в DAL, а `manager` передаётся в его методы параметром.
|
||||
|
||||
Так устроено создание пользователя: владелец сценария `UsersService`
|
||||
(`apps/api/src/users/users.service.ts`) открывает транзакцию, а участвует в ней чужой модуль —
|
||||
`BillingAccountService` → `AccountsService` → `AccountsDal` (`apps/api/src/billing/`).
|
||||
|
||||
Дальше — схематичные примеры на вымышленном модуле конкурсов: такого кода в репозитории нет, он
|
||||
показывает форму записи, а не место. Сервис-владелец сценария:
|
||||
|
||||
```ts
|
||||
@Injectable()
|
||||
export class ContestsService {
|
||||
constructor(
|
||||
private readonly contests: ContestsDal,
|
||||
private readonly reviews: ReviewsDal,
|
||||
// Исключение: `DataSource` здесь нужен только ради `transaction`.
|
||||
@InjectDataSource()
|
||||
private readonly dataSource: DataSource,
|
||||
) {}
|
||||
|
||||
public launch(input: LaunchContestInput): Promise<Contest> {
|
||||
return this.dataSource.transaction(async (manager) => {
|
||||
await this.reviews.closeOpen(input.contestId, manager);
|
||||
|
||||
return this.contests.markLaunched(input.contestId, manager);
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
DAL принимает `manager` опциональным параметром и по нему выбирает репозиторий:
|
||||
|
||||
```ts
|
||||
@Injectable()
|
||||
export class ContestsDal {
|
||||
constructor(
|
||||
@InjectRepository(Contest)
|
||||
private readonly contests: Repository<Contest>,
|
||||
) {}
|
||||
|
||||
public findById(id: number, manager?: EntityManager): Promise<Contest | null> {
|
||||
return this.repository(manager).findOne({ where: { id } });
|
||||
}
|
||||
|
||||
private repository(manager?: EntityManager): Repository<Contest> {
|
||||
return manager?.getRepository(Contest) ?? this.contests;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Параметр опционален у любого метода — и у чтения, и у записи. Выполнять операцию в транзакции или
|
||||
нет — ответственность вызывающей стороны: метод работает с тем `manager`, который ему передали, а
|
||||
без него — вне транзакции. Так один и тот же `AccountsDal.findRegionByCode` читает справочник
|
||||
регионов и в транзакции создания пользователя (из `AccountsService.create`), и без неё — на
|
||||
стартовой проверке `BillingModule`. Выборка с блокировкой (`SELECT ... FOR UPDATE`) устроена так же:
|
||||
блокировка держится только внутри транзакции, и открыть её — забота вызывающего.
|
||||
|
||||
Публичный метод сервиса, который может участвовать в чужой транзакции, тоже принимает
|
||||
`manager?: EntityManager` и пробрасывает его дальше. Контекст передаётся явно, `AsyncLocalStorage`
|
||||
не вводится.
|
||||
|
||||
Внешние вызовы — HTTP, SMTP, очереди — внутрь транзакции не заводятся: письмо верификации
|
||||
`AuthService.registration` отправляет **после** возврата из `UsersService.createUser`, то есть после
|
||||
коммита. Иначе транзакция держит соединение с базой на время сетевого таймаута, а откат письмо уже
|
||||
не отзовёт.
|
||||
|
||||
### Модуль без своего DAL
|
||||
|
||||
Пока модуль на DAL не переведён (сегодня это `users`), внутри `dataSource.transaction(...)` все
|
||||
операции с его сущностями идут через `manager.getRepository(...)` **прямо в сервисе**. Внедрённый
|
||||
`this.userRepository` работает вне транзакции — он берёт собственное соединение, и откат его записи
|
||||
не отменит.
|
||||
|
||||
```ts
|
||||
// Сервис модуля без DAL, которому нужна транзакция:
|
||||
return this.dataSource.transaction(async (manager) => {
|
||||
// Именно `manager.getRepository`, а не внедрённый `this.userRepository`.
|
||||
const users = manager.getRepository(User);
|
||||
// Только анкетные поля: `create(dto)` перенёс бы на сущность любую пришедшую колонку и связь.
|
||||
const user = users.create({
|
||||
email: dto.email,
|
||||
password: dto.password,
|
||||
firstName: dto.firstName,
|
||||
lastName: dto.lastName,
|
||||
});
|
||||
|
||||
// Чужая операция вызывается тем же `manager`: аккаунт и строка пользователя пишутся одной
|
||||
// транзакцией. Регион резолвит сам биллинг — `users` про его конфигурацию не знает.
|
||||
const account = await this.billingAccount.create({ name: user.email }, manager);
|
||||
|
||||
user.billingAccountId = account.id;
|
||||
|
||||
return users.save(user);
|
||||
});
|
||||
```
|
||||
|
||||
Строка собирается из явного перечня анкетных полей, а не из `dto` целиком: у
|
||||
`POST /auth/registration` валидирующего пайпа нет, поэтому в воронку уезжает сырое тело анонимного
|
||||
запроса, а `create(dto)` (typeorm 0.3.x) перенёс бы на сущность и служебные колонки (`id`,
|
||||
`emailVerified`, `banned`, `refreshToken`), и связь `roles`. Перечень — основная защита воронки,
|
||||
поэтому расширяется осознанно (докблок `UsersService.createWithBillingAccount`).
|
||||
|
||||
Аккаунт заводится **до** вставки пользователя, чтобы строка сразу писалась со ссылкой
|
||||
`users.billingAccountId`, а не догонялась вторым `save`. Такой порядок возможен потому, что
|
||||
`billing_accounts` на `users` не ссылается.
|
||||
|
||||
Вне транзакции тот же сервис пишет через внедрённый `this.userRepository` — так устроены одиночные
|
||||
записи вроде `UsersService.setUserEmailVerified` и `saveRefreshToken`, где менять нечего, кроме
|
||||
одной строки `users`.
|
||||
|
||||
Оговорка временная: с появлением `users.dal.ts` этот код уезжает в DAL по общему правилу.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Тесты
|
||||
|
||||
## Расположение и имя
|
||||
|
||||
Юнит-тест лежит **рядом с тестируемым файлом**, отдельной папки под тесты нет:
|
||||
|
||||
```
|
||||
apps/api/src/contests/
|
||||
├── contests.service.ts
|
||||
└── contests.service.test.ts
|
||||
```
|
||||
|
||||
Расширение — `.test.ts` (`.test.tsx` для React-компонентов).
|
||||
|
||||
В репозитории встречается и `.spec.ts` — vitest подхватывает оба паттерна.
|
||||
|
||||
## DAL тестами не покрывается
|
||||
|
||||
Юнит-тест DAL с замоканным репозиторием проверял бы сам себя: что `findOne` вызван с теми
|
||||
аргументами, с которыми его вызвали. Такие тесты не пишутся.
|
||||
|
||||
Логика, ради которой стоит писать тест, живёт в сервисе — там она и тестируется, с замоканным DAL.
|
||||
Исключение — [БД-логика внутри DAL](30-data-access.md#бизнес-логики-в-dal-нет): её корректность
|
||||
проверяется на реальной базе, а не моками.
|
||||
|
||||
## Запуск
|
||||
|
||||
```bash
|
||||
yarn nx run api:test
|
||||
yarn nx run web:test
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
label: 'Разработка'
|
||||
Reference in new issue
Block a user