NestJS 11 企业 API 模式

NestJS 11 已成为在 TypeScript 中构建生产级 API 的首选框架，它将 Angular 启发的架构与 Node.js 的原始功能相结合。当您在企业规模上运营时（处理数百万个请求、管理多租户数据并协调数十个模块），您在第一天选择的模式决定了您的代码库是可以正常扩展还是会因自身重量而崩溃。

本指南总结了从使用 310 多个 TypeScript 文件构建 56 个模块的 NestJS 11 后端来之不易的经验教训，涵盖了从模块组织和防护组合到实际在负载下保持的多租户模式的所有内容。

要点

• 使用 forRoutes('*path') 而不是 forRoutes('*') — NestJS 11 更改了通配符路由匹配
• 全局异常过滤器必须在main.ts中注册，而不是通过APP_FILTER注册
• 多租户需要在每个查询层进行 organizationId 过滤，而不仅仅是中间件
• @Public() 装饰器模式比完全禁用开放路线的防护更安全
• 切勿在 Drizzle 查询中使用 sql.raw() — 始终参数化 sql 模板文字
• EmailModule 应为 @Global() 以避免在每个功能模块中重新导入
• 在 NestJS 引导之前，必须在 main.ts 中预加载 Dotenv，以避免 env 解析问题
• 所有公共端点都必须进行速率限制 — 使用 @nestjs/throttler

---

规模项目结构

NestJS 中最重要的架构决策是如何组织模块。在企业规模上，app.module.ts 中的平面模块列表变得难以管理。有效的模式是具有显式依赖声明的域驱动模块分组。

apps/api/src/
  modules/
    auth/
      auth.module.ts
      auth.controller.ts
      auth.service.ts
      guards/
        jwt.guard.ts
        roles.guard.ts
      decorators/
        public.decorator.ts
        roles.decorator.ts
    contacts/
      contacts.module.ts
      contacts.controller.ts
      contacts.service.ts
      contacts.spec.ts
      dto/
        create-contact.dto.ts
        update-contact.dto.ts
    billing/
      billing.module.ts
      billing.service.ts
      webhook.controller.ts
  shared/
    filters/
      global-exception.filter.ts
    interceptors/
      transform.interceptor.ts
    pipes/
      validation.pipe.ts
  health/
    health.controller.ts
    indicators/
  main.ts
  app.module.ts

每个域模块都是独立的。 shared/ 目录包含横切关注点。这种分离使您可以添加新域，而无需触及现有代码。

---

@Public() 装饰器模式

NestJS 11 在全球范围内应用 JWT 防护，但您需要选择打开的端点 - 运行状况检查、身份验证回调、Webhook 接收器。 @Public() 装饰器模式远远优于禁用每条路由的防护。

// decorators/public.decorator.ts
import { SetMetadata } from '@nestjs/common';

export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

// guards/jwt-auth.guard.ts
import { Injectable, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { AuthGuard } from '@nestjs/passport';
import { IS_PUBLIC_KEY } from '../decorators/public.decorator';

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  constructor(private reflector: Reflector) {
    super();
  }

  canActivate(context: ExecutionContext) {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);

    if (isPublic) return true;
    return super.canActivate(context);
  }
}

// app.module.ts
import { APP_GUARD } from '@nestjs/core';

@Module({
  providers: [
    { provide: APP_GUARD, useClass: JwtAuthGuard },
    { provide: APP_GUARD, useClass: RolesGuard },
  ],
})
export class AppModule {}

现在，任何用 @Public() 修饰的控制器方法都完全绕过 JWT 验证。 Webhook 控制器、运行状况端点和身份验证路由都使用此模式。

---

具有 OrganizationId 的多租户

多租户 API 的基本规则：每个数据库查询都必须按 organizationId 进行过滤。设置 req.organizationId 的中间件是不够的 - 开发人员忘记应用过滤器会暴露跨租户数据。

该模式是从 JWT 有效负载中提取 organizationId 并将其附加到类型化请求接口：

