管道

揭秘 NestJS 管道 (Pipes)：你应用的数据质检员

想象一个工厂的流水线，原材料（数据）在进入下一个工序（你的业务逻辑）之前，必须经过一个或多个“质检站”。这些质检站有两个核心任务：

1. 检查规格 (Validation)：确保原材料的尺寸、材质、纯度都符合标准。如果不符合，就直接把它丢掉并发出警报。
2. 打磨加工 (Transformation)：有时原材料是合格的，但需要稍微加工一下，比如把一个粗糙的方块打磨成标准的圆形。

在 NestJS 中，管道 (Pipes) 就扮演着这个“质检员”的角色。它是一个在路由处理函数（Controller 里的方法）被调用之前，对传入的参数进行处理的类。

它的主要职责就两个：

• 转换 (Transformation)：将输入数据从一种形式转换为另一种形式（例如，将字符串 "123" 转换为数字 123）。
• 验证 (Validation)：评估输入数据是否有效。如果无效，就抛出一个异常，阻止后续的业务逻辑执行。

1. 为什么我需要管道？告别臃肿的 Controller

看看没有管道的代码会是什么样：

@Controller('cats')
export class CatsController {
  @Get(':id')
  findOne(@Param('id') id: string) {
    // 1. 手动转换类型
    const numericId = parseInt(id, 10);

    // 2. 手动验证
    if (isNaN(numericId)) {
      throw new BadRequestException('ID 必须是一个数字字符串');
    }
    
    // ...真正的业务逻辑...
    console.log(`获取 ID 为 ${numericId} 的猫，类型是：`, typeof numericId); 
    // ...
  }
}

这段代码的问题很明显：Controller 的方法里混杂了大量的参数校验和类型转换逻辑，它不够“纯粹”。Controller 的核心职责应该是协调业务，而不是干这些重复的脏活累活。

而管道，就是为了把这些“脏活累活”抽离出去，让你的 Controller 保持干净。

2. 管道的两种核心用法

NestJS 提供了很多开箱即用的管道，我们先从最常用的两个开始，来理解它的两大核心功能。

用法一：转换 (Transformation) - ParseIntPipe

URL 中的参数，无论你输入的是数字还是字母，传到后端时一律都是字符串。ParseIntPipe 的作用就是将这个字符串转换为整数。

看看使用管道后的代码有多清爽：

import { Controller, Get, Param, ParseIntPipe, BadRequestException } from '@nestjs/common';

@Controller('cats')
export class CatsController {
  @Get(':id')
  // 在参数后面直接使用管道
  findOne(@Param('id', ParseIntPipe) id: number) {
    // 此时，id 已经被 ParseIntPipe 自动转换成了 number 类型！
    // 你不再需要手动 parseInt 和 isNaN 判断。
    console.log(`获取 ID 为 ${id} 的猫，类型是：`, typeof id); // 输出: number
    // ...直接执行你的业务逻辑...
  }
}

发生了什么？

1. 当请求 /cats/123 时，ParseIntPipe 会接收到字符串 "123"。
2. 它内部执行 parseInt("123", 10)，得到数字 123。
3. 它将转换后的数字 123 传递给你的 id 参数。
4. 如果请求的是 /cats/abc，ParseIntPipe 在转换时会失败，并自动抛出一个 BadRequestException，请求立即被中断，根本不会进入 findOne 方法的内部。

用法二：验证 (Validation) - ValidationPipe

这是 NestJS 中最强大、最常用的管道。它通常与 class-validator 和 class-transformer 这两个库结合使用，来自动验证请求体（@Body()）的格式。

前置知识：DTO (Data Transfer Object)

在讲解 ValidationPipe 之前，必须先了解 DTO。DTO 是一个简单的类，它的唯一目的就是定义数据传输的结构和类型。

假设我们有一个创建猫的接口，我们希望传入的 JSON 必须包含一个字符串类型的 name 和一个整数类型的 age。

src/cats/dto/create-cat.dto.ts

// 1. 安装依赖: npm install class-validator class-transformer
import { IsString, IsInt, IsNotEmpty } from 'class-validator';

export class CreateCatDto {
  @IsString({ message: '名字必须是字符串' }) // 使用装饰器定义验证规则
  @IsNotEmpty({ message: '名字不能为空' })
  name: string;

  @IsInt({ message: '年龄必须是整数' })
  age: number;

  @IsString()
  breed: string;
}

现在，我们将 ValidationPipe 应用起来。最常见的方式是将其设置为全局管道。

src/main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ValidationPipe } from '@nestjs/common';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // 将 ValidationPipe 设置为全局管道
  app.useGlobalPipes(new ValidationPipe());

  await app.listen(3000);
}
bootstrap();

