一文吃透 Nestjs 动态模块之 register、forRoot、forFeature

读完此文，你能更准确的理解动态模块以及清楚register、forRoot、forFeature三者作用，何时使用它们

什么是动态模块

在 Nest 里，普通（静态）模块可以理解为"写死的一份模块定义"，你只能在 imports: [] 里直接引入模块类；而动态模块 允许你在"导入模块时传参"，由模块的静态方法（如 register / forRoot / forFeature）返回一个 DynamicModule 对象 ，Nest 会把这个对象当成模块元数据来编译，从而按你的参数动态生成 providers / exports / imports 等配置。

一句话总结：动态模块 = 可传参的模块工厂，返回 DynamicModule 来决定模块最终提供什么能力。

动态模块作用

动态模块的核心价值是：把"可配置性"变成模块 API 的一部分 。也就是说，你不再只能 imports: [SomeModule] 这样"死引入"，而是可以通过 SomeModule.forRoot(...) / forFeature(...) / register(...) 传入参数，让模块在"被导入时"就完成：

根据不同环境/业务场景生成不同的 Provider（例如不同的连接串、不同的开关、不同的策略实现）
导出一组"已经配置好"的能力（让使用方只管注入，不用关心怎么组装）
把模块的配置约束收口到一个入口 （避免到处散落 process.env 或重复 new 客户端）

从官方定义看，动态模块本质上就是：一个模块提供一个静态方法，返回 DynamicModule 对象（包含 module / imports / providers / exports / global 等元数据），Nest 会把它当成"模块定义"来编译。

你可以把动态模块理解为："返回模块定义的工厂函数"，只不过它被约定写成模块类上的静态方法。

什么时候适合用动态模块

动态模块并不是"写 Nest 就必须用"的东西，通常在下面这些场景才值得上：

需要配置且配置会变：例如 JWT、缓存、HTTP 客户端、消息队列、数据库连接等。
需要多实例：同一种能力要按不同名字/用途创建多个实例（例如两个 Redis、两个第三方 API client）。
需要隐藏复杂装配 ：使用方只想 imports: [...]，不想了解内部 provider 如何拼装、如何选择实现。
希望统一约束与默认值：集中处理 option 校验、默认值合并、token 命名、导出策略等。

不适合的情况：

没有任何配置差异，普通静态模块就够了。
配置只在单个业务模块里用且很简单，直接在该模块里写 providers 可能更清晰。

register、forRoot、forFeature：它们是什么关系

先说结论：它们不是语法关键字，只是 Nest 生态里长期形成的命名约定，目的是让人一眼看懂"这个动态模块方法在语义上做什么"。

register(...) ：更通用的命名，表示"注册/配置一次模块"。常见于需要传入 options 的模块（例如 ClientsModule.register(...)、JwtModule.register(...)、MulterModule.register(...)）。
forRoot(...) ：强调"根级别（应用级/全局级）配置"，通常只需要做一次，影响整个应用的默认行为或单例资源（例如 ConfigModule.forRoot(...)、TypeOrmModule.forRoot(...)）。
forFeature(...) ：强调"按功能域（feature）扩展/注册一小部分能力"，往往会被多次调用，每个业务模块各取所需（例如 TypeOrmModule.forFeature([Entity...])、MongooseModule.forFeature([{ name, schema }...])）。

一个很好理解的类比是：

forRoot：建"基础设施"（连接、全局配置、默认客户端）
forFeature：在某个业务域里"挂载资源"（实体仓库、某些模型、某些订阅）
register：没有明确 root/feature 分层时的"通用注册入口"

使用方法（从 DynamicModule 结构看懂一切）

动态模块方法最终都要返回一个 DynamicModule 对象（官方文档的核心点之一）。你需要理解这些字段各自解决什么问题：

module：必须指向当前模块类本身（Nest 用它做标识与元数据合并）。
imports ：该动态模块额外依赖的模块（例如需要先导入 ConfigModule 才能注入 ConfigService）。
providers：根据 options 生成/选择出来的 provider（通常包含 options provider、核心服务、工厂 provider 等）。
exports：允许外部模块使用的 provider（不导出就无法在外部注入）。
global （可选）：设为 true 后，该模块导出的 provider 在整个应用可见（减少重复 imports，但要谨慎使用）。