// types/authenticated-request.interface.ts
import { Request } from 'express';

export interface AuthenticatedRequest extends Request {
  user: {
    sub: string;
    email: string;
    name: string;
    role: 'admin' | 'support' | 'user';
    organizationId: string;
  };
}

// contacts/contacts.controller.ts
import { Controller, Get, Post, Body, Req } from '@nestjs/common';
import { AuthenticatedRequest } from '../../types/authenticated-request.interface';

@Controller('contacts')
export class ContactsController {
  constructor(private contactsService: ContactsService) {}

  @Get()
  findAll(@Req() req: AuthenticatedRequest) {
    return this.contactsService.findAll(req.user.organizationId);
  }

  @Post()
  create(@Body() dto: CreateContactDto, @Req() req: AuthenticatedRequest) {
    return this.contactsService.create(dto, req.user.organizationId);
  }
}

// contacts/contacts.service.ts
import { db } from '@ecosire/db';
import { contacts } from '@ecosire/db/schema';
import { eq, and } from 'drizzle-orm';

@Injectable()
export class ContactsService {
  async findAll(organizationId: string) {
    return db
      .select()
      .from(contacts)
      .where(eq(contacts.organizationId, organizationId))
      .limit(100);
  }
}

服务层在查询级别强制执行 organizationId。再多的中间件故障或被遗忘的装饰器也不会泄漏跨租户数据，因为 SQL 本身强制执行隔离。

---

全局异常过滤器

所有端点之间一致的错误响应需要全局异常过滤器。 NestJS 11 的 HttpException 层次结构可以处理大多数情况，但您还需要捕获意外错误并且永远不要在生产中暴露堆栈跟踪。

// filters/global-exception.filter.ts
import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  HttpStatus,
  Logger,
} from '@nestjs/common';
import { Request, Response } from 'express';

@Catch()
export class GlobalExceptionFilter implements ExceptionFilter {
  private readonly logger = new Logger(GlobalExceptionFilter.name);

  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();

    let status = HttpStatus.INTERNAL_SERVER_ERROR;
    let message = 'Internal server error';
    let errors: Record<string, string[]> | undefined;

    if (exception instanceof HttpException) {
      status = exception.getStatus();
      const exceptionResponse = exception.getResponse();

      if (typeof exceptionResponse === 'string') {
        message = exceptionResponse;
      } else if (typeof exceptionResponse === 'object') {
        const resp = exceptionResponse as Record<string, unknown>;
        message = (resp.message as string) || message;
        if (Array.isArray(resp.message)) {
          // Validation errors from class-validator
          errors = this.formatValidationErrors(resp.message as string[]);
          message = 'Validation failed';
        }
      }
    } else if (exception instanceof Error) {
      this.logger.error(exception.message, exception.stack);
      // Never expose stack traces in production
      if (process.env.NODE_ENV !== 'production') {
        message = exception.message;
      }
    }

    response.status(status).json({
      statusCode: status,
      message,
      errors,
      path: request.url,
      timestamp: new Date().toISOString(),
    });
  }

  private formatValidationErrors(messages: string[]): Record<string, string[]> {
    const errors: Record<string, string[]> = {};
    for (const msg of messages) {
      const [field, ...rest] = msg.split(' ');
      if (!errors[field]) errors[field] = [];
      errors[field].push(rest.join(' '));
    }
    return errors;
  }
}

将其注册到 main.ts 中：

// main.ts
import { NestFactory } from '@nestjs/core';
import { GlobalExceptionFilter } from './shared/filters/global-exception.filter';

async function bootstrap() {
  // CRITICAL: Load env vars before NestJS bootstraps
  require('dotenv').config({ path: join(__dirname, '..', '..', '..', '.env.local') });

  const app = await NestFactory.create(AppModule);
  app.useGlobalFilters(new GlobalExceptionFilter());
  app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
  await app.listen(3001);
}

---

NestJS 11 路由通配符更改

