Конвенции слоёв api и web, работа с БД и миграциями, тесты, деплой миграций, а также оглавление документации и README шаблона.
12 KiB
Слой доступа к данным (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
@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/).
Дальше — схематичные примеры на вымышленном модуле конкурсов: такого кода в репозитории нет, он показывает форму записи, а не место. Сервис-владелец сценария:
@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 опциональным параметром и по нему выбирает репозиторий:
@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 работает вне транзакции — он берёт собственное соединение, и откат его записи
не отменит.
// Сервис модуля без 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 по общему правилу.