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

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 по общему правилу.