4. 数据传输对象(DTO)与验证

在 NestJS 应用中，客户端发送的请求数据往往不可信。DTO（Data Transfer Object）模式与验证管道共同构成了数据进入业务逻辑前的第一道防线。本章将系统讲解 DTO 的设计原则、class-validator 与 class-transformer 的集成方式，以及全局 ValidationPipe 的配置策略。

4.1 DTO 模式介绍

DTO 是一种设计模式，用于在不同层之间传输数据。在 NestJS 中，DTO 通常是一个简单的 TypeScript 类，用于定义 API 请求体的结构，并配合装饰器声明验证规则。

4.2 class-validator 与 class-transformer 集成

NestJS 推荐使用 class-validator 进行声明式验证，class-transformer 负责将普通 JSON 对象转换为类实例。两者配合使用，才能让 ValidationPipe 正常工作。

4.2.1 安装依赖

npm install class-validator class-transformer

4.2.2 定义 DTO 类

以下是一个创建用户的 DTO 示例，展示了常用验证装饰器的组合使用：

import {
  IsString,
  IsEmail,
  IsOptional,
  MinLength,
  MaxLength,
  Matches,
  IsEnum,
} from 'class-validator';

export enum UserRole {
  ADMIN = 'admin',
  USER = 'user',
  GUEST = 'guest',
}

export class CreateUserDto {
  @IsString()
  @MinLength(2, { message: '用户名至少2个字符' })
  @MaxLength(20)
  @Matches(/^[a-zA-Z0-9_]+$/, {
    message: '用户名只能包含字母、数字和下划线',
  })
  username: string;

  @IsEmail({}, { message: '请输入有效的邮箱地址' })
  email: string;

  @IsString()
  @MinLength(8)
  @MaxLength(32)
  password: string;

  @IsOptional()
  @IsEnum(UserRole, { message: '角色必须是 admin、user 或 guest' })
  role?: UserRole;
}

4.2.3 class-transformer 的隐式转换

当请求体中的字段类型与 DTO 属性类型不匹配时，class-transformer 可以自动进行类型转换：

import { Type } from 'class-transformer';
import { IsNumber, IsArray, ValidateNested } from 'class-validator';

export class OrderItemDto {
  @IsString()
  productId: string;

  @Type(() => Number)  // 将字符串 "2" 转换为数字 2
  @IsNumber()
  quantity: number;
}

export class CreateOrderDto {
  @IsArray()
  @ValidateNested({ each: true })
  @Type(() => OrderItemDto)
  items: OrderItemDto[];
}

4.3 全局 ValidationPipe 配置

ValidationPipe 是 NestJS 内置的管道，它利用 class-validator 和 class-transformer 自动验证传入的请求数据。全局注册可以避免在每个 Controller 中重复声明。

4.3.1 基础配置

import { ValidationPipe } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

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

  app.useGlobalPipes(
    new ValidationPipe({
      // 关键配置项
      whitelist: true,          // 自动剔除 DTO 中未定义的属性
      forbidNonWhitelisted: true, // 当存在未定义属性时抛出异常
      transform: true,          // 自动将请求数据转换为 DTO 实例
      transformOptions: {
        enableImplicitConversion: false, // 关闭隐式转换，推荐显式使用 @Type()
      },
    }),
  );

  await app.listen(3000);
}
bootstrap();

4.3.2 配置项详解

4.3.3 自定义异常格式

app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    transform: true,
    exceptionFactory: (errors) => {
      const formattedErrors = errors.map((err) => ({
        field: err.property,
        constraints: err.constraints,
      }));
      return new BadRequestException({
        statusCode: 400,
        message: '请求数据验证失败',
        errors: formattedErrors,
      });
    },
  }),
);

4.4 DTO 验证流程架构

下图展示了从 HTTP 请求到达 Controller 之前，DTO 验证的完整数据流：

4.5 常见验证场景与最佳实践

4.5.1 条件验证

使用 @ValidateIf 实现条件验证：

import { ValidateIf, IsNotEmpty } from 'class-validator';

export class UpdateProfileDto {
  @IsOptional()
  @IsString()
  name?: string;

  @ValidateIf((o) => o.email !== undefined)
  @IsNotEmpty({ message: '邮箱不能为空' })
  email?: string;
}

4.5.2 自定义验证装饰器

import { registerDecorator, ValidationOptions, ValidationArguments } from 'class-validator';

export function IsPasswordStrong(validationOptions?: ValidationOptions) {
  return function (object: Object, propertyName: string) {
    registerDecorator({
      name: 'isPasswordStrong',
      target: object.constructor,
      propertyName: propertyName,
      options: validationOptions,
      validator: {
        validate(value: any, args: ValidationArguments) {
          return typeof value === 'string' &&
            /[A-Z]/.test(value) &&  // 至少一个大写字母
            /[a-z]/.test(value) &&  // 至少一个小写字母
            /[0-9]/.test(value) &&   // 至少一个数字
            /[!@#$%^&*]/.test(value); // 至少一个特殊字符
        },
        defaultMessage(args: ValidationArguments) {
          return '密码必须包含大写字母、小写字母、数字和特殊字符';
        },
      },
    });
  };
}

4.5.3 验证组（Validation Groups）

同一 DTO 在不同场景下使用不同的验证规则：

import { IsString, MinLength, ValidateIf } from 'class-validator';

export class UserDto {
  @IsString({ groups: ['create'] })
  @MinLength(3, { groups: ['create'] })
  @ValidateIf((o) => o.id !== undefined, { groups: ['update'] })
  @IsString({ groups: ['update'] })
  username: string;
}

// 在 Controller 中使用
@Post()
create(@Body(new ValidationPipe({ groups: ['create'] })) dto: UserDto) { }

@Patch(':id')
update(@Body(new ValidationPipe({ groups: ['update'] })) dto: UserDto) { }

4.6 安全验证清单