architecting-nestjs-modules

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Architecting NestJS Modules

NestJS 模块架构设计

When to use

适用场景

  • Adding a new feature module
  • Splitting a monolithic
    AppModule
  • Fixing tangled imports between modules
  • 添加新功能模块
  • 拆分单体式
    AppModule
  • 修复模块间混乱的导入关系

Core rules

核心规则

  1. Feature modules own their domain, application, infrastructure layers
  2. Providers default to
    Scope.DEFAULT
    (singleton), use
    Scope.REQUEST
    only when needed
  3. Export only what other modules need (don't export everything)
  4. Dynamic modules for configurable features (database, cache)
  5. No cross-feature imports; use shared contracts
  1. 功能模块拥有自身的领域层、应用层与基础设施层
  2. 提供者默认使用
    Scope.DEFAULT
    (单例),仅在必要时使用
    Scope.REQUEST
  3. 仅导出其他模块需要的内容(不要导出所有内容)
  4. 可配置功能(数据库、缓存)使用动态模块
  5. 禁止跨功能模块导入;使用共享契约

Reference shape (TypeScript)

参考结构(TypeScript)

Feature Module

功能模块

typescript
@Module({
  controllers: [UserController],
  providers: [
    CreateUserUseCase,
    { provide: 'UserRepository', useClass: TypeOrmUserRepository },
  ],
  exports: [CreateUserUseCase],
})
export class UserModule {}
typescript
@Module({
  controllers: [UserController],
  providers: [
    CreateUserUseCase,
    { provide: 'UserRepository', useClass: TypeOrmUserRepository },
  ],
  exports: [CreateUserUseCase],
})
export class UserModule {}

Dynamic Module Example

动态模块示例

typescript
@Module({})
export class DatabaseModule {
  static register(config: DatabaseConfig): DynamicModule {
    return {
      module: DatabaseModule,
      providers: [
        { provide: 'DATABASE_CONFIG', useValue: config },
        { provide: DataSource, useFactory: () => new DataSource(config).initialize() },
      ],
      exports: [DataSource],
    };
  }
}
typescript
@Module({})
export class DatabaseModule {
  static register(config: DatabaseConfig): DynamicModule {
    return {
      module: DatabaseModule,
      providers: [
        { provide: 'DATABASE_CONFIG', useValue: config },
        { provide: DataSource, useFactory: () => new DataSource(config).initialize() },
      ],
      exports: [DataSource],
    };
  }
}

Examples — Do

正面示例

typescript
// Clean module boundary
@Module({ controllers: [OrderController], providers: [OrderService], exports: [OrderService] })
export class OrderModule {}
typescript
// Clean module boundary
@Module({ controllers: [OrderController], providers: [OrderService], exports: [OrderService] })
export class OrderModule {}

Examples — Don't

反面示例

typescript
// ❌ Monolithic AppModule
@Module({ controllers: [UserController, OrderController, ProductController], providers: [...] })
export class AppModule {}
typescript
// ❌ Monolithic AppModule
@Module({ controllers: [UserController, OrderController, ProductController], providers: [...] })
export class AppModule {}

Checklist

检查清单

  • Feature modules with own layers
  • Providers with appropriate scopes
  • Only necessary exports
  • No cross-feature imports
See reference/module-patterns.md for full patterns.
  • 功能模块具备独立层级
  • 提供者使用了合适的作用域
  • 仅导出必要内容
  • 无跨功能模块导入
完整模式请参见 reference/module-patterns.md。