下面用"伪代码"把三类方法串起来看。

`register(...)`：通用注册入口

概念

register 通常用于：模块需要 options 才能工作，并且这个模块既可能全局用一次，也可能按需在少数地方导入，但作者不想强行区分 root/feature。

作用

把调用方传入的 options 固化为一个可注入的 provider（常用做法是 useValue）
用这些 options 组装出真正的客户端/服务 provider（常用做法是 useFactory）
决定导出哪些 token 给外部模块使用

伪代码示例

ts 复制代码

// 伪代码：不依赖具体业务库，展示结构与思路
type FooModuleOptions = { baseUrl: string; timeoutMs?: number };

const FOO_OPTIONS = Symbol('FOO_OPTIONS');
const FOO_CLIENT = Symbol('FOO_CLIENT');

@Module({})
export class FooModule {
  static register(options: FooModuleOptions): DynamicModule {
    const optionsProvider = {
      provide: FOO_OPTIONS,
      useValue: { timeoutMs: 3000, ...options },
    };

    const clientProvider = {
      provide: FOO_CLIENT,
      useFactory: (opts: FooModuleOptions) => {
        // 这里可以 new 一个 HTTP client / SDK client
        return createFooClient(opts.baseUrl, opts.timeoutMs);
      },
      inject: [FOO_OPTIONS],
    };

    return {
      module: FooModule,
      providers: [optionsProvider, clientProvider],
      exports: [clientProvider],
    };
  }
}

何时使用

你在写一个可复用模块：需要 options，但不想强制区分"全局/feature"两套 API。
你希望调用方语义简单：FooModule.register({ ... }) 一眼看懂"我在配置这个模块"。

`forRoot(...)`：应用级（根级别）初始化

概念

forRoot 的关键词是"根"。它通常承担两类职责：

初始化一次：创建单例连接/单例客户端/全局默认配置。
定义默认行为：例如全局中间件、全局拦截器/管道依赖的配置，或某个模块的"默认实例"。

在 Nest 的常见用法里：你会在 AppModule（或根模块）里调用 forRoot，其他业务模块不再重复调用，而是通过注入来使用它导出的 provider。

作用

建立"全局共享的底座"：连接池、客户端单例、全局配置 provider 等。
明确生命周期：避免每个 feature 模块都 new 一个连接或重复注册同一份全局配置。

伪代码示例

ts 复制代码

type FooRootOptions = { url: string };
const FOO_CONNECTION = Symbol('FOO_CONNECTION');

@Module({})
export class FooModule {
  static forRoot(options: FooRootOptions): DynamicModule {
    const connectionProvider = {
      provide: FOO_CONNECTION,
      useFactory: async () => {
        // 连接通常是 async 初始化
        return await connectFoo(options.url);
      },
    };

    return {
      module: FooModule,
      providers: [connectionProvider],
      exports: [connectionProvider],
      // 可选：如果你希望全局可见（谨慎）
      // global: true,
    };
  }
}

// AppModule 里只做一次 root 初始化
@Module({
  imports: [FooModule.forRoot({ url: '...' })],
})
export class AppModule {}

何时适合用 `forRoot`

需要"只初始化一次"的资源：数据库连接、MQ 连接、缓存连接、全局配置加载等。
你希望模块 API 语义明确：forRoot 让读代码的人直接知道"这是应用级初始化"。

`forFeature(...)`：按业务域挂载/扩展能力

概念

forFeature 的关键词是"feature"。它解决的问题通常是：某个模块已经通过 forRoot 建好了底座，但不同业务模块只需要其中一部分资源，或者需要在该模块下再注册一批与业务相关的 provider。

经典例子（官方生态里最常见的理解方式）：

ORM/ODM 模块在 root 初始化连接后，feature 模块再声明"我需要这些实体/模型"，框架据此生成仓库/模型 provider 并导出给当前业务模块使用。

作用

把"业务域的声明"放在业务模块里：可读性强、边界清晰。
支持多次调用：每个业务模块可以传不同的 feature 元数据。
避免全量导出：只为当前 feature 生成它需要的 providers。

伪代码示例

ts 复制代码

type FooFeature = { name: string };
const fooFeatureToken = (name: string) => `FOO_FEATURE_${name}`;

