【NestJS】11 管道：数据验证与转换实战

1
请求 → 中间件 → 守卫 → 拦截器（前） → 管道 → 控制器

1
@Get(':id')
2
findOne(@Param('id', ParseIntPipe) id: number) {
3
  // id 自动转换为 number 类型
4
  return this.userService.findOne(id);
5
}

1
@Get(':price')
2
getPrice(@Param('price', ParseFloatPipe) price: number) {
3
  return { price };
4
}

1
@Get()
2
findAll(@Query('active', ParseBoolPipe) active: boolean) {
3
  return this.userService.findAll({ active });
4
}

1
@Get(':id')
2
findOne(@Param('id', ParseUUIDPipe) id: string) {
3
  // id 必须是有效的 UUID 格式（如：550e8400-e29b-41d4-a716-446655440000）
4
  return this.userService.findOne(id);
5
}

1
enum UserRole {
2
  ADMIN = 'admin',
3
  USER = 'user',
4
  GUEST = 'guest',
5
}
6

7
@Get(':role')
8
findByRole(
9
  @Param('role', new ParseEnumPipe(UserRole)) role: UserRole,
10
) {
11
  // role 必须是枚举中定义的值
12
  return this.userService.findByRole(role);
13
}

1
@Get()
2
findAll(
3
  @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
4
  @Query('limit', new DefaultValuePipe(10), ParseIntPipe) limit: number,
5
) {
6
  // 如果 page 或 limit 不存在，使用默认值
7
  return this.userService.findAll(page, limit);
8
}

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

3
export class CreateUserDto {
4
  @IsString()        // 验证是否为字符串
5
  @IsNotEmpty()      // 验证是否不为空
6
  name: string;
7

8
  @IsEmail()         // 验证邮箱格式
9
  @IsNotEmpty()
10
  email: string;
11
}

1
@Post()
2
@UsePipes(
3
  new ValidationPipe({
4
    whitelist: true,
5
    transform: true,
6
  }),
7
)
8
create(@Body() createUserDto: CreateUserDto) {
9
  return this.userService.create(createUserDto);
10
}

1
// 基础验证
2
@IsString()                          // 验证是否是字符串
3
@IsNotEmpty()                        // 验证是否不为空
4

5
// 长度验证
6
@Length(2, 20)                       // 验证长度在 2-20 之间
7
@MinLength(2)                        // 最小长度 2
8
@MaxLength(20)                       // 最大长度 20
9

10
// 正则验证
11
@Matches(/^[a-zA-Z0-9]+$/)          // 匹配正则表达式

1
@IsNumber()                          // 验证是否是数字
2
@IsInt()                            // 验证是否是整数
3
@Min(0)                             // 最小值 0
4
@Max(120)                           // 最大值 120
5
@IsPositive()                       // 验证是否是正数
6
@IsNegative()                       // 验证是否是负数

1
@IsEmail()                          // 验证邮箱格式
2
@IsUrl()                            // 验证 URL 格式

1
@IsDate()                           // 验证是否是日期对象
2
@IsDateString()                     // 验证是否是日期字符串（ISO 8601）

1
@IsArray()                          // 验证是否是数组
2
@ArrayMinSize(1)                    // 数组最小长度 1
3
@ArrayMaxSize(10)                   // 数组最大长度 10
4
@ArrayNotEmpty()                    // 数组不能为空

1
@IsOptional()                       // 标记字段为可选
2
@IsString()
3
nickname?: string;

1
enum UserRole {
2
  ADMIN = 'admin',
3
  USER = 'user',
4
}
5

6
@IsEnum(UserRole)                   // 验证枚举值
7
role: UserRole;

1
{
2
  "statusCode": 400,
3
  "message": [
4
    "用户名至少2个字符",
5
    "邮箱格式不正确",
6
    "密码至少6个字符",
7
    "密码必须包含大小写字母和数字"
8
  ],
9
  "error": "Bad Request"
10
}

1
import { ValidateNested, IsObject } from 'class-validator';
2
import { Type } from 'class-transformer';
3

4
class AddressDto {
5
  @IsString()
6
  @IsNotEmpty()
7
  street: string;
8

9
  @IsString()
10
  @IsNotEmpty()
11
  city: string;
12

13
  @IsString()
14
  @IsNotEmpty()
15
  zipCode: string;
16
}
17

