express-validator 自定义错误消息完全指南:Validator 级、字段级与动态消息的优先级与实战
express-validator 自定义错误消息完全指南:Validator 级、字段级与动态消息的优先级与实战
express-validator 是 Express 生态中最流行的 validator.js 中间件封装,其默认错误消息统一为 Invalid value。本文基于仓库 website/versioned_docs/version-6.5.0/feature-error-messages.md 展开,系统讲解自定义错误消息的三个层级(Validator 级、Custom Validator 级、字段级)的写法、回退优先级,以及用于 i18n 国际化场景的函数式动态消息,并辅以 src/context.ts、src/chain/validators-impl.ts 等源码实现作为佐证。读完本文,你将能在任何校验链上精确控制每个字段、每个校验器的报错文案,并理解其底层消息解析机制。
默认错误消息:Invalid value
express-validator 在不做任何定制时,所有校验失败都会生成统一的 Invalid value 消息。这样设计的好处是:对全部字段一视同仁、不掺入任何主观意见,同时保持库的轻量。该默认值并非散落在文档里,而是硬编码在源码中——src/context.ts 的 addError() 方法遵循如下取值逻辑:
const msg = opts.message || this.message || 'Invalid value';
即:校验项自身消息 > 上下文(字段级)消息 > 默认 Invalid value。测试用例也验证了这一点,例如 src/context.spec.ts 中断言未指定消息时 msg 就是 'Invalid value'。
而当你想要有意义、可读、能直接展示给用户的错误消息时,express-validator 提供了以下三种层级以及动态消息能力。
错误消息的三个设置层级
Validator 级:.withMessage()
当你想对单个校验器实施最细粒度的控制时,使用校验链上的 .withMessage() 方法。它只作用于紧挨着它前面的那一个校验器,因此可以在同一条链上为不同校验器分别设置文案:
const { check } = require('express-validator');
app.post('/user', [
// ...some other validations...
check('password')
.isLength({ min: 5 }).withMessage('must be at least 5 chars long')
.matches(/\d/).withMessage('must contain a number')
], (req, res) => {
// Handle the request somehow
});
在上面的例子中:
- 如果密码长度不足 5 个字符,将报告错误消息
must be at least 5 chars long; - 如果密码同时不包含数字,还会报告另一个错误
must contain a number。
两个校验器各自独立、互不干扰,这是 Validator 级消息最典型的应用场景。从源码看,src/chain/validators-impl.ts 中 .withMessage(message) 的实现就是简单地把消息挂到 lastValidator.message 上:
withMessage(message: FieldMessageFactory | ErrorMessage) {
this.lastValidator.message = message;
return this.chain;
}
该校验器在运行时(如 src/context-items/standard-validation.ts)会把 this.message 传入 context.addError(),从而覆盖上下文级消息与默认消息。
Custom Validator 级:throw 或 reject 的内容即消息
当使用 .custom() 编写自定义校验器时,你可以通过抛异常或拒绝 Promise 来表达"值无效"。此时,错误消息就等于自定义校验器抛出/拒绝的内容:
const { check } = require('express-validator');
app.post('/user', [
check('email').custom(value => {
return User.findByEmail(value).then(user => {
if (user) {
return Promise.reject('E-mail already in use');
}
});
}),
check('password').custom((value, { req }) => {
if (value !== req.body.passwordConfirmation) {
throw new Error('Password confirmation is incorrect');
}
})
], (req, res) => {
// Handle the request somehow
});
这里有两个细节值得注意:
Promise.reject('E-mail already in use')拒绝了一个字符串,该字符串直接成为错误消息;throw new Error('Password confirmation is incorrect')抛出的是Error实例,此时消息取Error.prototype.message,即Password confirmation is incorrect。
这正是 src/context-items/custom-validation.ts 中 catch 分支的逻辑:
} catch (err) {
if (this.negated) {
return;
}
context.addError({
type: 'field',
message: this.message || (err instanceof Error ? err.message : err),
value,
meta,
});
}
即消息优先级为:.withMessage() 设置的消息 > 抛出的 Error 的 .message > 抛出的非 Error 值本身。若你在自定义校验器上又调用了 .withMessage(),则 .withMessage() 的文案会覆盖 throw/reject 的内容——这与 api-validation-chain.md 中".withMessage() 对自定义校验器抛出的错误具有优先级"的说明一致。
字段级:校验中间件的第二个参数
消息还可以通过校验中间件的第二个参数在字段级别设置,例如 check(field, message)、body(field, message) 等。字段级消息是回退消息(fallback):当链上的某个校验器没有为自己指定消息时,才使用它。参见 check 的 API 文档。
const { check } = require('express-validator');
app.post('/user', [
// ...some other validations...
check('password', 'The password must be 5+ chars long and contain a number')
.not().isIn(['123', 'password', 'god']).withMessage('Do not use a common word as the password')
.isLength({ min: 5 })
.matches(/\d/)
], (req, res) => {
// Handle the request somehow
});
上面的例子中:
- 当
password长度小于 5 或不含数字时,由于isLength、matches都没有自己的消息,将回退到字段级消息The password must be 5+ chars long and contain a number; - 但当密码命中了
isIn(['123', 'password', 'god'])的黑名单时,因为该校验器通过.withMessage('Do not use a common word as the password')指定了自身消息,字段级消息不会生效。
从源码链路看,src/middlewares/check.ts 把第三个参数 message 通过 ContextBuilder.setMessage(message) 写入 Context,之后 src/context.ts 的 addError() 在 opts.message(Validator 级)为空时回退到 this.message(字段级),最终才落到 'Invalid value'。由此可总结出完整的消息优先级:
Validator 级(.withMessage() / 自定义校验器抛出的内容)
> 字段级(check(field, message) 的第二个参数)
> 默认消息('Invalid value')
动态消息:用函数按请求上下文生成文案
express-validator 允许在任何支持校验消息的位置传入函数,从而根据字段值、请求对象、位置等信息动态生成消息。这在接入翻译/国际化(i18n)库时尤其有用:
// check(field, withMessage) 和 .withMessage() 行为一致
check('something').isInt().withMessage((value, { req, location, path }) => {
return req.translate('validation.message.path', { value, location, path });
}),
check('somethingElse', (value, { req, location, path }) => {
return req.translate('validation.message.path', { value, location, path });
}),
// oneOf 比较特殊——目前它只接收 req 对象
oneOf([ someValidation, anotherValidation ], ({ req }) => {
return req.translate('validation.multiple_failures');
});
字段类动态消息的签名
对于 check(field, message)、.withMessage() 以及 body() 等校验中间件,动态消息函数接收两个参数:
value:被校验字段的当前值;meta:包含req(Express 请求对象)、location(字段来源:body/cookies/headers/params/query)、path(字段在请求对象中的完整路径,例如foo.bar)等元信息,类型定义见 src/base.ts。
其对应的类型是 src/base.ts 中的 FieldMessageFactory = (value: any, meta: Meta) => any。底层调用发生在 src/context.ts:当 typeof msg === 'function' 时,会执行 msg(opts.value, opts.meta) 并把返回值作为最终消息。
上面示例中的 req.translate(...) 只是示意——你可以把它替换为任意 i18n 库(如 i18next)的翻译函数,或任何基于请求上下文的逻辑。
oneOf 的特殊签名
oneOf() 的错误消息函数签名与字段类不同:它目前只接收 req 对象,用于在所有备选链都失败时生成聚合消息。对应的类型是 src/base.ts 中的 AlternativeMessageFactory = (nestedErrors, opts: { req }) => any。若没有提供该函数,oneOf() 的默认消息是 Invalid value(s)——注意比字段默认多了个 (s),见 src/middlewares/one-of.ts 及 src/middlewares/one-of.spec.ts 的断言。
此外,在源码类型层面还存在针对 checkExact() 的 UnknownFieldMessageFactory 与针对 errorType: 'grouped' 的 GroupedAlternativeMessageFactory(src/base.ts),它们同样接收函数形态的动态消息,可满足更精细的报错定制需求。
优先级与回退机制小结
把上述内容整合成一张便于查阅的对照表:
| 层级 | 设置方式 | 作用范围 | 优先级 | 源码依据 |
|---|---|---|---|---|
| Validator 级 | .withMessage(msg) 或自定义校验器 throw / reject |
单个校验器 | 最高 | src/chain/validators-impl.ts、src/context-items/custom-validation.ts |
| 字段级 | check(field, message) 第二参数 |
整条链上未单独指定消息的校验器 | 次之 | src/middlewares/check.ts、src/context.ts |
| 默认 | 无 | 兜底 | 最低 | src/context.ts |
动态消息(函数)在上述任一位置均可使用:字段类位置接收 (value, { req, location, path }),oneOf 位置接收 ({ req })。
实战建议
- 优先用字段级消息做兜底文案:为每个字段写一条总括性的错误说明,再用
.withMessage()覆盖需要精确区分原因的少数校验器,避免链上每行都重复写文案。 - 自定义校验器尽量抛出带语义的
Error:如throw new Error('Password confirmation is incorrect'),这样消息可读且无需额外配置;若想让自定义校验器的错误与其它文案风格统一,可用.withMessage()覆盖。 - 动态消息函数适合多语言场景:将
req.translate替换为实际 i18n 库的翻译方法,即可按value、location、path组合出精准的本地化文案。 - 记住
oneOf签名的差异:它在失败时产生的是聚合错误,消息函数只收到{ req },不要误用字段级签名。
至此,你已经掌握了 express-validator 错误消息从默认值到三层定制、再到函数式动态消息的完整链路,可以在生产项目中为每个校验场景产出清晰、可读、可国际化的报错信息。