NestJS使用DTO作为请求体类型时出现UnprocessableEntityException问题

问题场景 #

我正在开发NestJS用户注册POST接口，代码如下：

Controller实现 #

@Controller('users')
@ApiTags('user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post('register')
  @ApiBody({ type: NewUserInputDto })
  registerUser(@Body() newUserInput: NewUserInputDto) {
    return this.userService.registerUser(newUserInput);
  }
}

DTO定义 #

export class NewUserInputDto {
    @ApiProperty()
    fullName: string;

    @ApiProperty()
    phone: string;

    @ApiProperty()
    email: string;

    @ApiProperty()
    password: string;

    @ApiProperty()
    retypedPassword: string;
}

发送与DTO结构完全匹配的请求时，却返回UnprocessableEntityException，所有字段均触发whitelistValidation错误，提示"property xxx should not exist"：

错误日志 #

[Nest] 47901  - 09/23/2024, 10:49:05 AM   ERROR [HttpExceptionFilter] Object:
[
  {
    "target": {
      "fullName": "string",
      "phone": "string",
      "email": "string",
      "password": "string",
      "retypedPassword": "string"
    },
    "value": "string",
    "property": "fullName",
    "constraints": {
      "whitelistValidation": "property fullName should not exist"
    }
  },
  {
    "target": {
      "fullName": "string",
      "phone": "string",
      "email": "string",
      "password": "string",
      "retypedPassword": "string"
    },
    "value": "string",
    "property": "phone",
    "constraints": {
      "whitelistValidation": "property phone should not exist"
    }
  },
  {
    "target": {
      "fullName": "string",
      "phone": "string",
      "email": "string",
      "password": "string",
      "retypedPassword": "string"
    },
    "value": "string",
    "property": "email",
    "constraints": {
      "whitelistValidation": "property email should not exist"
    }
  },
  {
    "target": {
      "fullName": "string",
      "phone": "string",
      "email": "string",
      "password": "string",
      "retypedPassword": "string"
    },
    "value": "string",
    "property": "password",
    "constraints": {
      "whitelistValidation": "property password should not exist"
    }
  },
  {
    "target": {
      "fullName": "string",
      "phone": "string",
      "email": "string",
      "password": "string",
      "retypedPassword": "string"
    },
    "value": "string",
    "property": "retypedPassword",
    "constraints": {
      "whitelistValidation": "property retypedPassword should not exist"
    }
  }
]

[Nest] 47901  - 09/23/2024, 10:49:05 AM   ERROR [HttpExceptionFilter] property fullName should not exist
UnprocessableEntityException: Unprocessable Entity Exception
    at ValidationPipe.exceptionFactory (/home/long/vegeta/HealthyFoodApplication_BackEnd/src/main.ts:74:16)
    at ValidationPipe.transform (/home/long/vegeta/HealthyFoodApplication_BackEnd/node_modules/@nestjs/common/pipes/validation.pipe.js:72:30)
    at processTicksAndRejections (node:internal/process/task_queues:95:5)
    at resolveParamValue (/home/long/vegeta/HealthyFoodApplication_BackEnd/node_modules/@nestjs/core/router/router-execution-context.js:147:23)
    at async Promise.all (index 0)
    at pipesFn (/home/long/vegeta/HealthyFoodApplication_BackEnd/node_modules/@nestjs/core/router/router-execution-context.js:150:13)
    at /home/long/vegeta/HealthyFoodApplication_BackEnd/node_modules/@nestjs/core/router/router-execution-context.js:37:30
POST /api/v1/users/register 422 115 - 10.342 ms

移除@Body()的类型约束（改为registerUser(@Body() newUserInput)）后接口恢复正常，且其他同类接口无此问题，求排查方向。

可能的原因及解决方案 #

1. ValidationPipe配置缺失关键参数 #

检查main.ts中的全局ValidationPipe配置，若开启了whitelist: true和forbidNonWhitelisted: true，但未启用transform: true，Nest无法将请求体转换为DTO实例，会把所有字段判定为“非白名单字段”。

修正后的配置示例：

app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    transform: true, // 必须开启：自动将请求体转换为DTO实例
    transformOptions: {
      enableImplicitConversion: true,
    },
  }),
);

2. DTO导入或定义异常 #

确认NewUserInputDto的导入路径正确，避免导入了同名的空DTO或字段定义不一致的文件。可以在Controller中添加日志验证：

registerUser(@Body() newUserInput: NewUserInputDto) {
  console.log(newUserInput instanceof NewUserInputDto); // 正常应为true
  return this.userService.registerUser(newUserInput);
}

3. 类验证器装饰器缺失 #

仅使用@ApiProperty不足以让ValidationPipe识别白名单字段，需要配合class-validator的装饰器（如@IsString()、@IsEmail()）标记字段类型：

import { IsString, IsEmail } from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';

export class NewUserInputDto {
    @ApiProperty()
    @IsString()
    fullName: string;

    @ApiProperty()
    @IsString()
    phone: string;

    @ApiProperty()
    @IsEmail()
    email: string;

    @ApiProperty()
    @IsString()
    password: string;

    @ApiProperty()
    @IsString()
    retypedPassword: string;
}

4. Swagger注解冲突 #

尝试移除@ApiBody({ type: NewUserInputDto })，NestJS通常可通过DTO类型自动推断请求体结构，手动配置可能导致元数据冲突。

内容的提问来源于stack exchange，提问作者Long