【Nest】管道

常见管道

在 NestJS 中，管道（Pipe）是处理请求数据转换和验证的核心工具。以下是几种常用内置管道的功能详解及其应用场景：

---

1. ValidationPipe

作用：基于 class-validator 和 class-transformer 验证请求数据的有效性，确保数据符合预定义的 DTO（数据传输对象）规则。 因此使用前，应该先安装这两个库。
应用场景：
• 表单验证：检查请求体中的必填字段、格式（如邮箱、密码强度等）。
• 参数校验：验证查询参数或路径参数是否合法。
• 转换：将请求数据自动转换为目标类型（例如将字符串转换为数字）。

示例：

// DTO 定义
import { IsEmail, IsNotEmpty } from 'class-validator';
export class CreateUserDto {
  @IsNotEmpty()
  name: string;
  
  @IsEmail()
  email: string;
}

// 控制器中使用
@Post()
@UsePipes(new ValidationPipe({ whitelist: true })) // 过滤非 DTO 字段
createUser(@Body() createUserDto: CreateUserDto) {
  // 业务逻辑
}

效果：若请求体缺少 name 或 email 格式错误，自动返回 400 Bad Request。

全局使用：

useGlobalPipes 是 Nest.js 应用实例的方法，用于注册全局管道。一旦注册，该管道会应用于所有的控制器和路由处理程序，而无需在每个地方单独配置。

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe());
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      transform: true,
      forbidNonWhitelisted: true,
    }),
  );

app.useGlobalPipes(new ValidationPipe(options));

常用选项:

(1) whitelist: true

• 作用：启用白名单功能。
• 效果：只允许 DTO 中定义的属性通过验证，未定义的属性会被自动移除。
• 示例：

  // DTO 定义
  export class CreateUserDto {
    @IsString()
    name: string;
  }
  
  // 请求体
  {
    "name": "John",
    "age": 30 // 未定义的属性，会被移除
  }
  

(2) transform: true

• 作用：启用自动类型转换。
• 效果：将请求数据自动转换为 DTO 中定义的类型。
• 示例：

  // DTO 定义
  export class CreateUserDto {
    @IsNumber()
    age: number;
  }
  
  // 请求体
  {
    "age": "25" // 字符串会被转换为数字
  }
  

(3) forbidNonWhitelisted: true

• 作用：禁止非白名单属性。
• 效果：如果请求数据中包含 DTO 中未定义的属性，则直接抛出错误。
• 示例：

  // DTO 定义
  export class CreateUserDto {
    @IsString()
    name: string;
  }
  
  // 请求体
  {
    "name": "John",
    "age": 30 // 非白名单属性，会抛出错误
  }
  

---

2. ParseIntPipe

作用：将前端传递的可能是字符串类型的参数转换为整数，若转换失败则抛出异常。
应用场景：
• 路径参数转换：如将 /users/ 123 中的 123 转换为数字类型的 id。

示例：

@Get(':id')
getUser(@Param('id', ParseIntPipe) id: number) {
  // id 自动转为数字
  return this.userService.findById(id);
}

效果：若路径参数非数字（如 /users/abc），返回 400 Bad Request。

---

3. ParseFloatPipe

作用：将字符串参数转换为浮点数，类似 ParseIntPipe，但处理小数。
应用场景：
• 价格或坐标处理：如接收商品价格 price=19.99。

示例：

@Get('price')
getPrice(@Query('value', ParseFloatPipe) price: number) {
  return { price };
}

---

4. ParseBoolPipe

作用：将字符串参数（如 "true"、"1"）转换为布尔值。
应用场景：
• 状态过滤：如查询参数 ?active=true 过滤激活用户。

示例：

@Get()
getUsers(@Query('active', ParseBoolPipe) isActive: boolean) {
  return this.userService.findActiveUsers(isActive);
}

---

5. ParseArrayPipe

作用：将字符串表示的数组（如 1,2,3）转换为数组，并支持元素类型转换。
应用场景：
• 多选参数处理：如分类筛选 ?categories=1,2,3。

示例：

@Get()
getProducts(
  @Query('ids', new ParseArrayPipe({ items: Number })) ids: number[]
) {
  return this.productService.findByIds(ids);
}

---

6. ParseUUIDPipe

作用：验证参数是否为有效的 UUID 格式。
应用场景：
• 资源标识符验证：如 RESTful API 中通过 UUID 获取资源。

示例：

@Get(':uuid')
getResource(@Param('uuid', ParseUUIDPipe) uuid: string) {
  return this.resourceService.findByUUID(uuid);
}

---

7. ParseEnumPipe

作用：验证参数值是否属于特定枚举类型。
应用场景：
• 限制取值范围：如排序方向仅允许 asc 或 desc。

示例：

enum SortDirection { ASC = 'asc', DESC = 'desc' }

@Get()
getList(@Query('dir', new ParseEnumPipe(SortDirection)) direction: SortDirection) {
  return this.service.sort(direction);
}

---

8. DefaultValuePipe

作用：为未提供的参数设置默认值。
应用场景：
• 分页参数默认值：如未传 page 时默认第一页。

示例：

@Get()
getPaginatedList(
  @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number
) {
  return this.service.paginate(page);
}

---

综合使用建议

• 全局注册：ValidationPipe 通常全局启用，确保所有请求数据通过统一验证。
• 局部使用：其他管道根据需要在特定路由或参数上使用，避免过度转换。
• 组合使用：如 @Query('ids', new ParseArrayPipe({ items: Number })) 将字符串数组转换为数字数组。