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

189 lines
12 KiB
Markdown

# Слой доступа к данным (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 по общему правилу.