express-validator 自定义错误消息完全指南:从 Validator、Field 到动态多级消息
express-validator 自定义错误消息完全指南:从 Validator、Field 到动态多级消息
express-validator 默认的校验错误消息是通用的 Invalid value,它能覆盖所有字段但无法提供有意义的反馈。本指南以 v6.0.0 文档 feature-error-messages.md 为核心,系统讲解自定义错误消息的三个层级(Validator 级、Custom Validator 级、Field 级),并深入剖析动态消息函数、源码级消息解析机制与多级消息的优先级规则,读完即可为你的 Express 接口写出专业、可读、可国际化的校验错误提示。
为什么需要自定义错误消息
express-validator 在字段校验失败时,默认的错误消息是 Invalid value。这个默认值在 src/context.ts 中定义:
const msg = opts.message || this.message || 'Invalid value';
也就是说,一条错误消息的解析顺序是:本次校验项的显式消息(opts.message)→ 整个校验上下文(Context)的默认消息 → 全局兜底 Invalid value。默认消息足够通用,但用户看到 Invalid value 时并不知道到底哪里出了问题——密码太短?缺少数字?邮箱已注册?因此 express-validator 提供了多种方式指定有意义的错误消息,并且支持在三个不同层级上设置。
三个错误消息层级
Validator 级:.withMessage() 精准控制每一条校验
当你想对校验链中每一条校验规则分别给出错误消息时,使用 .withMessage() 方法。它紧跟在对应的校验器之后,只作用于前一个校验器。这正是 src/chain/validators-impl.ts 中的实现:
withMessage(message: FieldMessageFactory | ErrorMessage) {
this.lastValidator.message = message;
return this.chain;
}
方法内部把消息挂到 lastValidator(上一条被添加的校验项)上,所以它只影响前一条校验。官方文档示例(原样保留):
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; - 两条规则各自独立报告,互不影响。
底层消息如何被消费?以标准校验器 StandardValidation 为例,它在校验失败时通过 context.addError({ type: 'field', message: this.message, value, meta }) 携带消息,最终在 src/context.ts 的 addError() 中落地。
Custom Validator 级:抛什么,就报什么
使用 .custom() 自定义校验器时,你不需要额外设置消息——校验器抛出的值(或 Promise reject 的值)会原样成为错误消息。官方文档示例:
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')会让错误消息等于Password confirmation is incorrect(即err.message)。
这一行为来自 CustomValidation 的源码:
} catch (err) {
if (this.negated) {
return;
}
context.addError({
type: 'field',
message: this.message || (err instanceof Error ? err.message : err),
value,
meta,
});
}
注意两点细节:
- 如果自定义校验器同时调用了
.withMessage(),则.withMessage()的优先级更高,err.message只作为没有显式消息时的兜底; - 若 reject/throw 的是普通字符串或对象,会原样作为消息;若抛的是
Error实例,则取err.message。
Field 级:校验中间件的第二个参数作为全局兜底
在 check(field, message)(以及 body、query、param、cookie、header)的第二个参数中可以设置字段级默认消息。它的作用是:当该字段上的某个校验器没有自己的消息时,使用这个字段级消息作为兜底。官方文档示例:
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
});
行为解读:
.isIn(['123', 'password', 'god'])有自己通过.withMessage()指定的消息Do not use a common word as the password,因此优先使用它;- 而
.isLength({ min: 5 })和.matches(/\d/)没有指定消息,当密码过短或不含数字时,会统一报告字段级消息The password must be 5+ chars long and contain a number。
字段级消息最终会通过 ContextBuilder 的 setMessage() 写入 Context 的 message 属性,并在 src/context.ts 中作为 this.message 参与优先级解析。关于 check(field, message) 的完整参数说明,可参考 docs/api/check.md。
三级消息优先级总结
结合 src/context.ts 的 addError() 逻辑,可以确认最终生效顺序:
| 优先级 | 来源 | 设置方式 |
|---|---|---|
| 1(最高) | 校验项级消息(opts.message) |
.withMessage() 或自定义校验器抛出的值 |
| 2 | 字段/链级消息(this.message) |
check(field, message) 第二个参数 |
| 3(最低) | 全局默认 | 硬编码的 Invalid value |
动态消息:函数式生成消息
任何支持消息的位置,都可以传入一个函数来动态生成消息。这在接入 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');
});
函数消息的签名与参数
- 字段级消息函数(
.withMessage()、check(field, message)):签名是(value, meta) => any,对应源码类型 FieldMessageFactory。meta即为 Meta 类型,包含req(Express 请求对象)、location(字段来源,如body、query、params等)、path(字段在请求对象中的完整路径,如foo.bar)、pathValues(通配符/globstar 匹配到的值)。调用点位于 src/context.ts:msg = typeof msg === 'function' ? msg(opts.value, opts.meta) : msg。 - oneOf() 的消息函数:签名是
(nestedErrors, { req }) => any或(nestedErrors, { req }) => any(分组模式),对应源码类型 AlternativeMessageFactory 与 GroupedAlternativeMessageFactory。如文档所述,它目前只向函数传入req对象,用于根据请求上下文决定整体失败消息。
动态消息的典型场景
// 结合 i18n,让消息随请求语言变化
check('email').isEmail().withMessage((value, { req }) => {
return req.t('errors.invalid_email', { value });
}),
// 结合通配符字段选择,把具体路径写进消息
body('products.*.quantity')
.isInt({ min: 1 })
.withMessage((value, { path }) => `Field "${path}" must be a positive integer`),
深入源码:消息解析的内部机制
Context 层:三级回退与四种错误类型
src/context.ts 的 addError() 是消息解析的核心。它先计算 const msg = opts.message || this.message || 'Invalid value',然后根据错误类型决定是否把消息当作函数调用:
field类型:typeof msg === 'function' ? msg(opts.value, opts.meta) : msg,即函数消息接收字段值与 Meta;alternative/alternative_grouped类型:函数消息接收nestedErrors(嵌套的字段错误列表)与{ req };unknown_fields类型(checkExact()触发):函数消息接收未知字段列表与{ req },对应 UnknownFieldMessageFactory。
校验项层:消息挂在最后一次校验上
标准校验器与自定义校验器都是 ContextItem 的实现,都带有 message: any 属性。.withMessage() 通过 lastValidator.message = message 把消息挂到最近一次添加的校验项上,因此它必须在对应校验器之后调用(src/chain/validators-impl.ts)。
oneOf() 的默认消息与消息函数
src/middlewares/one-of.ts 中,oneOf() 的默认消息是 Invalid value(s)(注意与字段默认的 Invalid value 不同)。当所有备选链都失败时,会生成一条 AlternativeValidationError 或 GroupedAlternativeValidationError,其 msg 可以由 options.message 指定,也可以传入 (nestedErrors, { req }) 形式的函数动态生成。相关测试可参考 src/middlewares/one-of.spec.ts,其快照 src/middlewares/snapshots/one-of.spec.ts.snap 也直观展示了默认消息的形态。
读取错误消息:validationResult() 与格式化
自定义消息最终通过 validationResult(req) 读取。一个完整的实战示例:
const { check, validationResult } = require('express-validator');
app.post('/user', [
check('email').isEmail().withMessage('must be a valid e-mail'),
check('password')
.isLength({ min: 5 }).withMessage('must be at least 5 chars long')
.matches(/\d/).withMessage('must contain a number')
], (req, res) => {
const errors = validationResult(req);
if (!errors.isEmpty()) {
return res.status(400).json({ errors: errors.array() });
}
// 校验通过,继续处理请求
});
返回的错误对象形如:
[
{ type: 'field', msg: 'must be a valid e-mail', path: 'email', location: 'body', value: 'foo' }
]
msg 字段就是你通过上述各层级设置的自定义消息。关于 validationResult() 的完整 API(Result 对象的 array()、mapped()、formatWith()、throw() 等方法,以及各类错误类型),可参考 docs/api/validation-result.md。此外,在 schema 校验中也可以为每条校验规则配置 errorMessage,其实现见 src/middlewares/schema.ts:validatorConfig.errorMessage && chain.withMessage(validatorConfig.errorMessage),这意味着 schema 方式与链式调用最终共享同一套消息机制。
最佳实践小结
- 校验器级消息优先用于规则本身含义明确、失败原因各不相同的场景(如密码的长度、复杂度要求),用
.withMessage()逐条定制; - 自定义校验器直接 throw/reject 有意义的描述(如
E-mail already in use),无需额外配置; - 字段级消息作为该字段所有未指定消息规则的兜底,适合"字段整体要求"的统一提示;
- 函数消息适合接入 i18n 翻译库或需要把字段路径、当前值注入提示的场景;
- 记住默认值
Invalid value(字段)与Invalid value(s)(oneOf),它们只在任何层级都未指定消息时出现。