🐈 NestJS: модули и внедрение зависимостей
NestJS — фреймворк поверх Express или Fastify, который добавляет то, чего в них нет: структуру приложения и контейнер внедрения зависимостей. Ты не создаёшь сервисы руками и не передаёшь их друг другу. Ты описываешь, что кому нужно, а Nest при старте сам строит граф объектов и раздаёт экземпляры. На собеседовании по Node-бэкенду почти всегда спрашивают, чем Nest отличается от Express, как устроен DI, какие бывают scopes и почему нельзя внедрить зависимость по интерфейсу. Всё это держится на одном механизме, и его стоит понять целиком
🧠 Как это устроено
Express против NestJS
Express даёт роутинг и цепочку middleware, остальное решаешь сам: где лежат сервисы, кто создаёт подключение к базе, как подменить его в тесте. В маленьком сервисе это плюс, в проекте на пять разработчиков каждый решает по-своему
Nest не заменяет HTTP-слой, а работает поверх него через адаптер. По умолчанию это @nestjs/platform-express, рядом есть @nestjs/platform-fastify, а в NestJS 12.3 появился нативный адаптер на node:http. Сверху Nest добавляет:
| Express | NestJS | |
|---|---|---|
| Структура | любая, как договорится команда | модули, контроллеры, провайдеры |
| Зависимости | import и ручная передача | DI-контейнер, внедрение через конструктор |
| Сквозная логика | middleware | middleware, guards, pipes, interceptors, filters |
| Язык | JavaScript или TypeScript | TypeScript с декораторами |
| Тесты | моки модулей через jest.mock | подмена провайдера по токену |
| Цена | почти нет абстракций | декораторы, метаданные, свой жизненный цикл |
Сами Express и Fastify разобраны на странице про HTTP-сервер и Express, путь запроса через guards и pipes — на странице «NestJS: путь запроса»
IoC и DI
Инверсия управления (IoC) — принцип: объект не управляет созданием своих зависимостей, это делает кто-то снаружи. Внедрение зависимостей (DI) — способ реализовать этот принцип: зависимости приходят в конструктор готовыми. OrdersService не пишет new PgOrdersRepository(pool), он объявляет параметр repo: OrdersRepository, и экземпляр ему передаёт контейнер. Поэтому в тесте зависимость заменяют фейком, не трогая код сервиса
Три строительных блока
- Провайдер — всё, что контейнер умеет создать и внедрить: сервис, репозиторий, клиент Redis, объект конфига. Класс становится провайдером, когда его помечают
@Injectable()и регистрируют вprovidersмодуля - Контроллер — класс с
@Controller(), его методы привязаны к маршрутам. Контроллер принимает запрос и зовёт сервис, бизнес-логики в нём нет - Модуль — класс с
@Module(), который группирует провайдеры и контроллеры одной области и решает, что из них видно снаружи
У @Module() четыре поля. providers — что создаёт этот модуль. controllers — его контроллеры. imports — модули, чьи провайдеры нужны здесь. exports — подмножество своих провайдеров, которое получат модули, импортирующие этот
Модуль инкапсулирован. Провайдер виден только внутри своего модуля, пока его не добавили в exports. Если OrdersModule импортирует UsersModule, а тот забыл экспортировать UsersService, приложение не стартует:
Nest can't resolve dependencies of the OrdersService (?). Please make sure that
the argument UsersService at index [0] is available in the OrdersModule module.Знак ? стоит на месте параметра конструктора, который не нашёлся
Как контейнер узнаёт, что внедрить
При сборке с emitDecoratorMetadata TypeScript записывает в каждый класс с декоратором типы параметров конструктора, ключ design:paramtypes. Подробнее про эту опцию и про то, почему Nest нельзя запустить через node app.ts, на странице про tsconfig и сборку. Дальше при старте Nest делает три шага:
- Обходит дерево модулей от корневого
AppModuleпоimportsи собирает граф - Для каждого провайдера читает
design:paramtypesи ищет провайдер с таким токеном в своём модуле или среди экспортов импортированных - Создаёт экземпляры от листьев к корню: сначала то, у чего нет зависимостей, потом то, что от них зависит
Токен — ключ, по которому контейнер ищет провайдер. Для обычного сервиса токен — сам класс: запись providers: [UsersService] это сокращение от { provide: UsersService, useClass: UsersService }. Токеном может быть и строка, и Symbol, тогда в конструкторе нужен явный @Inject(TOKEN), потому что из типа параметра его не вывести
Модуль по умолчанию синглтон. Если пять модулей импортируют UsersModule, все получат один и тот же экземпляр UsersService. А вот если вписать UsersService в providers пяти модулей, получится пять разных экземпляров со своим состоянием, и это частая причина «кэш почему-то не общий»
Глобальные модули
@Global() делает экспорты модуля видимыми везде без imports. Документация советует регистрировать глобальный модуль один раз, в корневом, и не делать глобальным всё подряд: по явным imports видно, кто от чего зависит, а тест не тянет пол-приложения. Глобальными обычно оставляют конфиг, логгер и базу, как ConfigModule.forRoot({ isGlobal: true })
🛠️ На практике
Области видимости провайдеров
| Scope | Сколько экземпляров | Когда создаётся |
|---|---|---|
DEFAULT | один на приложение | при старте |
REQUEST | один на каждый входящий запрос | при запросе, после ответа уходит в сборщик мусора |
TRANSIENT | свой у каждого, кто его внедряет | при создании потребителя |
Синглтон в Node безопасен: здесь нет модели «поток на запрос», и два запроса не выполняют код сервиса одновременно в разных потоках. Поэтому DEFAULT подходит почти всегда. Чего нельзя, так это хранить в поле синглтона данные конкретного запроса: между await его перезапишет соседний запрос
REQUEST всплывает по цепочке. Если синглтон зависит от request-scoped провайдера, он сам становится request-scoped, и так до контроллера. Проверка на @nestjs/core 11:
@Injectable({ scope: Scope.REQUEST })
class RequestContext {
constructor() { console.log('new RequestContext') }
}
@Injectable() // объявлен синглтоном
class OrdersService {
constructor(private readonly ctx: RequestContext) { console.log('new OrdersService') }
}
app.get(OrdersService)
// OrdersService is marked as a scoped provider. Request and transient-scoped
// providers can't be used in combination with "get()" method. Please, use "resolve()" instead
await app.resolve(OrdersService, ContextIdFactory.create())
await app.resolve(OrdersService, ContextIdFactory.create())
// new RequestContext
// new OrdersService
// new RequestContext
// new OrdersServiceОдин request-scoped логгер с requestId внизу делает request-scoped весь путь вверх до контроллера, и Nest пересоздаёт это поддерево на каждый запрос. По документации задержка в хорошо устроенном приложении вырастет примерно на 5%, но это ещё и лишний мусор для GC. А Passport-стратегии и задачи по крону обязаны оставаться синглтонами. Для requestId и пользователя документация советует AsyncLocalStorage, он разобран на странице про конфиг, логи и готовность к проду
TRANSIENT не всплывает. Синглтон, который внедрил transient-провайдер, остаётся синглтоном, просто получает собственную копию зависимости. В той же проверке два синглтона внедрили один transient-класс и получили два разных объекта. Так делают логгер, которому нужно знать имя класса-хозяина: токен INQUIRER из @nestjs/core даёт ссылку на того, кто его создал
Durable-провайдеры — компромисс для мультитенантных приложений. Подключение к базе тенанта зависит от запроса, но пересоздавать его на каждый запрос дорого. Провайдер помечают { scope: Scope.REQUEST, durable: true }, а глобальная ContextIdStrategy раскладывает запросы по ключу, например по заголовку x-tenant-id. Запросы одного тенанта делят одно поддерево. При большом числе тенантов документация этот приём не советует
Кастомные провайдеры
export const PAYMENTS_GATEWAY = Symbol('PAYMENTS_GATEWAY')
@Module({
imports: [ConfigModule],
providers: [
// готовое значение: константа или фейк в тесте
{ provide: 'APP_VERSION', useValue: '1.4.0' },
// выбор реализации без изменения потребителей
{
provide: PAYMENTS_GATEWAY,
useClass: process.env.NODE_ENV === 'test' ? FakeGateway : AcquiringGateway,
},
// значение считает функция, зависимости перечислены в inject по порядку аргументов
{
provide: 'REDIS',
useFactory: (config: ConfigService) => new Redis(config.getOrThrow('REDIS_URL')),
inject: [ConfigService],
},
// второе имя для того же экземпляра
{ provide: 'LEGACY_REDIS', useExisting: 'REDIS' },
],
exports: [PAYMENTS_GATEWAY, 'REDIS'],
})
export class InfraModule {}useClassподставляет класс по условию. Потребитель внедряет@Inject(PAYMENTS_GATEWAY)и не знает, какая реализация пришлаuseFactoryнужен, когда объект собирается из других провайдеров или асинхронно: фабрика может вернуть промис, и Nest дождётся его до старта. Зависимость вinjectможно пометить необязательной,{ token: X, optional: true }useExisting— алиас. Оба токена дают один и тот же экземпляр, это подтвердила проверка на Nest 11
Для токенов лучше Symbol, экспортированный из одного файла: две строки 'REDIS' из разных библиотек столкнутся, два Symbol нет
Внедрение по интерфейсу
Интерфейс TypeScript стирается при сборке, и в design:paramtypes на его месте оказывается Object. Nest ищет провайдер по Object, не находит и падает при старте. Выхода два: токен-Symbol рядом с интерфейсом плюс @Inject(TOKEN) в конструкторе или абстрактный класс, который существует в рантайме и сам служит токеном. Что попадает в собранный код и чем эти варианты отличаются, подробно на странице TypeScript «Классы, интерфейсы и абстрактные классы»
Динамические модули
Модулю библиотеки нужны параметры приложения: строка подключения, ключ API. Для этого у него есть статический метод, который возвращает DynamicModule — те же providers и exports, но собранные из аргументов. Они дополняют метаданные @Module(), а не заменяют их
Названия методов — договорённость сообщества, её описывает документация:
forRoot()— настроить один раз на всё приложение, обычно вAppModuleregister()— настроить для конкретного модуля, который вызвал, у каждого свои параметрыforFeature()— взять настройку изforRoot()и уточнить для своего модуля, какTypeOrmModule.forFeature([User])регистрирует репозитории- суффикс
Asyncзначит, что параметры приходят через DI, а не литералом
TypeOrmModule.forRootAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (config: ConfigService) => ({
type: 'postgres',
url: config.getOrThrow('DATABASE_URL'),
}),
})forRoot({ url: process.env.DATABASE_URL }) читает переменную при загрузке файла, в обход ConfigService и его валидации. forRootAsync вызывает фабрику внутри DI, когда ConfigService уже создан, и получает проверенные значения. Свой модуль с register и registerAsync можно не писать руками: ConfigurableModuleBuilder генерирует оба метода
Циклические зависимости
AService внедряет BService, а тот внедряет AService. Когда классы в разных файлах, к моменту декорирования одного второй ещё не загружен, и в метаданных вместо класса undefined. Nest отвечает «Nest can't resolve dependencies of the BService (?)» без имени зависимости. Если оба класса в одном файле, при target ES2022 падает уже загрузка: ReferenceError: Cannot access 'BService' before initialization
@Inject(forwardRef(() => BService)) откладывает чтение ссылки, пока оба класса не загрузятся. Документация велит ставить его с обеих сторон, для модулей тоже: imports: [forwardRef(() => UsersModule)]. Порядок конструкторов в цикле не определён, а с request-scoped провайдерами зависимость может оказаться undefined
Лучшее решение — разорвать цикл: вынести общую часть в третий сервис или заменить прямой вызов событием. Скрытая причина цикла — barrel-файлы: класс импортирует соседа через index.ts своей же папки. Документация советует не собирать через них модули и провайдеры
⚠️ Где ошибаются
Делают request-scoped провайдер ради requestId в логах. Scope расползается по графу вверх, синглтоны начинают пересоздаваться на каждый запрос, а задача по крону, которая обязана быть синглтоном, такой сервис внедрить уже не может. Для контекста запроса есть AsyncLocalStorage
Хранят состояние запроса в поле синглтона. this.currentUser = user, потом await, потом чтение this.currentUser. Между ними другой запрос перезапишет поле, и пользователь получит чужие данные
Лечат цикл forwardRef по привычке. Он прячет плохую границу между модулями. Сначала проверь, не нужен ли третий сервис
🎯 Вопросы с собеседований
Чем Express отличается от NestJS?
Express — минимальный HTTP-фреймворк: роутинг и цепочка middleware, архитектуру выбираешь сам. NestJS работает поверх Express или Fastify через адаптер и добавляет структуру: модули, контроллеры, провайдеры и DI-контейнер, который сам создаёт и связывает объекты. Сверху ещё guards, pipes, interceptors и filters для сквозной логики. Платишь за это декораторами, сборкой с метаданными и порогом входа. Для маленького сервиса Express проще, в большой команде Nest не даёт каждому изобретать свою архитектуру
Что такое IoC и DI? Как DI устроен в NestJS?
IoC — принцип, при котором объект не создаёт свои зависимости, а получает их снаружи. DI — способ это сделать: зависимости приходят через конструктор. В Nest при сборке TypeScript с emitDecoratorMetadata пишет в класс типы параметров конструктора. При старте Nest обходит граф модулей от AppModule, для каждого провайдера находит зависимости по токенам в своём модуле и в экспортах импортированных, а потом создаёт экземпляры от листьев к корню. По умолчанию каждый провайдер — синглтон
Какие scopes бывают у провайдеров и чем опасен REQUEST?
DEFAULT — один экземпляр на приложение, создаётся при старте. REQUEST — новый экземпляр на каждый запрос. TRANSIENT — отдельный экземпляр для каждого потребителя. REQUEST всплывает по цепочке: всё, что от него зависит, вплоть до контроллера, тоже становится request-scoped и пересоздаётся на каждый запрос. Это лишние аллокации и нагрузка на GC, а задача по крону, которая обязана быть синглтоном, такой провайдер внедрить не может. Для контекста запроса обычно берут AsyncLocalStorage, а для мультитенантности — durable-провайдеры
Почему нельзя внедрить зависимость по интерфейсу и как это обойти?
Nest ищет зависимость по токену, а тип параметра берёт из метаданных, которые пишет TypeScript. Интерфейс стирается при сборке, в метаданных на его месте Object, и провайдер не находится. Обходят двумя способами. Объявляют токен, лучше Symbol, регистрируют { provide: TOKEN, useClass: Impl } и ставят @Inject(TOKEN) в конструкторе. Или делают контракт абстрактным классом: он есть в рантайме и сам служит токеном
Что такое динамический модуль и зачем нужен forRoot?
Динамический модуль собирает свои провайдеры из параметров, которые передаёт приложение, через статический метод, возвращающий DynamicModule. forRoot по договорённости настраивает модуль один раз на всё приложение: подключение к базе, клиент брокера. register настраивает для конкретного модуля, forFeature уточняет настройку forRoot для своего модуля. Вариант forRootAsync получает параметры из фабрики с inject, например из ConfigService, поэтому конфиг уже загружен и проверен, когда модуль его читает
Как решить циклическую зависимость между сервисами?
Сначала понять, нужна ли она: чаще всего цикл значит, что два сервиса делят общую логику, и её выносят в третий или заменяют прямой вызов событием. Если разорвать нельзя, ставят forwardRef(() => OtherService) в @Inject() с обеих сторон, для модулей forwardRef в imports обоих. Он откладывает чтение ссылки, пока оба класса не загрузятся. Ещё вариант — достать сервис на одной стороне через ModuleRef. Порядок конструкторов в цикле не определён, полагаться на него нельзя
📚 Что почитать
- NestJS: Injection scopes — всплытие
REQUEST,INQUIRER, durable-провайдеры иContextIdStrategyс примером для тенантов - NestJS: Custom providers — все четыре вида провайдеров, токены и экспорт кастомных провайдеров
- NestJS: Dynamic modules — договорённость
forRoot,register,forFeatureиConfigurableModuleBuilder - NestJS: Circular dependency —
forwardRefдля провайдеров и модулей,ModuleRefи предупреждение про barrel-файлы