NestJS 的依赖注入系统：IoC 容器在 Node.js 后端的实践

为什么 Node 后端会需要 IoC 容器

很多从 Express 转过来的 Node.js 开发者，第一次看到 NestJS 构造函数时都会发愣：明明没有在调用处传入任何参数，类实例为什么能拿到一个完整可用的 service？

这并不是什么魔法。NestJS 在启动阶段就构建了一个 IoC 容器（Inversion of Control Container），由它来负责创建和组装实例。依赖注入（DI）则是容器对外提供的一种能力：你声明需要什么，容器就按规则创建什么，并且在你完全不感知的情况下把依赖送进构造函数。

Express 生态里我们习惯直接 import 一个模块，然后自己 new 对象。这种模式在项目规模增大后会产生两个痛点：一是组件之间的依赖关系散落在各个文件中，改一个依赖就要改所有引入处；二是写测试时很难替换真实实现，因为 import 是静态的。

举个常见的例子：

import { RedisClient } from './redis.client';
export class AuthService {
  private redis = new RedisClient();
  
  async saveToken(token: string) {
    await this.redis.set(token, 'valid');
  }
}

这段代码在功能上没有问题。但等到你写单元测试时，会发现 AuthService 内部直接 new 了一个 RedisClient，你几乎没法在不更改生产代码的情况下把它替换成内存 mock。这时你才会意识到，把依赖创建的控制权从调用方手里拿出来，交给一个容器，是一种更可维护的设计。

NestJS 的 IoC 容器到底做了什么

NestJS 的 IoC 容器核心机制并不复杂：先收集模块里声明的 provider，再根据构造函数上的类型元数据去匹配 provider，最后按依赖关系创建实例并保存到容器。

这背后依赖 TypeScript 的装饰器与 emitDecoratorMetadata。当你给类标注 @Injectable() 后，编译器会把构造函数参数的类型信息写到元数据里，NestJS 运行时再读取这些元数据，决定注入什么。

简单来说，下面这段代码：

@Injectable()
export class UserService {
  constructor(
    private readonly db: DatabaseService,
    private readonly cache: CacheService,
  ) {}
}

在启动时，Nest 会读取到 UserService 构造函数第一个参数的类型是 DatabaseService，第二个是 CacheService。只要这两个 provider 在当前模块或者导入的模块里注册过，容器就能正确创建并注入。

Provider 的注册方式不止一种

绝大多数时候，我们只是用 @Injectable() 的 class 作为 provider。但在真实项目里，会遇到数据库连接、配置对象、第三方 SDK 这类无法简单归为一个类的依赖。此时就需要使用 token 和自定义 provider。

以下面这段代码为例，它用 useFactory 创建了一个异步的数据库连接池：

@Module({
  providers: [
    {
      provide: 'DATABASE_POOL',
      useFactory: async (config: ConfigService) => {
        const pool = createPool(config.get('db'));
        await pool.connect();
        return pool;
      },
      inject: [ConfigService],
    },
  ],
})
export class DatabaseModule {}

这里的 provide 字段定义注入时的 token，useFactory 则是创建 provider 的方式。ConfigService 会先被容器创建，然后作为参数传给这个工厂函数。如果工厂方法里需要读取环境变量，这就显得尤其有用。

自定义 provider 的常见形态有四种：

• useClass：把 token 绑定到某个 class，实现策略替换。
• useValue：直接注入一个固定值，适合配置对象和测试 mock。
• useFactory：动态创建依赖，适合需要内部逻辑或异步初始化的场景。
• useExisting：让多个 token 指向同一个 provider。

你可能已经注意到，每次都需要用字符串 token 时，类型安全会变差。NestJS 文档也建议尽量用 class 作为 token，因为它既是类型信息又是唯一 key。字符串 token 只在跨语言边界时才值得使用。

模块边界决定依赖可见性

NestJS 的 DI 并不是一个全局泛化的容器。每个模块有自己的 provider 集合，模块之间通过 imports 显式声明依赖，通过 exports 暴露 provider。这种封装性很容易被开发者忽略，最后出现“为什么我 imports 了某个模块，还是不能注入它的 service”这样的问题。

答案通常很简单：那个模块没有导出对应的 provider。比如 DatabaseModule 内部提供了 DATABASE_POOL，但没写在 exports 里，外部模块就看不到它。

一个更典型的场景是，多人协作时习惯把工具类直接注册成全局 provider。刚开始确实方便，但时间一长，你会发现模块边界形同虚设，代码里到处是隐式依赖。养成明确 exports 的习惯，比依赖 @Global() 要健康得多。

作用域：单例不是唯一答案

NestJS 的 provider 默认是 singleton，即容器启动后创建一次，整个应用复用。这很适合无状态 service 和连接池。但遇到多租户系统、请求级上下文时，单例就挡不住了。