NestJS 11 中最具突破性的变化之一是通配符路由匹配。如果您从 NestJS 10 迁移，这会默默地破坏您的中间件：

// NestJS 10 — works
consumer.apply(LoggerMiddleware).forRoutes('*');

// NestJS 11 — use '*path' instead
consumer.apply(LoggerMiddleware).forRoutes('*path');

这同样适用于 Swagger 设置和任何基于字符串的路由模式。此更改会影响中间件注册、路由排除以及任何使用 glob 样式路由匹配的地方。

---

基于角色的访问控制

除了 JWT 身份验证之外，企业 API 还需要基于角色的授权。装饰器加保护模式使控制器保持干净：

// decorators/roles.decorator.ts
import { SetMetadata } from '@nestjs/common';

export type Role = 'admin' | 'support' | 'user';
export const ROLES_KEY = 'roles';
export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);

// guards/roles.guard.ts
import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { ROLES_KEY, Role } from '../decorators/roles.decorator';
import { AuthenticatedRequest } from '../../types/authenticated-request.interface';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);

    if (!requiredRoles) return true;

    const { user } = context.switchToHttp().getRequest<AuthenticatedRequest>();
    const hasRole = requiredRoles.some((role) => user.role === role);

    if (!hasRole) {
      throw new ForbiddenException('Insufficient permissions');
    }

    return true;
  }
}

在控制器中的用法：

// For top-level module controllers — one `..`
import { Roles } from '../auth/guards/roles.guard';

// For nested sub-module controllers — two `../..`
import { Roles } from '../../auth/guards/roles.guard';

@Controller('admin/contacts')
@Roles('admin', 'support')
export class AdminContactsController {}

导入路径深度是错误的常见来源。顶层模块控制器使用一个 ..；嵌套子模块控制器使用两个 ../..。

---

全局 EmailModule 模式

@Global() 装饰器解决了到处使用的服务的重复导入问题。电子邮件是典型的用例 - 您不想在每个发送通知的功能模块中导入 EmailModule 。

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

@Global()
@Module({
  providers: [EmailService],
  exports: [EmailService],
})
export class EmailModule {}

在 AppModule 中注册一次：

@Module({
  imports: [
    EmailModule, // Global — available everywhere
    ContactsModule,
    BillingModule,
    // ...
  ],
})
export class AppModule {}

现在任何服务都可以注入 EmailService 而无需触及模块导入。相同的模式适用于 Redis、EventBus 和任何横切基础设施服务。

---

限制公共端点的速率

企业 API 每天都会面临滥用行为。 NestJS 的 @nestjs/throttler 与防护系统完美集成：

// app.module.ts
import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';

@Module({
  imports: [
    ThrottlerModule.forRoot([
      { name: 'short', ttl: 1000, limit: 10 },
      { name: 'medium', ttl: 60000, limit: 100 },
    ]),
  ],
  providers: [
    { provide: APP_GUARD, useClass: ThrottlerGuard },
  ],
})

使用 @Throttle() 覆盖每个端点，以对敏感路由进行更严格的限制：

import { Throttle } from '@nestjs/throttler';

@Controller('auth')
export class AuthController {
  @Post('exchange')
  @Public()
  @Throttle({ short: { ttl: 60000, limit: 5 } }) // 5 per minute
  async exchangeCode(@Body() dto: ExchangeCodeDto) {
    return this.authService.exchangeCode(dto.code);
  }
}

---

使用 @nestjs/terminus 进行健康检查

生产 API 需要运行状况端点来进行负载均衡器检查和监控。 @nestjs/terminus 提供了一个带有内置指标的声明式系统：

// health/health.controller.ts
import { Controller, Get } from '@nestjs/common';
import { HealthCheck, HealthCheckService, TypeOrmHealthIndicator } from '@nestjs/terminus';
import { Public } from '../auth/decorators/public.decorator';
import { DatabaseHealthIndicator } from './indicators/database.indicator';
import { RedisHealthIndicator } from './indicators/redis.indicator';

