模块化架构设计：@Module 装饰器详解

NestJS 的模块化架构是整个框架的基石。通过 @Module() 装饰器，你可以将应用程序拆分为高内聚、低耦合的功能单元。本章将深入解析模块的声明、导入导出、全局作用域以及动态模块的构建方式，帮助你掌握模块化设计的核心原则。

1. @Module 装饰器核心结构

@Module() 装饰器接收一个配置对象，该对象定义了模块的四个核心元数据属性：

import { Module } from '@nestjs/common';
import { UserController } from './user.controller';
import { UserService } from './user.service';
import { DatabaseModule } from '../database/database.module';

@Module({
  imports: [DatabaseModule],
  controllers: [UserController],
  providers: [UserService],
  exports: [UserService],
})
export class UserModule {}

2. 模块的导入与导出机制

模块的导入导出构成了 NestJS 的依赖图。理解这一机制是构建大型应用的基础。

• 直接导入：在 imports 数组中直接引入模块类，即可使用该模块导出的所有 providers。
• 全局模块：使用 @Global() 装饰器标记的模块，其导出的 providers 会自动注册到全局作用域，无需在 imports 中重复导入。
• 循环依赖：当两个模块互相导入时，需要使用 forwardRef(() => Module) 解决循环引用问题。

// 显式导入示例
@Module({
  imports: [forwardRef(() => BModule)], // 解决循环依赖
  providers: [AService],
  exports: [AService],
})
export class AModule {}

3. 全局模块与动态模块

全局模块和动态模块是 NestJS 模块化体系中的高级特性，分别解决跨模块共享和运行时配置的问题。

3.1 全局模块

使用 @Global() 装饰器将模块标记为全局。全局模块的 exports 会自动注入到所有模块中，无需在 imports 中显式声明。

import { Global, Module } from '@nestjs/common';
import { ConfigService } from './config.service';

@Global()
@Module({
  providers: [ConfigService],
  exports: [ConfigService],
})
export class ConfigModule {}

3.2 动态模块

动态模块允许你在导入时传递配置参数，从而创建不同行为的模块实例。这是实现可配置插件系统的关键模式。

import { Module, DynamicModule } from '@nestjs/common';
import { DatabaseService } from './database.service';

@Module({})
export class DatabaseModule {
  static forRoot(options: DatabaseOptions): DynamicModule {
    return {
      module: DatabaseModule,
      providers: [
        {
          provide: 'DATABASE_OPTIONS',
          useValue: options,
        },
        DatabaseService,
      ],
      exports: [DatabaseService],
    };
  }
}

// 使用动态模块
@Module({
  imports: [DatabaseModule.forRoot({ host: 'localhost', port: 5432 })],
})
export class AppModule {}

4. 模块作用域与生命周期

NestJS 模块遵循单例模式，但通过作用域和生命周期钩子，你可以精细控制 providers 的创建和销毁时机。

import { Injectable, Scope } from '@nestjs/common';

@Injectable({ scope: Scope.REQUEST })
export class RequestContextService {
  private requestId: string;

  setRequestId(id: string) {
    this.requestId = id;
  }

  getRequestId(): string {
    return this.requestId;
  }
}

5. 模块生命周期钩子

模块本身也支持生命周期钩子，允许你在模块初始化或销毁时执行自定义逻辑。

• OnModuleInit：模块依赖注入完成后执行，适合初始化连接、加载配置。
• OnApplicationBootstrap：所有模块初始化完成后执行，适合启动后台任务。
• OnModuleDestroy：模块销毁前执行，适合关闭连接、清理资源。
• BeforeApplicationShutdown：应用关闭前执行，接收关闭信号。

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

@Module({
  providers: [Logger],
})
export class AppModule implements OnModuleInit {
  constructor(private readonly logger: Logger) {}

  onModuleInit() {
    this.logger.log('AppModule 初始化完成，所有依赖已就绪');
    // 执行初始化逻辑，如连接数据库、加载缓存
  }
}

6. 模块化架构设计模式

以下 SVG 图展示了 NestJS 模块化架构的核心设计模式，包括模块的导入导出关系、全局模块的作用范围以及动态模块的配置传递流程。

7. 模块化架构性能优化要点

合理的模块化设计不仅提升代码可维护性，还能带来显著的性能收益：

• 按需加载：使用动态模块和 forFeature 模式，只在需要时加载特定功能模块，减少启动时间。
• 作用域控制：将无状态服务保持为默认单例作用域，避免不必要的实例创建开销。
• 全局模块最小化：全局模块的 providers 会在所有模块中注入，增加依赖解析的复杂度。仅将真正需要全局共享的服务（如日志、配置）设为全局。
• 循环依赖规避：循环依赖会导致模块初始化顺序问题，增加启动延迟。通过引入中间模块或重构接口来消除循环依赖。

8. 模块作用域与生命周期实战

以下 SVG 图展示了模块及其 providers 的生命周期流程，从模块初始化到请求处理再到销毁的完整链路。

9. 模块化设计常见陷阱与避坑指南

10. 总结

模块化架构是 NestJS 应用设计的核心。通过 @Module() 装饰器，你可以精确控制依赖的可见性和生命周期。记住以下关键点：

• 使用 imports 和 exports 构建清晰的模块依赖图
• 全局模块仅用于基础设施，避免业务逻辑全局化
• 动态模块通过静态方法实现运行时配置，提升灵活性
• 合理选择作用域类型，平衡性能与功能需求
• 利用生命周期钩子管理初始化和销毁逻辑

掌握这些模块化设计原则，你将能够构建出可维护、可测试、高性能的 NestJS 应用。