大家好 👋，我是 Moment。Zui近我正忙着捣鼓我的新项目 DocFlow，这是一个基于 Next.js 和 NestJS 的 AI 协同文档平台。在开发过程中，除了折腾 Tiptap 编辑器的深度定制和 LangChain 的智Neng流外我感触Zui深的就是后端的数据治理了。今天咱们不聊虚的，专门来扒一扒 NestJS 里那个让无数又爱又恨的话题：DTO和数据校验。

说实话，hen多刚接触 NestJS 的朋友，容易把 TypeScript 的类型系统当成安全网。但咱们得清醒一点：TS 的类型检查是在编译时一旦代码跑起来到了运行时那就是赤裸裸的 JavaScript 世界，什么类型约束dou荡然无存。这时候，Ru果有人给你发了个请求，字段类型乱七八糟，或者塞了一些你根本没预料到的键，你的服务层要是直接照单全收，那离崩溃也就不远了。

为什么我们需要 DTO？它不只是个类型标注

在实际的项目开发中，Ru果你直接把请求体往业务逻辑里扔，那简直就是给自己埋雷。请求来自外部，外部输入绝对不Neng默认可信：字段可Neng缺失、类型可Neng串了、字符串里可Neng塞了根本转不成数字的内容，甚至还可Neng多带几个你从未在文档里写过的键。

这时候，DTO 的价值就体现出来了。它不仅仅是为了让编辑器不报错，它是你接口的“契约”，是守在门口的保安。它定义了“合法的请求长什么样”。只要不符合这个形状的，直接在进门时拦下根本别想进到控制器里去捣乱。

这里有个hen关键的概念要区分开：DTO、Entity 和 VO。虽然它们kan起来dou像是一堆字段的集合，但站位完全不同：

DTO 站在门口，负责接收和过滤外部输入。比如创建用户时的 CreateUserDto，它只关心 nameemail 和 password。

Entity站在数据库和领域层，比如 UserEntity，里面可Neng有 idpasswordHashcreatedAt 等持久化相关的字段。

VO 站在出口，负责告诉前端什么Nengkan、什么不Nengkan。比如 UserProfileVo，可Neng只包含 idname，绝对不Neng包含密码哈希。

Ru果你为了省事，把 Entity 直接当 DTO 用，或者把带密码的 Entity 原样返回给前端，那后果不堪设想。这种混用会导致入参与存储绑死、内部字段意外暴露，甚至为了兼容各种场景，一个类会不断长歪，Zui后变成谁dou不敢动的“上帝类”。

第一步：装备你的武器库

在 NestJS 里要玩转校验，通常离不开两员大将：class-validator 和 class-transformer。前者负责问“对不对”，后者负责问“怎么变成声明里的那种形状”。

还没装依赖的，赶紧在项目根目录执行：

pnpm add class-validator class-transformer

装好后我们就Ke以开始定义契约了。下面是一个Zui基础的入参契约，字段上的装饰器来自 class-validator

import { IsEmail, IsInt, IsString, Min, MinLength } from "class-validator";
/**
 * 创建用户接口允许的请求体形状
 * 这个类既不是表结构，也不是领域实体，它只是说：
 * 创建用户这条接口，合法请求体至少长这样。
 */
export class CreateUserDto {
  @IsString
  @MinLength
  name: string;
  @IsEmail
  email: string;
  @IsInt
  @Min
  age: number;
}

第二步：启用 ValidationPipe，让契约生效

光定义了 DTO 类还不够，请求进来时并不会自动校验。真正把契约接进管道的是 ValidationPipe。Zui常见的Zuo法是在 main.ts 里全局挂上管道：

import { ValidationPipe } from "@nestjs/common";
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";
async function bootstrap: Promise {
  const app = await NestFactory.create;
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,       // 剥离未定义的属性
      forbidNonWhitelisted: true, // 遇到未定义属性直接报错
      transform: true,       // 自动尝试类型转换
    }),
  );
  await app.listen;
}
void bootstrap;

这个配置非常关键，咱们拆开来kan。

whitelist 与 forbidNonWhitelisted

whitelist: true 意味着“白名单模式”。只有 DTO 类里声明过的属性会被保留，多出来的键会被静默剥离。而 forbidNonWhitelisted: true 则是geng严厉的版本：只要出现未声明的字段，直接判失败，抛出错误，而不是悄悄删掉。

为什么要这么干？想象一下Ru果你的 DTO 只有 name 和 email，客户端却恶意带了 role: "admin" 或 isAdmin: true。Ru果没有白名单机制，这些多余字段可Neng会混进你的后续逻辑，甚至被存进数据库，造成巨大的安全漏洞。hen多风险其实来自“多传了不该收的字段”，而不只是字段值写错。

transform：自动类型转换的魔法

transform: true 会启用 class-transformer，把原始负载转成 DTO 类的实例，并按装饰器Zuo类型转换。这Neng省去你大量的手动类型转换代码。

比如查询串里的 ?page=1，在 HTTP 层面它其实是字符串 "1"。Ru果不开启转换，你在业务代码里拿到的就是字符串，Zuo加减法可Neng会出 bug。开启 transform 后NestJS 会尝试把它变成数字。Ru果配合 transformOptions.enableImplicitConversion，效果geng好。

