NestJS 管道绑定方式

管道支持多级别注册，优先级从高到低为：参数级别 > 方法级别 > 控制器级别 > 模块级别 > 全局级别。

参数级别（最细粒度）

直接在参数装饰器后指定管道，仅作用于当前参数

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

方法级别

通过 @UsePipes() 装饰器作用于当前方法的所有参数

@Post()
@UsePipes(PhoneNumberPipe)
create(@Body() createUserDto: CreateUserDto) {}

控制器级别

通过 @UsePipes() 装饰器作用于控制器所有方法的参数

@Controller('users')
@UsePipes(ValidationPipe)
export class UserController {}

模块级别

在模块的 providers 中通过 APP_PIPE 令牌注册，作用于当前模块所有控制器

// src/user/user.module.ts
import { Module, APP_PIPE } from '@nestjs/common';
import { UserController } from './user.controller';
import { UserService } from './user.service';
import { UserExistsPipe } from './pipes/user-exists.pipe';

@Module({
  controllers: [UserController],
  providers: [
    UserService,
    {
      provide: APP_PIPE,
      useClass: UserExistsPipe, // 模块内全局生效
    },
  ],
})
export class UserModule {}

全局级别

1. 方式一：通过 providers 注册（推荐，支持依赖注入）

// app.module.ts
import { Module } from '@nestjs/common';
import { APP_PIPE } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [ConfigModule.forRoot()],
  providers: [
    {
      provide: APP_PIPE,
      useValue: new ValidationPipe({
        whitelist: true,
        forbidNonWhitelisted: true,
        transform: true,
      }),
    },
    // 若自定义管道需要依赖注入，改用 useClass：
    // { provide: APP_PIPE, useClass: CustomValidationPipe },
  ],
})
export class AppModule {}

1. 方式二：通过 NestFactory 注册（不支持依赖注入）

// 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({
      whitelist: true, // 自动过滤 DTO 中未定义的字段
      forbidNonWhitelisted: true, // 存在未定义字段时抛出异常
      transform: true, // 自动将请求数据转换为 DTO 类实例（支持类型转换，如 string → number）
      transformOptions: {
        enableImplicitConversion: true, // 隐式类型转换（如 URL 参数 string 转 number）
      },
    }),
  );

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