栈记
Nest

管道 pipe

内置管道、类型转换与自定义管道

说明

管道的主要作用是类型转换和类型验证,当管道抛出异常时会被 Exception Filter 接收异常并不处理,不会调用实际的业务方法。

内置管道

Nest 提供了一些内置的管道,这些管道都来自 @nestjs/common

管道说明
ValidationPipe自定义校验管道
ParseIntPipe尝试转换整数并且验证
ParseFloatPipe尝试转换浮点数并且验证
ParseBoolPipe布尔值验证
ParseArrayPipe校验数组类型,如果复杂类型可以使用 new ParseArrayPipe({ items: Dto })
ParseUUIDPipe校验 uuid 可以指定版本 new PaseUUIDPipe({ version: '3' }) 支持 3,4,5,7
ParseEnumPipe校验 enum 类型,需要通过 new PaseEnumPipe(EnumState) 方式调用
DefaultValuePipe默认值
ParseFilePipe文件校验
ParseDatePipe日期校验

管道的实际使用中可以直接传递一个类,也可以是这个管道的实例对象。

import {
  Controller,
  Get,
  Body,
  ParseIntPipe,
  ParseBoolPipe,
  ParseFloatPipe,
  ParseArrayPipe,
  ParseUUIDPipe,
  ParseEnumPipe,
  DefaultValuePipe,
  ParseDatePipe,
} from '@nestjs/common';

@Controller('users')
export class UsersController {

  @Get()
  findAll(
    @Body('id', ParseIntPipe) id: number,
    @Body('bool', ParseBoolPipe) bool: boolean,
    @Body('float', ParseFloatPipe) float: number,
    @Body('arr', ParseArrayPipe) arr: string[],
    @Body('uuid', new ParseUUIDPipe({ version: '4' })) uuid: string,
    @Body('en', new ParseEnumPipe(State)) en: State,
    @Body('defaultDate', new DefaultValuePipe(new Date()), new ParseDatePipe()) defaultDate: string
  ) {
    return this.usersService.finAll();
  }
}

// 对于校验失败的内容系统会默认返回 
// {
//   "statusCode": 400,
//   "message": "Validation failed (numeric string is expected)",
//   "error": "Bad Request"
// }

自定义管道

自定义的管道需要实现 PipeTransform 类中的 transform 方法

该方法中接收 value 及 metadata 参数。大部分场景下无需自定义管道,本身的功能已经很完善了


import { PipeTransform, Injectable, ArgumentMetadata, BadRequestException } from '@nestjs/common';
// 类校验库和类转换库
import { validate } from 'class-validator';
import { plainToInstance } from 'class-transformer';

@Injectable()
export class ValidationPipe implements PipeTransform<any> {
  async transform(value: any, { metatype }: ArgumentMetadata) {
    if (!metatype || !this.toValidate(metatype)) {
      return value;
    }
    // 将普通对象变成实例对象
    // instanceToPlain
    // plainToClass ... 其他方法
    const object = plainToInstance(metatype, value);
    // 校验对象是否符合规范
    const errors = await validate(object);
    if (errors.length > 0) {
      throw new BadRequestException('Validation failed');
    }
    return value;
  }

  private toValidate(metatype: Function): boolean {
    const types: Function[] = [String, Boolean, Number, Array, Object];
    return !types.includes(metatype);
  }
}

在使用时有三种方案,controller、global、appModule 全局模式下不会为网关和微服务设置管道

// users.controller.ts
@Controller
export class UsersController {

  @Post()
  create(@Body(new ValidationPipe()) createUserDto: CreateUserDto) {}

  @Patch()
  // 也可以是为整个方法或者 controller 进行注解
  @UsePipes(new ValidationPipe())
  update(@Body() createUserDto: CreateUserDto) {}
}

// main.ts
const app = await NestFactory.create(AppModule);
app.useGlobalPipes(new ValidationPipe());

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

@Module({
  // 此种情况 useClass 并不是唯一选择,也可以是 useFactory 再次注入一些其他的依赖丰富 ValidationPipe 的内容
  prodivders: [{ provide: APP_PIPE, useClass: ValidationPipe }]
})
export class AppModule {}

类验证器

class-validator 是在 Nestjs 开发过程中比较重要的一个三方库 GitHub。通过装饰器的方式对数据的类型进行校验;

在 Nest 中常用于校验 Dto 数据。

在使用时,除了一些特殊的注解,需要多传递一些参数,一般都会接受一个 message 作为校验失败后的返回;也可以允许针对同一个字段使用多种规则。

import {
  IsNumber, // 是否为数字
  IsString, // 是否为字符串
  IsArray, // 是否为数组
  IsEnum, // 是否为枚举
  IsBoolean, // 是否为 bool
  IsOptional, // 是否可选
  IsNotEmpty, // 不是 null undefined ''
  IsEmail, // 是否为 email
  IsPhoneNumber, // 是否为电话号码,格式为 区号 + 号码 示例 03941234567 0394 是我老家的区号 哈哈
  IsMobilePhone, // 是否为手机号,指定地区后 +86手机号 实例 +8618342348234
  MinLength, // 最大长度
  MaxLength, // 最小长度
  Min, // 最大值
  Max // 最小值
} from 'class-validator';

enum Role {
  ADMIN = 'ADMIN',
  PLAIN = 'PLAIN'
}

export class CreateUserDto {
  @IsNumber()
  @Max(10)
  @Min(0)
  num: number;
  @IsString()
  @MaxLength(10)
  @MinLength(1)
  str: string;
  @IsEmail()
  @IsOptional()
  email: string;
  // 指定地区和模式,message 则是校验失败后的信息
  @IsMobilePhone('zh-CN', { strictMode: true }, { message: 'xxx' })
  mobile: string;
  @IsEnum(Role)
  role: Role;
}

复杂类型的校验

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

class User {
  @IsString()
  id: string;
  @IsString()
  name: string;
}

export class CreateUserDto {
  @IsArray()
  // 如果需要为数组中的每个元素都校验可以使用 each true
  // 仅限于简单类型的校验
  @MaxLength(3, { each: true })
  arr: string[]

  // 嵌套对象的类型必须是类的实例不然无法进行校验
  @ValidateNested()
  @Type(() => User) // 通过 transformer 转换类型
  user: User;

  @ValidateNested()
  @Type(() => User)
  users: User[];
}

On this page