@Controller('health')
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private db: DatabaseHealthIndicator,
    private redis: RedisHealthIndicator,
  ) {}

  @Get()
  @Public()
  @HealthCheck()
  check() {
    return this.health.check([
      () => this.db.isHealthy('database'),
      () => this.redis.isHealthy('redis'),
    ]);
  }
}

Drizzle ORM 的自定义指示器（因为 terminus 没有内置指示器）：

// health/indicators/database.indicator.ts
import { Injectable } from '@nestjs/common';
import { HealthIndicator, HealthIndicatorResult, HealthCheckError } from '@nestjs/terminus';
import { db } from '@ecosire/db';
import { sql } from 'drizzle-orm';

@Injectable()
export class DatabaseHealthIndicator extends HealthIndicator {
  async isHealthy(key: string): Promise<HealthIndicatorResult> {
    try {
      await db.execute(sql`SELECT 1`);
      return this.getStatus(key, true);
    } catch (error) {
      throw new HealthCheckError('Database check failed', this.getStatus(key, false));
    }
  }
}

---

DTO 验证模式

ValidationPipe 和 whitelist: true 在未知属性到达您的服务层之前将其剥离。与 class-transformer 结合，DTO 成为您的第一道防线：

// contacts/dto/create-contact.dto.ts
import { IsString, IsEmail, IsOptional, IsEnum, MinLength, MaxLength } from 'class-validator';
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import { Transform } from 'class-transformer';

export enum ContactType {
  INDIVIDUAL = 'individual',
  COMPANY = 'company',
}

export class CreateContactDto {
  @ApiProperty({ example: 'Acme Corp' })
  @IsString()
  @MinLength(2)
  @MaxLength(255)
  @Transform(({ value }) => value?.trim())
  name: string;

  @ApiProperty({ example: '[email protected]' })
  @IsEmail()
  @Transform(({ value }) => value?.toLowerCase().trim())
  email: string;

  @ApiPropertyOptional({ enum: ContactType })
  @IsOptional()
  @IsEnum(ContactType)
  type?: ContactType;

  @ApiPropertyOptional()
  @IsOptional()
  @IsString()
  @MaxLength(500)
  notes?: string;
}

@Transform 装饰器在验证层标准化数据。修剪空格和小写电子邮件可防止因大小写差异而导致重复记录。

---

Swagger 集成

企业 API 需要文档。 NestJS 的 Swagger 模块从装饰器生成 OpenAPI 规范，但设置必须经过深思熟虑：

// main.ts
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('ECOSIRE API')
    .setDescription('Enterprise API for ECOSIRE platform')
    .setVersion('1.0')
    .addBearerAuth()
    .addTag('auth', 'Authentication endpoints')
    .addTag('contacts', 'Contact management')
    .build();

  const document = SwaggerModule.createDocument(app, config);

  // Only expose in non-production environments
  if (process.env.NODE_ENV !== 'production') {
    SwaggerModule.setup('api/docs', app, document);
  }

  await app.listen(3001);
}

每个控制器方法都需要 @ApiOperation 和 @ApiResponse：

@Get(':id')
@ApiOperation({ summary: 'Get contact by ID' })
@ApiResponse({ status: 200, description: 'Contact found', type: ContactResponseDto })
@ApiResponse({ status: 404, description: 'Contact not found' })
async findOne(@Param('id') id: string, @Req() req: AuthenticatedRequest) {
  return this.contactsService.findOne(id, req.user.organizationId);
}

---

常见陷阱和解决方案

陷阱1：模块之间的循环依赖

循环导入在启动时导致 NestJS 崩溃，并出现一个神秘的错误。修复方法是 forwardRef()：

@Module({
  imports: [forwardRef(() => BillingModule)],
})
export class LicenseModule {}

更好的解决方案：将共享逻辑提取到第三个模块，两个模块都无需循环依赖即可导入。

陷阱 2：模块初始化期间环境变量不可用