@Module({})
export class FooModule {
  static forRoot(options: { url: string }): DynamicModule {
    // 省略：创建连接并导出
    return { module: FooModule, providers: [...], exports: [...] };
  }

  static forFeature(features: FooFeature[]): DynamicModule {
    const featureProviders = features.map((f) => ({
      provide: fooFeatureToken(f.name),
      useFactory: (conn: unknown) => {
        // conn 来自 forRoot 导出的连接 token
        return connCreateFeatureHandle(conn, f.name);
      },
      inject: [/* FOO_CONNECTION */],
    }));

    return {
      module: FooModule,
      providers: featureProviders,
      exports: featureProviders,
    };
  }
}

// 某个业务模块按需声明它要哪些 feature
@Module({
  imports: [FooModule.forFeature([{ name: 'User' }, { name: 'Order' }])],
})
export class UserDomainModule {}

何时适合用 `forFeature`

你已经有一个"root 级底座"，但需要在不同业务模块里分别声明不同资源集合。
你希望业务模块的依赖可读：打开模块文件就能看到它依赖了哪些实体/模型/功能片段。

三者在真实项目里的组合方式（推荐理解）

常见的组合模式是：

基础设施模块 ：XxxModule.forRoot(...)（只在根模块调用一次）
业务域模块 ：XxxModule.forFeature(...)（每个业务域各自声明所需）
不分层或轻量模块 ：XxxModule.register(...)（直接配置即可用）

如果你在某个三方库里同时看到 register 和 forRoot/forFeature：

通常意味着作者提供了多种入口，方便不同使用习惯；
但底层本质仍然是返回 DynamicModule，差异更多在"语义分层"和"推荐调用位置"。

注意事项（容易踩坑但官方语义允许你避免）

不要把 forRoot 到处调用：如果它创建的是连接/单例资源，多次调用往往意味着多份实例（开销大、难排查）。更稳妥的模式是 root 初始化一次，feature 按需挂载。
导出策略要克制 ：exports 只导出真正需要给外部用的 provider。导出太多会让依赖边界变模糊，也会增加误用概率。
token 设计要稳定 ：options provider、客户端 provider、feature provider 的 token 一旦对外暴露，后续变更会影响大量模块。推荐用常量/Symbol/统一工厂函数生成 token，避免字符串散落。
global: true 谨慎使用 ：全局模块能减少 imports，但也会让依赖变"隐式"。团队协作里，显式 imports 往往更可维护。
考虑异步配置 ：如果 options 依赖配置中心/远程拉取/ConfigService，一般会需要 registerAsync / forRootAsync 这一类异步变体（很多官方生态模块也提供同名 Async 方法）。

小结

动态模块的本质是：用一个静态方法返回 DynamicModule，把"模块如何被配置、生成哪些 provider、导出哪些能力"收敛为一个清晰入口 。register / forRoot / forFeature 是社区约定的命名语义：

forRoot：做应用级初始化（通常一次），建立底座与默认能力
forFeature：按业务域扩展/声明所需资源（可多次），只生成当前 feature 需要的 providers
register：通用注册入口（语义不分层），把 options 转成可注入能力即可用

掌握这三者，你读三方模块源码时会更快看懂"哪里初始化一次、哪里按需扩展、哪些 provider 会被导出"，写自己的可复用模块时也能把配置与依赖边界做得更清楚。

一文吃透 Nestjs 动态模块之 register、forRoot、forFeature

什么是动态模块

动态模块作用

什么时候适合用动态模块

register、forRoot、forFeature：它们是什么关系

使用方法（从 DynamicModule 结构看懂一切）

register(...)：通用注册入口

概念

作用

伪代码示例

何时使用

forRoot(...)：应用级（根级别）初始化

概念

作用

伪代码示例

何时适合用 forRoot

forFeature(...)：按业务域挂载/扩展能力

概念

作用

伪代码示例

何时适合用 forFeature

三者在真实项目里的组合方式（推荐理解）

注意事项（容易踩坑但官方语义允许你避免）

小结

`register(...)`：通用注册入口

`forRoot(...)`：应用级（根级别）初始化

何时适合用 `forRoot`

`forFeature(...)`：按业务域挂载/扩展能力

何时适合用 `forFeature`