Что такое динамические модули и паттерн forRoot/forFeature?

Question

Accepted Answer

**Динамические модули** — это модули, которые **можно конфигурировать при импорте** — вместо статичного `@Module({...})` они предоставляют статические методы (по соглашению **`forRoot`** и **`forFeature`**), которые возвращают модуль, сконфигурированный с переданными вами аргументами. Именно так конфигурируемые, переиспользуемые модули (конфиг, база данных, JWT) принимают опции.

## Какую проблему они решают

```text
A static module is fixed — but reusable modules (DatabaseModule, ConfigModule,
JwtModule) need to be CONFIGURED per app (connection URL, secret, options).
Dynamic modules let a module accept configuration at import time.
```

## Вы уже их использовали

```ts
@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),               // ← forRoot with options
    TypeOrmModule.forRoot({ type: "postgres", url: ... }),  // ← configured at import
    JwtModule.register({ secret: process.env.SECRET }),      // ← register variant
    TypeOrmModule.forFeature([User, Post]),                  // ← forFeature for specifics
  ],
})
export class AppModule {}
```

Вызовы `.forRoot()`/`.register()`/`.forFeature()`, которые вы видите при импорте модулей, — это методы динамических модулей, принимающие конфигурацию.

## Соглашение forRoot vs forFeature

```text
forRoot()    → configure the module ONCE, globally (the connection, the secret, core setup)
               called in the root/app module a single time
forFeature() → register feature-specific pieces in each feature module that needs them
               (e.g. TypeOrmModule.forFeature([User]) registers entities per module)
```

По соглашению: `forRoot` для глобальной/одноразовой конфигурации; `forFeature` для регистрации на уровне фичи, которую вы вызываете в нескольких модулях.

## Создание собственного динамического модуля

```ts
@Module({})
export class StorageModule {
  static forRoot(options: StorageOptions): DynamicModule {
    return {                                  // returns a configured module
      module: StorageModule,
      providers: [
        { provide: "STORAGE_OPTIONS", useValue: options },   // inject the passed options
        StorageService,
      ],
      exports: [StorageService],
      global: true,                            // optionally make it global
    };
  }
}
// usage: StorageModule.forRoot({ bucket: "my-bucket", region: "us-east-1" })
```

Статический метод возвращает объект `DynamicModule` (модуль + провайдеры + экспорты), связывая переданные опции с провайдерами модуля (часто через injection token).

## Асинхронная конфигурация (forRootAsync)

```ts
// configure using OTHER injected dependencies (e.g. ConfigService) — async/factory
StorageModule.forRootAsync({
  useFactory: (config: ConfigService) => ({ bucket: config.get("BUCKET") }),
  inject: [ConfigService],
});
```

Вариант `forRootAsync` позволяет конфигурации зависеть от других провайдеров (например, `ConfigService`) — это необходимо, когда опции поступают из валидированной конфигурации.

## Почему это важно

Динамические модули и паттерн `forRoot`/`forFeature` — это важная концепция NestJS для создания **конфигурируемых, переиспользуемых модулей** — и их понимание ценно как для *использования* экосистемы, так и для *создания* общих модулей.

Почти каждый крупный модуль NestJS (ConfigModule, TypeOrmModule, JwtModule, BullModule, CacheModule) — это динамический модуль, конфигурируемый через `.forRoot()`/`.register()`/`.forFeature()`, поэтому понимание, что эти вызовы делают (передача конфигурации модулю при импорте, а не статичный импорт), демистифицирует, как работает вся экосистема.

Соглашение **forRoot vs forFeature** (forRoot для одноразовой глобальной настройки вроде подключения к базе данных или секрета; forFeature для регистрации на уровне фичи вроде регистрации сущностей в каждом модуле) — это паттерн, с которым вы сталкиваетесь постоянно.

Для senior разработчиков умение **создавать собственные динамические модули** (возвращение `DynamicModule` с провайдерами, сконфигурированными из переданных опций, часто через injection tokens, с асинхронными вариантами для конфиг-зависимой настройки) — это то, что позволяет вам создавать переиспользуемые, конфигурируемые модули — общую инфраструктуру (хранилище, клиенты внешних API, кастомная конфигурация), которую другие части приложения или других проектов импортируют со своими настройками.

Это более продвинутая тема, но она фундаментальна для глубокого понимания модульной архитектуры NestJS и для создания профессиональных, переиспользуемых библиотек модулей, делая её важным навыком для проектирования крупных, хорошо структурированных NestJS систем.