SuperAPI AI 工具集

validation

编程与开发

查看项目

更新于 10-16 10:48

技能介绍

NestJS Validation 技能

适用场景

该技能适用于以下情况:校验请求体(POST、PUT、PATCH);校验查询参数与路由参数;转换和清洗输入数据;从请求中剥离不需要的属性;实现自定义验证逻辑;自动转换基本类型;校验嵌套对象和数组。

概念说明

NestJS ValidationPipe 使用 class-validator 库,通过声明式装饰器将传入数据与 DTO 类进行校验,提供自动验证、转换与清洗能力。

安装

npm install class-validator class-transformer

基础设置

全局启用 ValidationPipe:

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());

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

基础验证

使用验证装饰器创建 DTO:

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

export class CreateUserDto { @IsEmail() email: string;

@IsString() @IsNotEmpty() @MinLength(8) password: string;

@IsString() @IsNotEmpty() name: string; }

在控制器中使用:

import { Body, Controller, Post } from '@nestjs/common'; import { CreateUserDto } from './dto/create-user.dto';

@Controller('users') export class UsersController { @Post() create(@Body() createUserDto: CreateUserDto) { return createUserDto; } }

如果验证失败,ValidationPipe 会抛出 BadRequestException 并附带错误详情。

常用验证装饰器

字符串验证器:@IsString、@IsNotEmpty、@MinLength、@MaxLength、@Matches、@IsEmail、@IsUrl、@IsUUID、@IsAlpha、@IsAlphanumeric。

数字验证器:@IsNumber、@IsInt、@IsPositive、@IsNegative、@Min、@Max、@IsDivisibleBy。

布尔验证器:@IsBoolean。

日期验证器:@IsDate、@MinDate、@MaxDate。

数组验证器:@IsArray、@ArrayMinSize、@ArrayMaxSize、@ArrayNotEmpty、@ArrayUnique。

枚举验证器:@IsEnum。

对象验证器:@IsObject、@ValidateNested(配合 class-transformer 的 @Type 使用)。

ValidationPipe 选项

app.useGlobalPipes( new ValidationPipe({ // 自动将载荷转换为 DTO 实例 transform: true,

// 剥离 DTO 中不存在的属性
whitelist: true,

// 若存在非白名单属性则抛错
forbidNonWhitelisted: true,

// 跳过 undefined 属性的验证
skipMissingProperties: false,

// 跳过 null 属性的验证
skipNullProperties: false,

// 跳过 undefined 值的验证
skipUndefinedProperties: false,

// 禁用详细错误(用于生产环境)
disableErrorMessages: false,

// 自定义错误消息处理器
exceptionFactory: (errors) => new BadRequestException(errors),

// 验证分组
groups: [],

// 始终验证(即使没有装饰器)
always: false,

// 启用严格分组模式
strictGroups: false,

// 丢弃默认消息
dismissDefaultMessages: false,

// class-validator 的验证选项
validationError: {
  target: false,
  value: false,
},

// 启用自动转换
transformOptions: {
  enableImplicitConversion: true,
},

}), );

自动转换

当 transform: true 时,ValidationPipe 会自动转换类型,例如 "5" → 5(number)、"true" → true(boolean)、"2024-01-01" → Date 对象。控制器中通过 @Query() 接收的 DTO 字段类型会变为对应的 number、boolean 等。

属性剥离(白名单)

若 DTO 中没有定义 role 属性,而请求体包含 role: "admin",启用 whitelist: true 后会被剥离;配合 forbidNonWhitelisted: true 则会在检测到该属性时抛出错误。

自定义验证器

可通过 @ValidatorConstraint 实现 ValidatorConstraintInterface 接口,并配合 registerDecorator 创建自定义装饰器,例如 IsStrongPassword,在 validate 方法中实现校验逻辑,在 defaultMessage 中返回错误提示。

异步自定义验证器

使用 @ValidatorConstraint({ name: '...', async: true }) 标注并在类上使用 @Injectable(),可在构造函数中注入服务(如 UsersService),在 validate 方法内异步查询数据,例如判断邮箱是否已存在。

条件验证与可选属性

使用 @ValidateIf 根据其他字段值决定是否校验,例如仅当 type 为 'email' 时校验 email 字段。使用 @IsOptional 将属性标记为可选。

验证分组

在装饰器选项中通过 groups 指定分组(如 ['create']、['update']),并在控制器中通过 new ValidationPipe({ groups: [...] }) 应用不同分组进行创建与更新场景的差异化验证。

数组对象验证

使用 @IsArray、@ValidateNested({ each: true }) 与 @Type(() => ItemDto) 对对象数组进行校验。

装饰器参考

类型验证器:@IsBoolean、@IsDate、@IsNumber、@IsInt、@IsString、@IsArray、@IsEnum(entity)、@IsObject。

字符串验证器:@IsEmail、@IsUrl、@IsUUID、@IsAlpha、@IsAlphanumeric、@IsHexColor、@IsJSON。

数字验证器:@IsPositive、@IsNegative、@Min(min)、@Max(max)、@IsDivisibleBy(num)。

通用验证器:@IsDefined、@IsOptional、@IsNotEmpty、@IsEmpty、@IsIn(values)、@IsNotIn(values)。

数组验证器:@ArrayContains(values)、@ArrayNotContains(values)、@ArrayNotEmpty、@ArrayMinSize(min)、@ArrayMaxSize(max)、@ArrayUnique。

对象验证器:@ValidateNested、@IsInstance(value)。

映射类型

NestJS 提供 @nestjs/mapped-types 中的工具转换 DTO:PartialType(全部属性变为可选)、PickType(仅保留指定属性)、OmitType(排除指定属性)、IntersectionType(合并 DTO)。

解析与转换管道

ParseIntPipe 用于路由参数转整数;ParseBoolPipe 用于查询参数转布尔;ParseUUIDPipe 用于校验 UUID;ParseArrayPipe 用于解析数组。

自定义错误消息

装饰器可传入 message 选项,例如 @IsEmail({}, { message: 'Please provide a valid email address' })、@MinLength(8, { message: '...' })。

测试验证

可引入 class-validator 的 validate 函数对 DTO 进行单元测试,断言错误数量与出错属性。

最佳实践

始终创建独立 DTO 类;启用 whitelist: true 剥离多余数据;使用 transform: true 自动转换;生产环境使用 forbidNonWhitelisted: true;提供用户友好的错误消息;使用映射类型复用 DTO;使用 @ValidateNested() 与 @Type() 校验嵌套对象;为 DTO 编写单元测试;利用 TypeScript 类型;全局设置 ValidationPipe 以保持一致。