# Слой доступа к данным (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, ) {} public findById(id: number): Promise { 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 { 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, ) {} public findById(id: number, manager?: EntityManager): Promise { return this.repository(manager).findOne({ where: { id } }); } private repository(manager?: EntityManager): Repository { 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 по общему правилу.