第三步：实战中的常见坑与解决方案

配置好了咱们来kankan实际写代码时遇到的那些“坑”。

查询参数的数字陷阱

查询参数特别需要 @Type 装饰器。因为从 HTTP 进应用时查询串几乎dou是字符串。你kankan下面这个例子：

import { Type } from "class-transformer";
import { IsInt, IsOptional, IsString, Min } from "class-validator";
/** 用户列表查询：关键词可选，页码可选且至少为 1 */
export class QueryUsersDto {
  @IsOptional
  @IsString
  keyword?: string;
  @IsOptional
  @Type => Number) // 必须加这个！
  @IsInt
  @Min
  page?: number;
}

Ru果不加 @Type => Number)，@IsInt hen容易和你的直觉拧着来因为校验器拿到的是空字符串或者字符串数字。有了 @Type，page=1 就Neng顺滑地变成数字 1，避免整份业务代码里到处是手动的 Number 或 parseInt。

嵌套对象的校验

请求体里常有嵌套结构，比如创建订单时包含地址信息。外层 DTO 校验到了内层Ru果只是个普通对象，规则是不会自动往下传的。

这时候你需要用 @ValidateNested 配合 @Type => InnerDto)

import { Type } from "class-transformer";
import { IsArray, IsString, MinLength, ValidateNested } from "class-validator";
export class AddressDto {
  @IsString
  @MinLength
  city: string;
}
export class CreateOrderDto {
  @ValidateNested
  @Type => AddressDto)
  address: AddressDto;
  @IsArray
  @IsString
  tags: string;
}

嵌套越深，越要在类型和装饰器上写清楚，否则hen容易出现“外层过了、内层仍是任意 JSON”的假象，脏数据一旦进了服务层或持久层，再排查就要沿着整条调用链往回找，成本高得吓人。

复用 DTO：别再复制粘贴了

geng新接口常常和创建接口只差“全部可选”。手写两份几乎相同的类容易漂移，维护起来简直是噩梦。这时候Ke以用 @nestjs/mapped-types 包里的工具。

先安装：

pnpm add @nestjs/mapped-types

然后这样写：

import { PartialType } from "@nestjs/mapped-types";
import { CreateUserDto } from "./create-user.dto";
/**
 * geng新用户：字段与创建一致，但均可选
 * 装饰器会一并变成可选校验
 */
export class UpdateUserDto extends PartialType {}

除了 PartialType，还有 PickType和 OmitType。思路dou是：一份源契约，多份视图，而不是复制粘贴改几个字母。

第四步：控制器的Zui终形态

当你Zuo好了这一切，你的控制器就会变得异常清爽。kankan下面这个 users.controller.ts

import { Body, Controller, Post } from "@nestjs/common";
import { CreateUserDto } from "./dto/create-user.dto";
@Controller
export class UsersController {
  @Post
  create body: CreateUserDto): CreateUserDto {
    // Neng执行到这里时body Yi通过校验并按 DTO Zuo过转换
    // 你Ke以放心地使用 body，不用再判断字段是否存在或类型是否正确
    return body;
  }
}

Ru果不满足 CreateUserDto 的规则，create 方法根本不会执行。客户端会先收到一个 400 Bad Request 的错误，响应体里会详细列出哪条规则没通过。服务层就Ke以少写一层重复的“字段是不是 string”式的防御代码，专注于核心业务逻辑。

当然Ru果某个路由要临时关掉转换或换一套规则，Ke以用控制器级或方法级管道覆盖默认行为，不必动全局配置：

import { UsePipes, ValidationPipe } from "@nestjs/common";
// ...
  @Post
  @UsePipes(
    new ValidationPipe({
      whitelist: true,
      transform: true,
      forbidNonWhitelisted: false, // 临时放宽一点
    }),
  )
  saveDraft body: CreateUserDto): CreateUserDto {
    return body;
  }

建立你的防御思维

这一篇想建立的，不局限于“会贴几个校验装饰器”，而是一种防御思维。把 DTO 想成控制器前的一道闸：参数先按 DTO 规则过一遍，过了才进方法体，不过则直接短路成错误响应。

参数并不是原样流进控制器，而是先被整理成契约允许的形状。收益不只是少报错，而是入口这一圈边界可控、可测、可讲清楚。

若下面这些Yi经变成你的默认思路，这一章就到位了：

接口参数不Neng默认可信，必须经过 DTO 审查。

DTO、Entity、VO 各司其职，绝不混用。

善用 ValidationPipe 的全局配置，把脏数据挡在门外。

利用 class-transformer 减少手动类型转换的样板代码。

用 PartialType 等工具避免重复定义。

在这个项目的持续打磨过程中，我积累了不少实战经验，不只是 Tiptap 的深度定制、编辑器性Neng优化和协同方案设计，也包括前端工程化建设、React 源码理解以及复杂项目架构实践。Ru果你对 AI 全栈开发、Agent、长期记忆、文档编辑器、前端工程化或者 React 源码相关内容感兴趣，欢迎添加我的微信 yunmz777 一起交流。觉得项目还不错的话，也欢迎给 DocFlow 点个 star ⭐。

下一节，咱们会kankan配置与环境变量。除了 HTTP 负载，运行时的开关和密钥同样需要被约束和管理，咱们下回见！

---