模块化设计基础：@Module 装饰器详解、模块的导入与导出、全局模块与动态模块

NestJS 的模块化体系是整个框架的骨架。每个 NestJS 应用至少有一个根模块（AppModule），而复杂业务则通过拆分为多个功能模块来组织。理解 @Module() 装饰器及其导入/导出机制，是构建可维护、可测试后端服务的第一步。

1. @Module 装饰器核心结构

@Module() 装饰器接收一个元数据对象，用于声明模块的组成元素。下表列出了其四个核心属性：

以下是一个标准功能模块的代码示例：

// user.module.ts
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. 模块的导入与导出机制

模块间的依赖关系通过 imports 和 exports 建立。下图展示了三个模块之间的典型交互流程：

3. 全局模块

当一个 provider（如日志服务、配置服务）被大量模块需要时，在每个模块的 imports 中重复导入会显得冗余。NestJS 提供了 @Global() 装饰器，使模块内的 providers 自动全局可用。

// logger.module.ts
import { Global, Module } from '@nestjs/common';
import { LoggerService } from './logger.service';

@Global()
@Module({
  providers: [LoggerService],
  exports: [LoggerService],
})
export class LoggerModule {}

一旦 LoggerModule 被根模块导入，LoggerService 就会自动注入到任何模块的 provider 中，无需再显式导入 LoggerModule。

4. 动态模块

动态模块允许在导入时传递配置参数，使模块的行为可定制。这是实现可配置库（如数据库模块、HTTP 模块）的标准方式。

动态模块通常通过一个静态方法（惯例命名为 forRoot 或 register）返回一个 DynamicModule 对象：

// database.module.ts
import { Module, DynamicModule } from '@nestjs/common';
import { DbService } from './db.service';

export interface DatabaseOptions {
  host: string;
  port: number;
  username: string;
  password: string;
}

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

在根模块中导入时传递配置：

// app.module.ts
import { Module } from '@nestjs/common';
import { DatabaseModule } from './database/database.module';

@Module({
  imports: [
    DatabaseModule.forRoot({
      host: 'localhost',
      port: 5432,
      username: 'admin',
      password: 'secret',
    }),
  ],
})
export class AppModule {}

下图对比了静态模块与动态模块的导入方式：

5. 模块设计对比总结