NestJS 内置 Pipes笔记

一、概述

Nest 内置 Pipe 均从 @nestjs/common 导出，用于参数验证、类型转换、默认值等场景，可直接在控制器路由、DTO、全局配置中使用。

二、内置 Pipe 清单与作用

1. 验证类

1.1 ValidationPipe

• 作用：最常用的全局验证管道，配合 class-validator + class-transformer 对 DTO 进行自动校验。
• 场景：校验请求体、查询参数、路径参数的合法性。

• 常用配置：

  • whitelist: true：过滤掉非 DTO 定义的字段
  • forbidNonWhitelisted: true：禁止传入多余字段
  • transform: true：自动将原始值转为 DTO 对应类型

2. 基础类型转换

2.1 ParseIntPipe

• 作用：将参数转为整数，转换失败抛出 400 Bad Request。
• 场景：id、page、limit 等数字路径参数。

2.2 ParseFloatPipe

• 作用：转为浮点数。
• 场景：价格、经纬度、小数类参数。

2.3 ParseBoolPipe

• 作用：转为布尔值，支持 true/false、1/0、'true'/'false'。
• 场景：开关、状态查询参数。

3. 格式/结构校验

3.1 ParseUUIDPipe

• 作用：校验参数是否为合法 UUID（v4 等），不合法则报错。
• 场景：用户 ID、订单号等 UUID 格式参数。

3.2 ParseEnumPipe

• 作用：校验参数是否属于指定枚举。
• 场景：状态、类型、固定选项参数。

3.3 ParseArrayPipe

• 作用：将字符串转为数组，可指定分隔符、校验每项类型。
• 场景：批量 ID、多选参数 ?ids=1,2,3。

3.4 ParseDatePipe

• 作用：将字符串/时间戳转为 Date 对象，非法日期报错。
• 场景：开始时间、结束时间等日期参数。

4. 文件与默认值

4.1 DefaultValuePipe

• 作用：为参数提供默认值，不与其他 Pipe 冲突。
• 场景：分页默认 page=1、limit=10。

4.2 ParseFilePipe

• 作用：上传文件校验，可校验文件类型、大小、数量等。
• 场景：单文件/多文件上传校验。

三、典型使用方式（极简示例）

1. 路由参数直接使用

@Get(':id')
getOne(@Param('id', ParseIntPipe) id: number) {}

2. 带默认值

@Get()
getList(
  @Query('page', ParseIntPipe, new DefaultValuePipe(1)) page: number,
) {}

3. 枚举校验

@Get('type/:type')
getByType(
  @Param('type', new ParseEnumPipe(StatusEnum)) type: StatusEnum,
) {}

4. 全局启用 ValidationPipe（推荐）

// main.ts
app.useGlobalPipes(
  new ValidationPipe({
    transform: true,
    whitelist: true,
  }),
);

四、使用总结

• 校验 + 转换：统一由 Pipe 完成，控制器代码更干净。
• 失败自动抛错：返回标准 400 错误，无需手动判断。
• 可组合：多个 Pipe 可按顺序链式使用。