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 以保持一致。