你可以设置作用域：

@Injectable({ scope: Scope.REQUEST })
export class AuditService {
  constructor(@Inject(REQUEST) private request: Request) {}
}

REQUEST 作用域意味着每个请求都会创建一个新的实例，可以安全地获取当前请求上下文。副作用是创建开销明显上升，同时无法直接依赖非 request 作用域的 provider。TRANSIENT 作用域则更自由，每次注入都会新创建实例，适合有状态且不希望共享的服务。

需要提醒的是，作用域选择的代价是真实的。默认单例是性能最好的选择；request 作用域会显著影响吞吐量。如果一个 service 只是为了读一个 header 才用 request 作用域，更合理的做法是显式传递上下文对象，而不是让整个依赖链都跟着变成 request。

依赖注入中的几个典型误区

依赖注入本身不难，难的是在工程里用好它。下面这几个坎，很多团队都踩过。

• 把所有依赖都当成构造函数参数，忽略了模块导出和 provider 注册。结果是依赖声明了但容器找不到，报错时只能一层层翻模块。
• 为了图方便，大量使用字符串 token。一旦拼写错误，只有运行到注入时才会暴露，无法静态检查。
• 出现循环依赖时，第一反应是扔一个 forwardRef 进去。这样做往往掩盖了模块划分不对的事实，长期来看会形成一团互相缠绕的依赖。
• 滥用 request 作用域，只为了拿请求对象，却连累一大片 service 失去缓存和复用优势。

循环依赖尤其值得多说一句。NestJS 提供了 forwardRef 来解决两个类互相引用的问题，但你应该把 forwardRef 当作最后手段，而不是常规方案。多数循环依赖都可以通过拆分模块或者提取公共边界来消除。比如 UserService 和 AuthService 互相依赖，通常是你把一个业务逻辑放错了位置。

NestJS DI 与其他方案有什么不同

Node.js 生态里并非只有 NestJS 提供了依赖注入。很多项目会使用轻量 DI 库，或者干脆手动管理。不同方案之间的选择，其实映射的是团队对项目结构的要求。

如果你已经选择了 NestJS，那么内置 DI 无疑是最自然的选择，因为你不需要额外引入一套生命周期机制。轻量 DI 库更适合那些不想用框架、但仍希望获得依赖注入灵活性的项目。手动管理在小规模服务里足够直接，但随着业务增长，文件间互相 new 的问题会很快显现出来。

在项目里落地 DI 的几个建议

依赖注入的价值不是在写代码时体现的，而是在后续维护和测试中体现。想让这套机制真正发挥作用，可以从这几件事入手。

首先，把 provider 的注册权交给模块。数据库连接、缓存客户端这类资源，在 CoreModule 或者某个 DomainModule 中集中提供，并用 exports 暴露需要给外部使用的部分。避免把连接逻辑散落在各个 service 中。

其次，默认选择 class token。它同时提供类型和唯一标识，不会因为字符串拼写错误而埋雷。只有遇到无法表示为 class 的场景时，才考虑字符串或 Symbol。

再次，测试时利用 useValue 替换实现。依赖注入最大的好处之一就是测试替身很容易做。假设你想用内存数据库替代真实连接，只需要在测试模块里这样写：

@Module({
  providers: [
    {
      provide: 'DATABASE_POOL',
      useValue: createMemoryPool(),
    },
  ],
})
export class TestDatabaseModule {}

这样 UserService 里对 DATABASE_POOL 的注入就会自动拿到内存池，不需要改任何业务代码。

还有一个容易被忽视的细节：合理使用 @Optional()。当某些依赖是可选的，比如外部监控客户端在本地环境没有配置，用 @Optional() 能让注入在缺失时返回 undefined，而不是直接让应用崩溃。不过也要注意，太容易得到可选依赖反而会降低代码的显式性，使用前先想想是不是真的可缺失。

依赖注入不是银弹。它把对象创建行为集中到容器里，随之换来的代价是控制流变得更不直观。当你遇到问题时，优先检查模块边界，而不是急着调整代码结构。

另外，不要在一开始就引入复杂的设计。NestJS 的 DI 在简单场景下同样很轻，你完全可以只是用 @Injectable() 和默认单例。等业务真正需要动态配置或请求级独立状态时，再启用 useFactory 和 request 作用域，这样成本才可控。

最后

NestJS 是少数把完整 IoC 容器带进了 Node.js 世界的后端框架。它对 DI 的坚持，让大规模 TypeScript 项目有机会突破 Express 那种“自己拼装一切”的开发模式，获得更清晰的模块边界和可测试性。

但容器本身不会替你设计架构。真正决定代码质量的，是你如何划分模块、如何暴露依赖，以及如何在需要时做出恰当的取舍。理解了 NestJS 的依赖注入系统，你就能在使用它时更主动，而不是在报错后才发现设计上出了问题。