18
export class CreateUserDto {
19
  @IsString()
20
  name: string;
21

22
  @ValidateNested()              // 验证嵌套对象
23
  @Type(() => AddressDto)        // 指定类型
24
  @IsObject()
25
  address: AddressDto;
26
}

1
import { IsArray, ValidateNested } from 'class-validator';
2
import { Type } from 'class-transformer';
3

4
class TagDto {
5
  @IsString()
6
  @IsNotEmpty()
7
  name: string;
8
}
9

10
export class CreatePostDto {
11
  @IsString()
12
  @IsNotEmpty()
13
  title: string;
14

15
  @IsArray()
16
  @ValidateNested({ each: true })  // 验证数组中的每个元素
17
  @Type(() => TagDto)
18
  tags: TagDto[];
19
}

1
@Post()
2
create(@Body('phone', PhoneValidationPipe) phone: string) {
3
  // phone 已经过验证，是有效的手机号
4
  return this.userService.create({ phone });
5
}

1
transform(value: any, metadata: ArgumentMetadata) {
2
  // value: 要转换的值
3
  // metadata: 元数据对象
4

5
  console.log('值:', value);
6
  console.log('类型:', metadata.type);      // 'body' | 'query' | 'param' | 'custom'
7
  console.log('元数据:', metadata.metatype); // 参数的类型
8
  console.log('参数名:', metadata.data);     // 参数名（如果指定了）
9

10
  return value;
11
}

1
import { Transform } from 'class-transformer';
2

3
export class CreateUserDto {
4
  @Transform(({ value }) => value.trim())    // 去除首尾空格
5
  @IsString()
6
  username: string;
7

8
  @Transform(({ value }) => value.toLowerCase()) // 转换为小写
9
  @IsEmail()
10
  email: string;
11
}

1
import { Exclude, Expose } from 'class-transformer';
2

3
export class UserDto {
4
  @Expose()
5
  id: number;
6

7
  @Expose()
8
  name: string;
9

10
  @Exclude()                    // 排除密码字段，防止泄露
11
  password: string;
12
}

1
import { Type } from 'class-transformer';
2

3
export class CreateUserDto {
4
  @Type(() => Date)             // 将字符串转换为 Date 对象
5
  birthDate: Date;
6

7
  @Type(() => AddressDto)       // 指定嵌套对象类型
8
  address: AddressDto;
9
}

1
// ✅ 推荐：全局配置
2
app.useGlobalPipes(
3
  new ValidationPipe({
4
    whitelist: true,
5
    forbidNonWhitelisted: true,
6
    transform: true,
7
  }),
8
);

1
// ✅ 推荐：友好的错误消息
2
@IsString({ message: '用户名必须是字符串' })
3
@MinLength(2, { message: '用户名至少需要2个字符，请重新输入' })
4
username: string;
5

6
// ❌ 避免：使用默认消息
7
@IsString()
8
@MinLength(2)
9
username: string;

1
// ✅ 推荐：复用 DTO
2
export class CreateUserDto {
3
  @IsString()
4
  name: string;
5

6
  @IsEmail()
7
  email: string;
8
}
9

10
// 更新 DTO 继承创建 DTO，所有字段自动变为可选
11
export class UpdateUserDto extends PartialType(CreateUserDto) {}

1
// ✅ 推荐：使用常量
2
const USERNAME_MIN_LENGTH = 2;
3
const USERNAME_MAX_LENGTH = 20;
4
const USERNAME_PATTERN = /^[a-zA-Z0-9_\u4e00-\u9fa5]+$/;
5

6
export class CreateUserDto {
7
  @MinLength(USERNAME_MIN_LENGTH)
8
  @MaxLength(USERNAME_MAX_LENGTH)
9
  @Matches(USERNAME_PATTERN)
10
  username: string;
11
}

1
// ✅ 推荐：自定义装饰器
2
import { registerDecorator, ValidationOptions } from 'class-validator';
3

4
export function IsStrongPassword(validationOptions?: ValidationOptions) {
5
  return function (object: Object, propertyName: string) {
6
    registerDecorator({
7
      name: 'isStrongPassword',
8
      target: object.constructor,
9
      propertyName: propertyName,
10
      options: validationOptions,
11
      validator: {
12
        validate(value: any) {
13
          return /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])/.test(value);
14
        },
15
        defaultMessage() {
16
          return '密码必须包含大小写字母、数字和特殊字符';
17
        },
18
      },
19
    });
20
  };
21
}
22

23
// 使用
24
export class CreateUserDto {
25
  @IsStrongPassword()
26
  password: string;
27
}