express-validator 自定义错误消息完全指南:Validator 级、自定义校验器级与字段级消息机制
express-validator 自定义错误消息完全指南:Validator 级、自定义校验器级与字段级消息机制
express-validator 默认的校验错误消息是笼统的 Invalid value,虽然能覆盖所有字段、不预设观点,但在真实业务中远远不够友好。本篇指南以 express-validator 6.1.0 的错误消息体系为核心,系统讲解三种消息级别(Validator 级、自定义校验器级、字段级)的配置方式、它们之间的优先级规则,以及通过函数构造动态消息的进阶用法。读完本篇,你将能针对每个校验规则、每个字段乃至整组备选校验链产出精准、可本地化、可读性强的业务错误信息。
默认错误消息:Invalid value 从何而来
express-validator 的所有校验错误,最终都会汇聚到 Context 对象的 addError() 方法中。从源码可以看到错误消息的最终解析逻辑:
// src/context.ts
const msg = opts.message || this.message || 'Invalid value';
也就是说,错误消息的取值顺序是:本次校验器显式指定的消息(opts.message)→ 上下文级兜底消息(this.message,即字段级消息)→ 全局默认 Invalid value。这条优先级链是整个错误消息体系的地基,理解它之后,下面三种级别的配置方式就一目了然了。
另外,当使用 oneOf() 且所有备选链都失败时,默认消息有所不同,是 Invalid value(s)(见 one-of.ts 中 options.message || 'Invalid value(s)' 的实现)。
Validator 级消息:用 .withMessage() 做细粒度控制
当你需要对每一个校验器分别定制错误消息时,使用 Validation Chain 上的 .withMessage(message) 方法。它作用于"上一个校验器",即链式调用中紧邻其前的那个校验规则:
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; - 两个规则分别失败、分别上报各自独立的消息,互不影响。
从源码层面看,.withMessage() 的实现位于 validators-impl.ts,它本质上是把消息写回"上一个校验器"实例:
withMessage(message: FieldMessageFactory | ErrorMessage) {
this.lastValidator.message = message;
return this.chain;
}
每次调用 addItem() 添加校验器时都会更新 lastValidator 指针(validators-impl.ts),因此 .withMessage() 永远只影响紧邻其前的那个校验器,这正是它可以"逐规则定制"的底层原因。后续的实际校验在 CustomValidation 的 run() 中完成,消息字段 this.message 会被携带进错误对象。
自定义校验器级消息: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
});
这里有两种写法等价可互换:
- 同步抛出:
throw new Error('Password confirmation is incorrect'),消息取err.message; - 异步拒绝:
Promise.reject('E-mail already in use'),消息取被拒绝的值本身。
对应的底层逻辑在 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,
});
}
注意这里的关键细节:this.message || ... —— 如果该自定义校验器前面已经用 .withMessage() 指定过消息,那么**.withMessage() 的优先级高于抛出的内容**;只有未显式指定时,才会回落到 throw/reject 携带的消息。
字段级消息:作为校验器的兜底回退
字段级消息在创建校验链时通过校验中间件的第二个参数指定,也就是 check(field, message) 的第二个参数。它作为兜底:当某个校验器没有用自己的消息时,字段级消息才会生效:
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;- 但如果密码命中了
['123', 'password', 'god']黑名单,由于该规则显式指定了.withMessage('Do not use a common word as the password'),则上报这条更具体的消息。
这与前面 Context.addError() 的解析顺序完全吻合:opts.message(Validator 级)优先,其次 this.message(字段级,即创建校验链时传入的第二个参数),最后才是 Invalid value。
字段级消息同样适用于 body()、query()、param()、cookie()、header() 等所有校验中间件变体,因为它们的签名都是 (fields, message) 形式。
三种级别汇总
| 消息级别 | 指定方式 | 作用范围 | 优先级 |
|---|---|---|---|
| Validator 级 | .withMessage(message) |
仅影响紧邻其前的单个校验器 | 最高 |
| 自定义校验器级 | throw 异常 / Promise.reject 的值 |
仅影响该自定义校验器自身失败时 | 中(被 .withMessage() 覆盖) |
| 字段级 | check(field, message) 第二个参数 |
该字段上所有未自定消息的校验器 | 兜底 |
| 全局默认 | 无(内置) | 所有字段 | Invalid value |
动态消息:把消息写成函数,接入翻译与上下文
任何支持消息的位置,都可以传入一个函数而非静态字符串,从而构造动态消息。函数签名统一为 (value, { req, location, path }),其中:
value:触发失败的字段值;req:当前 Express 请求对象;location:字段所在位置(body、query、params、cookies、headers之一);path:字段的路径。
这在接入 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');
});
从源码看,动态消息在 context.ts 中被这样求值:
error = this.updateVisibility({
type: 'field',
value: opts.value,
msg: typeof msg === 'function' ? msg(opts.value, opts.meta) : msg,
...
});
即:当消息是函数时,以 (value, meta) 调用它,meta 展开后即 { req, location, path } 等元信息;当消息是普通字符串时原样使用。
oneOf() 是特例:它只把 req 传给消息函数(以及聚合后的 nestedErrors)。这是因为 oneOf 产生的是"备选整体失败"的错误类型(alternative / alternative_grouped),其消息函数签名为 ({ req }) 或 (nestedErrors, { req }),对应 context.ts 中 alternative 与 alternative_grouped 两个分支的求值方式。oneOf 的默认失败消息为 Invalid value(s),完整参数签名见 oneOf API 文档。
组合实战:消息 + 结果格式化输出
自定义消息只是第一步,配合 validationResult() 的格式化能力,可以构建完整的企业级错误响应:
const { check, validationResult } = require('express-validator');
app.post('/create-user', [
check('email').isEmail().withMessage('Not a valid e-mail address'),
check('password', 'Password must be at least 8 chars')
.isLength({ min: 8 })
.matches(/\d/).withMessage('Password must contain a number'),
], (req, res) => {
const result = validationResult(req).formatWith(({ location, msg, param, value }) => {
return { field: `${location}.${param}`, message: msg, received: value };
});
if (!result.isEmpty()) {
return res.status(400).json({ errors: result.array() });
}
// 校验通过,继续业务处理
});
每个错误对象的默认结构为 { msg, param, value, location, nestedErrors? }(nestedErrors 仅在 oneOf() 场景下出现),msg 即本文所有消息配置的最终落点。
小结
- 消息最终由 Context.addError() 统一解析,优先级为:Validator 级(
.withMessage())→ 字段级(check第二参数)→ 全局默认Invalid value; - 自定义校验器的
throw/reject内容可作为消息,但会被.withMessage()覆盖(见 custom-validation.ts); - 消息可以是函数,从而接入翻译库与请求上下文;
oneOf()的消息函数目前仅接收req; oneOf()全部失败时的默认消息是Invalid value(s)(见 one-of.ts)。
掌握了这三层消息级别与动态消息机制,你就能在不引入额外中间件的情况下,为 express-validator 构建出完全贴合业务语义的校验错误体系。