class-validator 验证的5个开关如何让错误只出现在该出现的地方【免费下载链接】class-validatorDecorator-based property validation for classes.项目地址: https://gitcode.com/gh_mirrors/cl/class-validator更新用户资料的接口有时 avatar 传空整个请求就被打回有时又希望它放行——问题多半不在装饰器而在validate()没传第二个参数。class-validator 的验证行为可以由 ValidatorOptions 里的5个开关定制返回的错误则统一装在ValidationError结构里。读完这篇你能按接口场景自由组合哪些字段要验、验不过返回什么。10秒看懂开关管什么不管什么ValidatorOptions管验证怎么跑装饰器的ValidationOptionsmessage、groups、each管单个字段怎么验两层各管各的类别选项一句话效果跳过缺失值skipUndefinedProperties/skipNullProperties/skipMissingProperties值为 undefined、null 或两者之一时整个字段不参与验证字段白名单whitelist/forbidNonWhitelisted未加装饰器的属性被删除或触发错误错误输出validationError.target/value、stopAtFirstError控制错误里带不带原对象、遇错是否停消息控制dismissDefaultMessages、enableDebugMessages默认消息是否保留、是否打调试警告它不做的类型转换JSON 变类实例要配 class-transformer、跨字段一致性校验需写自定义约束。缺失值怎么处理三个跳过开关class-validator 把undefined字段没赋值和null显式传 null当成两种缺失分别给了开关skipMissingProperties是两者的并集。原理就一行ValidationExecutor在跑任何验证器前先判值命中开关直接return该字段后续验证全部跳过见 ValidationExecutor.ts 的performValidations。注意IsDefined会绕开这三个开关声明此字段必须存在时用它在字段上标而不是靠跳过开关放行。这段代码演示同一份数据在三种开关下的表现class User { IsEmail() email: string; IsNotEmpty() nickname: string; IsUrl() avatar: string; } const user: any new User(); user.email ab.com; user.avatar null; // 显式 null validate(user).then(e console.log(e.map(x x.property))); // [nickname, avatar] validate(user, { skipMissingProperties: true }).then(e console.log(e.map(x x.property))); // 只剩 [nickname]更新接口的典型配法就是skipMissingProperties: true让未传的可选字段安静通过。这里要注意skipMissingProperties: true只挡 null 和 undefined空字符串照样进验证器。whitelist 和 forbidNonWhitelisted外来字段怎么办两个开关控制没加任何装饰器的属性的命运。配置写法{ whitelist: true }实际效果分两支没开forbidNonWhitelisted时这类属性被直接从对象上delete开了则每个属性生成一条constraints里带whitelist的错误消息为property xxx should not exist原对象保持原样。适用场景是防前端多传参数。源码 ValidationExecutor.ts 的whitelist方法会先扫一遍对象所有 key没有对应元数据的进黑名单然后按上面两支处理。这段代码演示两种模式的差异注意验证后draft.hackerField的变化class Post { IsString() title: string; Min(0) rating: number; } const draft: any new Post(); draft.title hi; draft.hackerField extra; await validate(draft, { whitelist: true }); console.log(draft.hackerField); // undefined已被 delete const draft2: any { ...draftRaw }; await validate(draft2, { whitelist: true, forbidNonWhitelisted: true }); // 返回1条错误原对象不被改动这里要注意whitelist是真删字段不是复制一份再删。想保留原始请求用于日志时先Object.assign({}, obj)浅拷贝再验。如果某个字段只是透传、不需要验证给它标Allow()就能留档不必硬塞一个无意义的验证器。把错误说成人话ValidationError 结构验证结果是一个ValidationError[]每个节点就是一棵树的分支property是属性名value是出错时的值constraints是{ 验证器名: 消息 }嵌套对象的错误挂在children数组里递归展开定义见 ValidationError.ts。控制带什么出去用validationError子选项target和value默认为 true生产环境建议设validationError: { target: false }避免整个对象混进错误响应造成 JSON 循环引用。toString()支持4个参数是否加 ANSI 高亮、是否为子错误、父路径、显示约束名还是约束消息。默认输出长这样An instance of Post has failed the validation: - property title has failed the following constraints: isString - property tags[1] has failed the following constraints: length数组下标会被格式化成[1]这种形式方便直接定位元素这在做批量导入校验日志时特别省事。最小可复现一个更新接口够用的配置下面这段只配了一个开关模拟可选字段允许缺省的更新场景import { IsString, Length } from class-validator; import { validate } from class-validator; class Post { IsString() Length(10, 50) title: string; } const post: any new Post(); post.title hello; // 不足10位 validate(post).then(e console.log(e.length)); // 1title 报 length validate(post, { stopAtFirstError: true }).then(e console.log(Object.keys(e[0].constraints)) ); // [isString]同一字段后续约束不再跑为什么这么写错误收集是每字段先建节点全部验证跑完再删空节点stripEmptyErrors所以默认会拿到字段的全部违规stopAtFirstError: true让每个字段只报第一条约束错误前端表单只需要一句提示时正好省掉噪音。记住选项是每次validate()调用生效的全局配置不同接口该传不同的 options 对象别追求一份配置打天下。避坑清单skipMissingProperties没放行空字符串不是 null/undefined仍会进验证器 → 根因是开关只判null value || undefined value→ 解法字段上补IsOptional()处理空值语义或显式把空串归一化成 undefined 再验。验证完发现请求体里多了个字段消失了whitelist: true直接delete原对象上的属性 → 解法先浅拷贝再验证或者改用forbidNonWhitelisted: true让多传字段显式报错而不是静默蒸发。传了groups才生效不传就全过strictGroups未开启时不传groups的验证会忽略所有带组的装饰器表现像规则失效 → 解法按默认行为给所有验证器补无组配置或接口层强制要求groups参数必要时开strictGroups: true反转默认行为。错误列表莫名变短dismissDefaultMessages: true后未写自定义message的约束产出undefined消息整个错误节点被stripEmptyErrors过滤 → 解法要么给装饰器补message要么别开这个开关。validate({})直接失败forbidUnknownValues默认为 true对没有任何装饰器元数据的裸对象会直接报unknownValue错误 → 解法验普通 JSON 对象时显式传forbidUnknownValues: false或先把对象转成带装饰器的类实例。class-validator 只负责判不负责转入参是原始 JSON 时仍需 class-transformer 先转成类实例跨字段一致性逻辑则要落在自定义约束里。想继续深入可以看 whitelist-validation.spec.ts 里白名单三种行为的完整用例以及 ValidationExecutor.ts 中execute主流程如何串联这些开关。【免费下载链接】class-validatorDecorator-based property validation for classes.项目地址: https://gitcode.com/gh_mirrors/cl/class-validator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/11/4 16:12:31 · 阅读 1.2k class-validator 验证的5个开关：如何让错误只出现在该出现的地方
class-validator 验证的5个开关如何让错误只出现在该出现的地方【免费下载链接】class-validatorDecorator-based property validation for classes.项目地址: https://gitcode.com/gh_mirrors/cl/class-validator更新用户资料的接口有时 avatar 传空整个请求就被打回有时又希望它放行——问题多半不在装饰器而在validate()没传第二个参数。class-validator 的验证行为可以由 ValidatorOptions 里的5个开关定制返回的错误则统一装在ValidationError结构里。读完这篇你能按接口场景自由组合哪些字段要验、验不过返回什么。10秒看懂开关管什么不管什么ValidatorOptions管验证怎么跑装饰器的ValidationOptionsmessage、groups、each管单个字段怎么验两层各管各的类别选项一句话效果跳过缺失值skipUndefinedProperties/skipNullProperties/skipMissingProperties值为 undefined、null 或两者之一时整个字段不参与验证字段白名单whitelist/forbidNonWhitelisted未加装饰器的属性被删除或触发错误错误输出validationError.target/value、stopAtFirstError控制错误里带不带原对象、遇错是否停消息控制dismissDefaultMessages、enableDebugMessages默认消息是否保留、是否打调试警告它不做的类型转换JSON 变类实例要配 class-transformer、跨字段一致性校验需写自定义约束。缺失值怎么处理三个跳过开关class-validator 把undefined字段没赋值和null显式传 null当成两种缺失分别给了开关skipMissingProperties是两者的并集。原理就一行ValidationExecutor在跑任何验证器前先判值命中开关直接return该字段后续验证全部跳过见 ValidationExecutor.ts 的performValidations。注意IsDefined会绕开这三个开关声明此字段必须存在时用它在字段上标而不是靠跳过开关放行。这段代码演示同一份数据在三种开关下的表现class User { IsEmail() email: string; IsNotEmpty() nickname: string; IsUrl() avatar: string; } const user: any new User(); user.email ab.com; user.avatar null; // 显式 null validate(user).then(e console.log(e.map(x x.property))); // [nickname, avatar] validate(user, { skipMissingProperties: true }).then(e console.log(e.map(x x.property))); // 只剩 [nickname]更新接口的典型配法就是skipMissingProperties: true让未传的可选字段安静通过。这里要注意skipMissingProperties: true只挡 null 和 undefined空字符串照样进验证器。whitelist 和 forbidNonWhitelisted外来字段怎么办两个开关控制没加任何装饰器的属性的命运。配置写法{ whitelist: true }实际效果分两支没开forbidNonWhitelisted时这类属性被直接从对象上delete开了则每个属性生成一条constraints里带whitelist的错误消息为property xxx should not exist原对象保持原样。适用场景是防前端多传参数。源码 ValidationExecutor.ts 的whitelist方法会先扫一遍对象所有 key没有对应元数据的进黑名单然后按上面两支处理。这段代码演示两种模式的差异注意验证后draft.hackerField的变化class Post { IsString() title: string; Min(0) rating: number; } const draft: any new Post(); draft.title hi; draft.hackerField extra; await validate(draft, { whitelist: true }); console.log(draft.hackerField); // undefined已被 delete const draft2: any { ...draftRaw }; await validate(draft2, { whitelist: true, forbidNonWhitelisted: true }); // 返回1条错误原对象不被改动这里要注意whitelist是真删字段不是复制一份再删。想保留原始请求用于日志时先Object.assign({}, obj)浅拷贝再验。如果某个字段只是透传、不需要验证给它标Allow()就能留档不必硬塞一个无意义的验证器。把错误说成人话ValidationError 结构验证结果是一个ValidationError[]每个节点就是一棵树的分支property是属性名value是出错时的值constraints是{ 验证器名: 消息 }嵌套对象的错误挂在children数组里递归展开定义见 ValidationError.ts。控制带什么出去用validationError子选项target和value默认为 true生产环境建议设validationError: { target: false }避免整个对象混进错误响应造成 JSON 循环引用。toString()支持4个参数是否加 ANSI 高亮、是否为子错误、父路径、显示约束名还是约束消息。默认输出长这样An instance of Post has failed the validation: - property title has failed the following constraints: isString - property tags[1] has failed the following constraints: length数组下标会被格式化成[1]这种形式方便直接定位元素这在做批量导入校验日志时特别省事。最小可复现一个更新接口够用的配置下面这段只配了一个开关模拟可选字段允许缺省的更新场景import { IsString, Length } from class-validator; import { validate } from class-validator; class Post { IsString() Length(10, 50) title: string; } const post: any new Post(); post.title hello; // 不足10位 validate(post).then(e console.log(e.length)); // 1title 报 length validate(post, { stopAtFirstError: true }).then(e console.log(Object.keys(e[0].constraints)) ); // [isString]同一字段后续约束不再跑为什么这么写错误收集是每字段先建节点全部验证跑完再删空节点stripEmptyErrors所以默认会拿到字段的全部违规stopAtFirstError: true让每个字段只报第一条约束错误前端表单只需要一句提示时正好省掉噪音。记住选项是每次validate()调用生效的全局配置不同接口该传不同的 options 对象别追求一份配置打天下。避坑清单skipMissingProperties没放行空字符串不是 null/undefined仍会进验证器 → 根因是开关只判null value || undefined value→ 解法字段上补IsOptional()处理空值语义或显式把空串归一化成 undefined 再验。验证完发现请求体里多了个字段消失了whitelist: true直接delete原对象上的属性 → 解法先浅拷贝再验证或者改用forbidNonWhitelisted: true让多传字段显式报错而不是静默蒸发。传了groups才生效不传就全过strictGroups未开启时不传groups的验证会忽略所有带组的装饰器表现像规则失效 → 解法按默认行为给所有验证器补无组配置或接口层强制要求groups参数必要时开strictGroups: true反转默认行为。错误列表莫名变短dismissDefaultMessages: true后未写自定义message的约束产出undefined消息整个错误节点被stripEmptyErrors过滤 → 解法要么给装饰器补message要么别开这个开关。validate({})直接失败forbidUnknownValues默认为 true对没有任何装饰器元数据的裸对象会直接报unknownValue错误 → 解法验普通 JSON 对象时显式传forbidUnknownValues: false或先把对象转成带装饰器的类实例。class-validator 只负责判不负责转入参是原始 JSON 时仍需 class-transformer 先转成类实例跨字段一致性逻辑则要落在自定义约束里。想继续深入可以看 whitelist-validation.spec.ts 里白名单三种行为的完整用例以及 ValidationExecutor.ts 中execute主流程如何串联这些开关。【免费下载链接】class-validatorDecorator-based property validation for classes.项目地址: https://gitcode.com/gh_mirrors/cl/class-validator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考