express-validator 自定义校验器与自定义清洗器(Custom Validators/Sanitizers)完整指南
express-validator 自定义校验器与自定义清洗器(Custom Validators/Sanitizers)完整指南
express-validator 通过底层依赖 validator.js 提供了大量开箱即用的校验器(Validator)与清洗器(Sanitizer),但真实业务中总会有内置规则覆盖不到的校验逻辑,例如"邮箱是否已被注册""两次密码输入是否一致""将参数转换为 MongoDB ObjectID"等。本指南基于仓库 website/versioned_docs/version-6.8.0/feature-custom-validators-sanitizers.md 文档,结合源码与测试,系统讲解如何用 .custom() 编写同步/异步自定义校验器、用 .customSanitizer() 编写自定义清洗器,并深入解析其底层执行原理与错误处理细节,读完即可在项目中落地可复用的自定义校验/清洗逻辑。
为什么需要自定义校验器与清洗器
虽然 express-validator 通过其底层依赖 validator.js 中内置了 isEmail、isInt、isURL、isUUID 等数十个标准校验器,清洗链接口 Sanitizers 内置了 trim、escape、toInt、normalizeEmail 等标准清洗器,但涉及业务规则(如查询数据库、比较多个字段、类型转换)时,就必须编写自定义校验器或自定义清洗器。
自定义校验器通过链方法 .custom() 实现,它接收一个校验器函数;自定义清洗器则通过 .customSanitizer() 实现,无论在校验链上还是清洗链上均可使用。
自定义校验器(Custom Validator)
基本用法与函数签名
在 Validators 接口 中,.custom() 的签名是:
custom(validator: CustomValidator): Return;
其中 CustomValidator 的类型定义位于 src/base.ts:
export type CustomValidator = (input: any, meta: Meta) => any;
即校验器函数接收两个参数:
input:被校验字段的值;meta:关于被校验字段的元数据,包含req(Express 请求对象)、location(字段来源,取值为body、cookies、headers、params或query)、path(字段在请求对象中的完整路径)、pathValues(使用通配符选择字段时匹配到的值)。
提示:在 v6 版本中,通过
body('products.*.price').custom(...)这类通配符选择字段时,可以在meta.pathValues<a href="https://link.gitcode.com/i/3be18dc07570c18027682976ac506075" target="_blank">0]中拿到对应的数组索引,详见 [src/base.ts 中的注释示例。
同步校验器:返回值语义
校验器函数可以有三种"判定结果"表达方式:
- 返回 falsy 值(如
false、undefined、null、0、'')表示字段无效; - 返回 truthy 值(如
true)表示字段有效; throw抛出任意值,表示字段无效,且被抛出的值会作为错误消息。
从源码实现 src/context-items/custom-validation.ts 可以看到,CustomValidation.run() 会执行校验器函数,随后 const failed = this.negated ? actualResult : !actualResult; 即对返回值做布尔判定;若返回 falsy 则通过 context.addError() 记录一条 type: 'field' 的错误。
异步校验器:Promise 语义
自定义校验器可以返回 Promise 来表示异步校验,express-validator 会等待该 Promise 完成(await result)。异步校验的语义与同步相反,需要特别注意:
注意:如果自定义校验器返回一个 Promise,它必须 reject 才能表示字段无效;resolve 则无论返回值是什么,字段都被视为有效。
这一约定在源码中有明确体现(src/context-items/custom-validation.ts):代码通过 result?.then 判断校验器是否返回了 Promise,对于 Promise 情况,只有 reject 才会进入 context.addError() 分支;同时 catch (err) 会把 reject 的值或抛出的 Error 捕获为错误消息。
对应测试 src/context-items/custom-validation.spec.ts 验证了这些行为:
- 校验器
throw new Error('boom')→ 错误消息为'boom'; - 校验器返回 reject 的 Promise(
mockRejectedValue('a bomb'))→ 错误消息为'a bomb'; - 校验器返回 resolve 的 Promise → 不产生错误。
示例一:检查邮箱是否已被注册(异步)
原文档给出的经典异步场景——注册时校验邮箱唯一性:
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
});
这里 User.findUserByEmail(value) 返回一个 Promise;当查找到已存在的用户时,通过 Promise.reject('E-mail already in use') 使校验失败,并且 reject 的值 'E-mail already in use' 会直接成为该字段的错误消息。若没有查到用户,Promise 以 undefined resolve,字段判定为有效。
示例二:检查密码确认是否与密码一致(同步)
另一个常见场景是校验两个字段的一致性,此时可以借助 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 } 拿到 meta 中的 Express 请求对象,进而读取 req.body.password 与当前字段值比对。不一致时抛出 Error,其 .message 会被用作错误消息;一致时显式 return true 表示校验通过。
错误消息的优先级与覆盖
关于自定义校验器的错误消息,需要理解两个层次:
- 自定义校验器层级:当校验器
throw或 reject 时,错误消息默认等于被抛出/reject 的值,这与 自定义错误消息文档 中"Custom Validator Level"的描述一致; .withMessage()覆盖:可以用.withMessage(message)为前一个校验器指定固定消息,它将优先于自定义校验器抛出/reject 的消息。从实现看,ValidatorsImpl.withMessage()直接为lastValidator.message赋值,而CustomValidation在捕获到错误后使用this.message || (err instanceof Error ? err.message : err)作为最终消息(见 src/context-items/custom-validation.ts)。
const { check } = require('express-validator');
app.post('/user', [
check('email')
.custom(value => User.findByEmail(value).then(user => {
if (user) return Promise.reject('E-mail already in use');
}))
.withMessage('This e-mail address is already registered'),
]);
与 .not() 的配合
自定义校验器同样支持链式取反:.not().custom(...) 会将下一个校验器的结果取反。从 ValidatorsImpl.custom() 可见,custom() 通过 new CustomValidation(validator, this.negateNext) 把取反状态传给校验项,negateNext 由 .not() 置位并在 addItem 后自动重置(src/chain/validators-impl.ts#L24-L27)。CustomValidation 中 this.negated ? actualResult : !actualResult 以及对应的取反分支测试(src/context-items/custom-validation.spec.ts#L119-L158)都证明了这一点。
自定义清洗器(Custom Sanitizer)
基本用法与函数签名
自定义清洗器通过 .customSanitizer() 方法实现,无论在校验链(Validation Chain)还是清洗链(Sanitization Chain)上都可以调用。其类型定义见 src/base.ts:
export type CustomSanitizer = (input: any, meta: Meta) => any;
与校验器不同,清洗器接收字段值 input 和元数据 meta,返回清洗后的新值;当前版本中清洗器函数必须是同步的。这一点在源码实现 src/context-items/sanitization.ts 中可以看到:自定义清洗器虽然以 await 方式调用(Promise.resolve(sanitizerValue) 只是为了统一异步接口),但清洗器本身是同步执行的,不支持真正的异步清洗逻辑。
清洗器执行完毕后,通过 context.setData(path, newValue, location) 把新值写回请求对象;而 ContextRunnerImpl.run() 在清洗器返回后会通过 _.set(req[location], path, newValue) 将清洗结果同步回 req(除非以 dryRun 模式运行),因此后续的校验器会基于清洗后的值继续执行——这也正是"先清洗、后校验"链式写法的数据流基础。
示例:转换为 MongoDB 的 ObjectID
原文档的示例是将路径参数转换为 MongoDB 的 ObjectID:
const { param } = require('express-validator');
app.post('/object/:id', param('id').customSanitizer(value => {
return ObjectId(value);
}), (req, res) => {
// Handle the request
});
执行后,req.params.id 会被替换为 ObjectId(value) 的结果,后续中间件和路由处理函数拿到的便是转换后的对象。实际项目中 ObjectId 通常来自 mongoose.Types.ObjectId,同样可以在此处做类型转换。
自定义清洗器与内置清洗器的实现差异
从 SanitizersImpl 的实现可以看出两类清洗器的差异:
- 自定义清洗器(src/chain/sanitizers-impl.ts#L13-L16):
new Sanitization(sanitizer, true),custom标志为true,清洗结果直接替换原值,不做字符串化; - 标准清洗器(如
trim、escape):new Sanitization(sanitizer, false, options),值会被先转为字符串再传给 validator.js 的清洗函数。
在 Sanitization.run() 中,custom 分支直接使用 sanitizer(value, meta) 的返回值替换字段值;而标准清洗分支则对每个值执行 sanitizer(stringify(value), ...options)。
有趣的是,仓库中 default()、replace()、toLowerCase()、toUpperCase() 等内置清洗器本质上都是基于 customSanitizer() 实现的(见 src/chain/sanitizers-impl.ts#L17-L29),例如:
default(default_value: any) {
return this.customSanitizer(value =>
[undefined, null, NaN, ''].includes(value) ? _.cloneDeep(default_value) : value,
);
}
这说明 customSanitizer 是表达"任意值变换逻辑"的最底层原语,你可以用同样的方式实现自己的业务清洗规则。
执行顺序:清洗与校验如何串联
自定义清洗器与自定义校验器都可以附加在同一个链上,链内所有项目(Context Item)按添加顺序依次执行。从 ContextRunnerImpl.run() 可以看到,每个上下文项 contextItem.run(...) 会依次作用于每个被选中的字段实例,且每个实例是可变的——如果某个清洗器改变了字段值,后续校验器读取到的就是清洗后的新值。
因此,下面这种"先清洗、后校验"的写法是成立且推荐的:
const { body } = require('express-validator');
app.post('/user', [
// 先清洗:去掉首尾空格并转小写
body('email').trim().toLowerCase(),
// 后校验:基于清洗后的值校验邮箱格式,并做唯一性业务校验
body('email')
.isEmail()
.custom(value => User.findUserByEmail(value).then(user => {
if (user) return Promise.reject('E-mail already in use');
})),
], (req, res) => {
// Handle the request
});
最佳实践与常见注意事项
- 异步校验务必 reject:返回 Promise 的自定义校验器,只有 reject 才代表校验失败;resolve 一律视为通过,哪怕 resolve 的是
false。 - 不要"吞掉"错误:不要在自定义校验器内部
catch后不处理,否则异步校验会静默通过;需要业务错误信息时,直接throw或Promise.reject一个可读消息即可。 - 清洗器保持同步:当前版本
customSanitizer只支持同步函数,涉及数据库查询等异步逻辑应放在.custom()校验器中,而不是清洗器中。 - 链式顺序即执行顺序:链是可变对象,每调用一个方法就为同一个链追加行为;若需要复用基础链,建议用工厂函数返回新链(参考 Validation Chain API 的注意事项)。
- 配合
.bail()防止无效调用:当自定义校验器涉及数据库或外部 API 调用时,可先用.bail()让前面的校验失败后不再执行后续校验,避免已知会失败时仍发起昂贵调用。 - 利用
meta访问上下文:meta中的req、location、path和pathValues可以支撑跨字段校验、按请求上下文条件化校验、通配符字段校验等高级场景。 - 错误消息定制:可用
.withMessage()覆盖自定义校验器抛出/reject 的消息,也可结合字段级消息与动态消息函数实现 i18n 或模板化错误提示。
总结
自定义校验器与自定义清洗器是 express-validator 扩展业务校验能力的两个核心入口:
.custom(validator)支持同步(返回 falsy / throw)与异步(Promise reject)两种判定方式,配合meta元数据可实现跨字段、依赖请求上下文的复杂业务校验;.customSanitizer(sanitizer)用同步函数完成任意值变换,结果会写回请求对象并影响后续校验器,底层由 Sanitization 统一执行并回写请求;- 两者的类型定义集中在 src/base.ts,实现位于 CustomValidation 与 Sanitization,测试用例见 custom-validation.spec.ts,可作为深入理解其行为边界的权威参考。
掌握了这两个方法,再结合内置的数十个标准校验器/清洗器,你几乎可以为任何业务字段定义精确、可复用、可测试的校验与清洗规则。