Динамические модули и асинхронная конфигурация

Фиксированный набор против рантайм-дескриптора

У статического @Module({ providers, exports }) набор провайдеров фиксирован, решён в момент определения класса. Он не может принять конфигурацию — imports: [CacheModule] даёт тебе то, что CacheModule решил за себя сам.

Динамический модуль — это класс со static-методом, который возвращает дескриптор DynamicModule в рантайме: { module, providers, imports?, exports?, global? }. Импортёр вызывает этот метод и передаёт конфиг, а Nest вклеивает возвращённые провайдеры в граф. Именно так работают ConfigModule.forRoot({ ... }), JwtModule.register({ ... }) и TypeOrmModule.forFeature([ ... ]) — каждый вызов есть вызов метода, собирающий заточенный модуль прямо на месте.

import { DynamicModule, Module } from '@nestjs/common';

export const STORAGE_OPTIONS = 'STORAGE_OPTIONS';
export interface StorageOptions { bucket: string; region: string; }

@Module({})
export class StorageModule {
  // hand-rolled dynamic module: the importer passes config, we turn it into a provider
  static forRoot(options: StorageOptions): DynamicModule {
    return {
      module: StorageModule,
      providers: [{ provide: STORAGE_OPTIONS, useValue: options }],
      exports: [STORAGE_OPTIONS], // so consumers can inject the options token
      global: true,               // exports visible app-wide without re-importing
    };
  }
}

StorageModule.forRoot({ bucket: 'uploads', region: 'eu-central-1' }) возвращает полностью сформированный модуль, единственный провайдер которого — объект опций, экспортированный под токеном, который инжектят нижестоящие сервисы. Оболочка @Module({}) пуста намеренно — настоящий конструктор тут метод.

Конвенция имён: forRoot, forFeature, register

Три имени метода — это конвенция, не навязанная Nest, — но каждый Nest-разработчик читает их как контракт, так что нарушение её есть выстрел себе в ногу.

• forRoot() — настроить один раз, в корне приложения. Обычно возвращает общую инфраструктуру (соединение, хранилище конфига) и часто global. Вызов более одного раза — это и есть баг из хука.
• forFeature() — зарегистрировать срез, многократно, на фиче-модуль. TypeOrmModule.forFeature([User]) в одном модуле, forFeature([Order]) в другом — каждый вызов скоупит репозитории в этот модуль, не пересоздавая соединение, которое уже сделал forRoot.
• register() — конфигурация на импорт, без root/global-семантики. Каждый HttpModule.register({ baseURL }) независим; два импорта означают два отдельно сконфигурированных инстанса, и это задумано.

// forRoot ONCE, at the root — stands up the shared connection (global)
imports: [DatabaseModule.forRoot({ url: process.env.DB_URL, poolSize: 10 })]

// forFeature PER module — scopes entities/repos, reuses the forRoot connection
imports: [DatabaseModule.forFeature([User])]   // in UsersModule
imports: [DatabaseModule.forFeature([Order])]  // in OrdersModule

// register PER import — each gets its own independent config, no sharing implied
imports: [HttpModule.register({ baseURL: 'https://api.billing.internal' })]

Вместе три имени кодируют намерение по шарингу: forRoot — «один общий пул на всё приложение», forFeature — «срез этого пула, на модуль», register — «независимый инстанс, без шаринга». Когда видишь, что коллега вызывает forRoot в фиче-модуле, — это инцидент в 2 ночи, ждущий своего часа: само имя несёт контракт.

Асинхронный конфиг: forRootAsync и провайдер-фабрика

Самописный forRoot выше принимает литеральный объект опций. Но настоящий конфиг — URL базы, JWT-секрет — лежит в env и читается через ConfigService. Ты не можешь передать литерал в момент импорта; тебе нужно значение, разрезолвленное из другого провайдера. Это forRootAsync:

import { JwtModule } from '@nestjs/jwt';
import { ConfigModule, ConfigService } from '@nestjs/config';

JwtModule.registerAsync({
  imports: [ConfigModule],            // make ConfigService resolvable IN this context
  inject: [ConfigService],            // the factory's dependencies, in order
  useFactory: (cfg: ConfigService) => ({
    secret: cfg.getOrThrow('JWT_SECRET'),
    signOptions: { expiresIn: cfg.get('JWT_TTL') ?? '15m' },
  }),
});

Три части работают вместе. useFactory сам является провайдером — функцией, которую Nest вызывает, чтобы произвести опции. inject перечисляет зависимости этой функции, позиционно, чтобы Nest знал, что нужно разрезолвить ConfigService и передать его первым аргументом. imports делает эти зависимости резолвимыми внутри собственного контекста инъекции динамического модуля — у динамического модуля свой скоуп, так что, если ConfigModule не глобальный, фабрика не увидит ConfigService без импорта его здесь.

Забудь imports: [ConfigModule] (а ConfigModule не глобальный) — и получишь падение на старте, а не в рантайме: Nest can't resolve dependencies of the <factory> (?). Please make sure that the argument ConfigService at index [0] is available in the <module> context. (?) — это неразрезолвленный ConfigService: фабрика объявила его через inject, но ничего в скоупе его не провайдит.

ConfigurableModuleBuilder: хватит писать руками

Писать forRoot и forRootAsync руками — литеральный путь, путь через фабрику, async-варианты useExisting/useClass, токен опций — это ~40 строк бойлерплейта на модуль, повторяемых идентично в каждом конфигурируемом модуле, которым ты владеешь. ConfigurableModuleBuilder генерирует всё это:

import { ConfigurableModuleBuilder } from '@nestjs/common';
import { StorageOptions } from './storage-options.interface';

// generates the class + token + sync AND async entry points for you
export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
  new ConfigurableModuleBuilder<StorageOptions>().build();

import { Module } from '@nestjs/common';
import { ConfigurableModuleClass } from './storage.module-definition';

@Module({ providers: [StorageService], exports: [StorageService] })
export class StorageModule extends ConfigurableModuleClass {}
// now StorageModule.register({...}) AND StorageModule.registerAsync({ useFactory, inject, imports })
// both exist, and StorageService can inject MODULE_OPTIONS_TOKEN

Билдер отдаёт обратно ConfigurableModuleClass (наследуешь его) и MODULE_OPTIONS_TOKEN (инжектишь, чтобы прочитать опции). Ты получаешь и register, и registerAsync бесплатно, с уже разведённой async-обвязкой imports/inject/useFactory. Хочешь именование forRoot вместо register? .setClassMethodName('forRoot'). Хочешь глобальный? .setExtras({ isGlobal: true }, ...). Те ~40 строк на модуль схлопываются до двух.