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,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 по общему правилу.
|
||||
Reference in new issue
Block a user