К содержимому
Войти

Node.js Road Map

🐈 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 добавляет:

ExpressNestJS
Структуралюбая, как договорится командамодули, контроллеры, провайдеры
Зависимостиimport и ручная передачаDI-контейнер, внедрение через конструктор
Сквозная логикаmiddlewaremiddleware, guards, pipes, interceptors, filters
ЯзыкJavaScript или TypeScriptTypeScript с декораторами
Тестымоки модулей через 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 делает три шага:

  1. Обходит дерево модулей от корневого AppModule по imports и собирает граф
  2. Для каждого провайдера читает design:paramtypes и ищет провайдер с таким токеном в своём модуле или среди экспортов импортированных
  3. Создаёт экземпляры от листьев к корню: сначала то, у чего нет зависимостей, потом то, что от них зависит

Токен — ключ, по которому контейнер ищет провайдер. Для обычного сервиса токен — сам класс: запись 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() — настроить один раз на всё приложение, обычно в AppModule
  • register() — настроить для конкретного модуля, который вызвал, у каждого свои параметры
  • 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-файлы