express-validator 自定义校验器与净化器(Custom Validators/Sanitizers)实战指南
express-validator 自定义校验器与净化器(Custom Validators/Sanitizers)实战指南
express-validator 通过其底层依赖 validator.js 提供了数量可观的内置校验器(如 isEmail、isInt、isUUID)与净化器(如 trim、escape、toInt),但当业务规则超出通用库的范畴——例如"邮箱是否已被注册"、"两次输入的密码是否一致"、"把 URL 参数转换成 MongoDB ObjectID"——就需要编写自定义校验器与自定义净化器。本文基于 express-validator 官方文档中的自定义校验器/净化器指南(见 feature-custom-validators-sanitizers.md),并结合仓库源码(src/chain、src/context-items、src/base.ts)逐层剖析 .custom() 与 .customSanitizer() 的底层执行机制,帮助你掌握同步/异步校验、自定义错误消息、链式组合等完整实战能力。
为什么需要自定义校验器与净化器
validator.js 覆盖了邮件、URL、UUID、数字、日期、金额等大量通用格式校验,express-validator 把这些函数一一映射为链式方法(可参见 validators-impl.ts 中从 isAbaRouting 到 matches 的完整映射)。但在真实业务中,几乎总会遇到两种内置能力覆盖不到的场景:
- 需要访问请求上下文或数据库的校验:如"邮箱是否已被占用",仅凭字段值本身无法判断,必须查询数据库;
- 需要将字段值转换为业务对象/结构的净化:如把十六进制字符串参数转为 MongoDB 的
ObjectId实例,或把逗号分隔字符串转为数组。
这两种场景正是 .custom()(自定义校验器)与 .customSanitizer()(自定义净化器)的用武之地。
自定义校验器(Custom Validator):.custom()
自定义校验器通过校验链方法 .custom() 实现,它接收一个校验函数。其函数签名定义在 base.ts 中:
export type CustomValidator = (input: any, meta: Meta) => any;
其中 input 是被校验字段的原始值,meta 是包含 req(Express 请求对象)、location(字段来源,如 body/query/params/cookies/headers)、path(字段完整路径,如 foo.bar)以及 pathValues(通配符匹配到的值)的元数据对象(完整定义见 base.ts)。
同步与异步校验的三种失败方式
根据 feature-custom-validators-sanitizers.md 的说明,自定义校验器可以:
- 返回 falsy 值:表示字段校验失败(同步方式);
- 返回 truthy 值:表示校验通过;
- 返回 Promise:表示异步校验,express-validator 会
await该 Promise,Promise 被 resolve 视为通过、被 reject 视为失败; throw任意值(或 reject Promise):触发失败,且该值可用作自定义错误消息(详见下文"自定义错误消息")。
这些规则在 custom-validation.ts 中有精确实现:它先调用 this.validator(value, meta) 拿到结果,再 await 结果以同时兼容同步返回值与 Promise,随后判断 failed = this.negated ? actualResult : !actualResult。也就是说,未取反时返回 falsy、抛异常或 reject 都会记为字段错误;取反(.not())时则相反。
示例:检查邮箱是否已被使用(异步 + 数据库)
原文档给出的经典场景——注册接口校验邮箱唯一性:
const { body } = require('express-validator');
app.post('/user', body('email').custom(value => {
return User.findUserByEmail(value).then(user => {
if (user) {
return Promise.reject('E-mail already in use');
}
});
}), (req, res) => {
// Handle the request
});
要点拆解:
.custom()中的回调返回一个 Promise,express-validator 会等待其完成(在 custom-validation.ts 中通过const actualResult = await result;实现);Promise.reject('E-mail already in use')会让该字段校验失败,同时reject 的字符串值会被直接当作错误消息;- 若未找到用户,Promise 隐式 resolve(回调不返回显式值时 resolve 为
undefined,属于 falsy,但注意这里 Promise 被 resolve 后不会产生错误——源码注释明确说明:"A promise that was resolved only adds an error if negated. Otherwise it always succeeds",见 custom-validation.ts)。
示例:确认密码与密码一致(同步 + 访问 req)
第二个经典场景是校验两个字段之间的关系。此时需要借助 meta.req 访问整个请求体:
const { body } = require('express-validator');
app.post('/user', body('passwordConfirmation').custom((value, { req }) => {
if (value !== req.body.password) {
throw new Error('Password confirmation does not match password');
}
// Indicates the success of this synchronous custom validator
return true;
}), (req, res) => {
// Handle the request
});
要点拆解:
- 解构
{ req }即可拿到 Express 请求对象(meta的结构与字段见 base.ts),从而跨字段比较req.body.password; throw new Error('...')是同步失败的标准写法;当未用.withMessage()指定消息时,源码会取err instanceof Error ? err.message : err作为错误消息(见 custom-validation.ts),所以这里抛出的Error实例的message会被原样展示;- 显式
return true表示校验通过,这也是官方推荐的写法,避免依赖隐式undefined。
结合源码看 .custom() 的实现路径
从源码结构可以梳理出完整调用链:
.custom(validator)在 validators-impl.ts 中执行this.addItem(new CustomValidation(validator, this.negateNext)),把自定义校验器包装成CustomValidation这个 context item 加入上下文构建器,同时this.negateNext = false重置取反标记;- 运行时,custom-validation.ts 的
run()被调用,完成"调用 → await → 判失败 → 写错误"的全流程; - 失败时通过
context.addError({ type: 'field', message, value, meta })写入字段错误,最终由validationResult()统一呈现。
这也解释了为什么 .custom() 返回的是当前链实例:addItem 中 return this.chain(见 validators-impl.ts),因此可以继续 .withMessage()、.not() 或追加更多校验器。相关的取反(negated)与错误消息行为,均有对应测试用例覆盖,见 custom-validation.spec.ts(如"validator throws → add error with thrown message"、"promise rejects → add error with rejection message"、"negated 时抛异常不报错"等)。
自定义错误消息的优先级
原文档指出,抛出的任意值/reject 的 Promise 可用于携带自定义错误消息。更完整的规则是:
- 若链上使用了
.withMessage(message)(在 validators-impl.ts 中通过this.lastValidator.message = message写入),则该消息优先于抛出的值; - 未设置
.withMessage()时,throw 的Error实例取err.message,reject 的非 Error 值则原样作为消息(如'E-mail already in use'); - 内置校验器的自定义错误消息机制可进一步参考 feature-error-messages.md。
自定义净化器(Custom Sanitizer):.customSanitizer()
自定义净化器通过 .customSanitizer() 实现,它在校验链(Validation Chain)与净化链(Sanitization Chain)上均可使用(后者见 api-sanitization-chain.md)。函数签名同样定义在 base.ts 中:
export type CustomSanitizer = (input: any, meta: Meta) => any;
与校验器的重要区别在于:净化器必须返回处理后的新值,且原文档明确说明"目前必须是同步的"("which must be synchronous at the moment")。
从源码看,sanitizers-impl.ts 中 customSanitizer() 将函数包装为 new Sanitization(sanitizer, true)(第二个参数 true 标记其为自定义净化器,与标准净化器走不同的执行分支)。在 sanitization.ts 的 run() 中:
const runCustomSanitizer = async () => {
const sanitizerValue = this.sanitizer(value, meta);
return Promise.resolve(sanitizerValue);
};
即自定义净化器分支不经过字符串化(stringify)预处理,直接接收原始值 value,并把返回值通过 context.setData(path, newValue, location) 写回请求对象——这正是"净化"的含义:下游代码(后续校验器、路由处理器)拿到的都是净化后的值。
示例:转换为 MongoDB 的 ObjectID
原文档给出的例子——把路径参数 :id 转换为 ObjectId:
const { sanitizeParam } = require('express-validator');
app.post('/object/:id', sanitizeParam('id').customSanitizer(value => {
return ObjectId(value);
}), (req, res) => {
// Handle the request
});
要点拆解:
sanitizeParam('id')建立一条针对req.params.id的净化链;- 自定义净化器把字符串值交给
ObjectId(value)转换,返回值被写回req.params.id,因此后续路由处理器中req.params.id直接就是ObjectId实例,无需再手动转换; - 在净化链中
.customSanitizer()同样返回当前链实例,可继续链式调用其他净化器(如sanitizeParam('email').normalizeEmail().customSanitizer(...))。
自定义净化器与内置净化器的差异
- 自定义净化器(
custom: true分支):直接拿原始值,返回值原样写回,不强制字符串化; - 标准净化器(
custom: false分支):对非数组值先stringify,对数组值逐元素处理后再写回(见 sanitization.ts)。
换句话说,自定义净化器拿到的是"真·原始值"(可能是数字、对象、null 等),这对处理 ObjectId、对象结构转换等场景至关重要;相关行为测试见 sanitization.spec.ts("persists sanitized value back into the context"、"calls it with the value of an async function and the meta" 等用例,其中也验证了其返回值会被持久化回 context)。
注:虽然
Sanitization.run用Promise.resolve(...)兼容异步返回值(测试也覆盖了 async 净化器),但官方文档当前版本仍建议自定义净化器保持同步,编写时请以"必须同步"为前提,避免依赖异步行为。
校验链中的组合实战
自定义校验器/净化器最大的价值在于与内置方法自由组合,形成完整的字段处理管线。以 api-validation-chain.md 中的创建用户示例为参照:
app.post('/create-user', [
check('password').exists(),
check('passwordConfirmation', 'passwordConfirmation field must have the same value as the password field')
.exists()
.custom((value, { req }) => value === req.body.password),
], loginHandler);
再结合条件校验 .if()(定义见 api-validation-chain.md),自定义校验器可与条件逻辑叠加:
body('oldPassword')
// 仅当提供了新密码时才继续校验旧密码
.if((value, { req }) => req.body.newPassword)
.not().empty()
.custom((value, { req }) => value !== req.body.newPassword)
与净化器同理,一个典型的"先净化后校验"管线可以是:
body('email')
.normalizeEmail() // 内置净化:归一化邮箱
.isEmail() // 内置校验
.custom(async value => { // 自定义异步校验:查库
const user = await User.findUserByEmail(value);
if (user) {
throw new Error('E-mail already in use');
}
});
实践建议与注意事项
- 异步校验务必返回 Promise / 使用 async 函数:
Promise.reject(...)或throw都能中断并标记失败;resolve 的值只要不是显式失败语义,即视为通过; - 跨字段校验依赖
meta.req:不要依赖闭包中的旧请求对象,始终从{ req }中读取最新字段值; - 自定义净化器必须返回新值:返回值会被写回请求对象,忘记 return 会把字段净化成
undefined; - 错误消息设计:优先用
.withMessage()固定面向用户的文案;当需要把数据库中的业务错误原样透出时,再依赖 throw/reject 的值(见 feature-error-messages.md 的自定义校验器层级说明); - 取反语义:
.custom()前使用.not()会反转通过/失败判定,使用时注意测试 custom-validation.spec.ts 中 negated 场景的行为边界; - 适用于所有字段来源:
.custom()/.customSanitizer()不限于body,同样可用于query、params、cookies、headers构建的链(如sanitizeParam('id'))。
小结
自定义校验器(.custom())与自定义净化器(.customSanitizer())是 express-validator 从"通用格式检查工具"升级为"业务校验引擎"的关键扩展点:前者支持同步 falsy/throw 与异步 Promise 三种失败语义、可通过 meta 访问整个请求上下文;后者将任意转换函数写回请求字段。结合 validators-impl.ts、sanitizers-impl.ts、custom-validation.ts 与 sanitization.ts 的源码实现,你可以精确理解每一步的判定与写回逻辑,从而放心地把数据库查询、对象转换等真实业务规则交给校验链。