如果在 dotenv 加载之前在类构造函数或提供程序工厂中访问 process.env.DATABASE_URL，您将获得 undefined。解决方案：在导入任何 NestJS 之前，在 main.ts 的最顶部加载 dotenv。

// main.ts — must be FIRST
import * as path from 'path';
require('dotenv').config({ path: path.join(__dirname, '..', '..', '..', '.env.local') });

// Then NestJS imports
import { NestFactory } from '@nestjs/core';

陷阱 3：生命周期挂钩中缺少异步操作的等待

// Wrong — database connection might not be ready
@Injectable()
export class AppService implements OnModuleInit {
  onModuleInit() {
    this.seedDatabase(); // Not awaited!
  }
}

// Correct
async onModuleInit() {
  await this.seedDatabase();
}

陷阱 4：在 Drizzle 查询中使用 sql.raw()

sql.raw() 绕过参数化并打开 SQL 注入向量。始终使用 sql 模板文字：

// Dangerous — never do this
const result = await db.execute(sql.raw(`SELECT * FROM contacts WHERE id = '${id}'`));

// Safe — parameterized
const result = await db.execute(sql`SELECT * FROM contacts WHERE id = ${id}`);

---

常见问题

如何处理 NestJS 11 API 中的版本控制？

NestJS 11 支持开箱即用的 URI 版本控制、标头版本控制和媒体类型版本控制。在 main.ts 中使用 app.enableVersioning({ type: VersioningType.URI }) 启用它，然后使用 @Version('1') 装饰控制器。对于企业 API，URI 版本控制 (/v1/contacts) 是最明确且缓存友好的方法。

NestJS 中处理文件上传的最佳方式是什么？

使用 @nestjs/platform-express 和 multer 进行文件上传。对于 S3 上传，通过 multer-s3 配置自定义存储引擎。在处理程序运行之前，始终在管道级别验证文件类型和大小，并且永远不要信任客户端提供的 MIME 类型 - 而是验证魔术字节。

我应该如何在 NestJS 中构建数据库事务？

Drizzle ORM 支持 db.transaction(async (tx) => { ... }) 的事务。将事务对象传递给服务方法而不是全局 db 实例。对于多操作业务逻辑（创建订单+扣除库存+发送电子邮件），将所有内容包装在事务中，并在提交后使用 .catch() 使电子邮件发送非阻塞。

什么时候应该使用守卫、中间件和拦截器？

警卫处理授权（该用户可以访问该资源吗？）。中间件处理横切请求转换（日志记录、相关 ID、解析）。拦截器封装了转换、缓存和指标的请求-响应周期。执行顺序为：中间件→守卫→拦截器（之前）→管道→处理程序→拦截器（之后）→异常过滤器。

如何单独测试 NestJS 模块？

使用 Test.createTestingModule() 创建具有模拟依赖项的测试沙箱。使用 jest.fn() 或 vi.fn() 模拟您的服务方法，并独立于数据库测试控制器行为。对于集成测试，请使用 @nestjs/testing 与真实数据库连接（单独的测试数据库）并在每次测试后进行事务回滚。

全局守卫对性能有何影响？

全局警卫会根据每个请求运行，因此请保持速度快。 JWT 验证通常为 1-5ms。避免在防护中进行数据库查找 - 在令牌创建期间加载权限并将其包含在 JWT 有效负载中。如果您需要对每个请求提供新的权限，请使用具有较短 TTL 的 Redis，而不是访问数据库。

---

后续步骤

大规模构建企业 API 从一开始就需要正确的架构。 ECOSIRE 的工程团队构建并运营了一个包含 56 个模块的 NestJS 11 后端，可处理复杂的多租户工作流程、Stripe 计费、许可证管理和人工智能驱动的分析。

无论您需要自定义 NestJS API、Odoo ERP 集成还是全栈企业平台，我们的团队都会为您的项目带来经过生产验证的模式。 探索我们的开发服务 了解我们如何加速您的下一个构建。