然后，在你的 Controller 中使用这个 DTO：

src/cats/cats.controller.ts

@Controller('cats')
export class CatsController {
  @Post()
  create(@Body() createCatDto: CreateCatDto) {
    // 如果代码能执行到这里，说明传入的 body
    // 已经通过了 ValidationPipe 的所有检查！
    // createCatDto 保证是一个符合 CreateCatDto 结构和类型的对象。
    console.log(createCatDto);
    // ...执行创建猫的逻辑...
  }
}

现在会发生什么？

• 发送一个正确的请求: POST /cats，Body 为 {"name": "Mimi", "age": 2, "breed": "Short Hair"}。
  • 请求成功，控制台会打印出这个对象。
• 发送一个错误的请求: POST /cats，Body 为 {"name": "Mimi", "age": "two"}。
  • ValidationPipe 会检测到 age 应该是 IsInt（整数），但收到了字符串 "two"。
  • 它会自动抛出一个 BadRequestException，并返回类似这样的详细错误信息，你的 create 方法甚至都不会被执行！

  {
    "statusCode": 400,
    "message": [
      "年龄必须是整数"
    ],
    "error": "Bad Request"
  }

看到了吗？ValidationPipe 极大地简化了验证逻辑，你只需要在 DTO 中声明规则即可。

3. 创建你自己的管道

当然，你也可以创建自定义管道。一个管道就是一个实现了 PipeTransform 接口的类。

让我们来创建一个简单的自定义管道，它会将所有传入的查询参数值转换为小写。

src/pipes/to-lowercase.pipe.ts

import { PipeTransform, Injectable, ArgumentMetadata } from '@nestjs/common';

@Injectable()
export class ToLowerCasePipe implements PipeTransform {
  transform(value: any, metadata: ArgumentMetadata) {
    // 我们只关心查询参数 (query)
    if (metadata.type === 'query' && typeof value === 'string') {
      return value.toLowerCase();
    }
    return value; // 对于其他情况，原样返回
  }
}

• transform(value, metadata) 是管道的核心方法。
  • value：当前处理的参数值。
  • metadata：元数据对象，包含了参数的上下文信息，比如它是 @Query()、@Body() 还是 @Param() (metadata.type)。

在 Controller 中使用它：

@Get('search')
findByName(@Query('name', ToLowerCasePipe) name: string) {
  // 无论你请求 /search?name=TOM 还是 /search?name=Tom
  // 这里的 name 参数永远是小写的 "tom"
  return `Finding cat with name: ${name}`;
}

4. 如何应用管道（总结）

你有多种方式应用管道，作用范围从小到大：

1. 参数作用域 (Parameter-scoped)：直接在参数装饰器中使用，只对该参数生效。 @Param('id', ParseIntPipe)
2. 处理函数作用域 (Handler-scoped)：使用 @UsePipes() 装饰器，对整个方法的所有参数生效。 @UsePipes(ValidationPipe) @Post()
3. 控制器作用域 (Controller-scoped)：在 Controller 类上使用 @UsePipes()，对该控制器下所有方法生效。 @UsePipes(ValidationPipe) @Controller('cats')
4. 全局作用域 (Global-scoped)：使用 app.useGlobalPipes()，对整个应用生效。这是 ValidationPipe 最常用的方式。

管道 vs. 中间件 vs. 守卫 vs. 过滤器

让我们再次回顾这张对比图，明确管道的位置：

组件	主要职责	执行时机	典型用例
中间件	请求预处理，与框架无关	在路由匹配之前	日志、CORS
守卫	授权 (Authorization)	路由处理函数执行前	检查角色、权限
拦截器	AOP，转换请求/响应	路由处理函数执行前后	格式化响应、缓存
管道 (Pipes)	转换和验证	路由处理函数参数传入前	验证请求体 (DTO)、转换参数类型
过滤器	异常处理	发生未捕获的异常时	格式化错误响应

核心区别：管道是唯一一个专门作用于 Controller 方法参数 的组件。它的工作是在你的业务逻辑拿到这些参数之前，确保它们是“干净”且“正确”的。

总结

管道是 NestJS 框架设计的精髓之一，它遵循了“装饰器优先”和“关注点分离”的原则。

• 它将数据验证和转换的逻辑从你的业务逻辑中彻底剥离。
• ValidationPipe 结合 DTO 是现代后端开发的最佳实践，能极大地提高开发效率和代码健壮性。
• ParseIntPipe 等内置管道能轻松处理常见的数据转换任务。

从现在开始，养成在 Controller 中使用管道的好习惯，你将编写出更优雅、更易于维护的 NestJS 应用。