express-validator 自定义错误消息完全指南:校验器级、自定义校验器级与字段级三种层级的配置实践

原创2026-10-09 15:18:231,646 阅读
文章标签:后端

express-validator 自定义错误消息完全指南:校验器级、自定义校验器级与字段级三种层级的配置实践

express-validator 默认会为所有校验失败返回统一的 Invalid value,而真实业务往往需要为不同字段、不同规则给出各自贴切的错误提示。本文以 express-validator 官方文档《Custom Error Messages》为核心,结合仓库源码与测试,完整讲解错误消息的三个配置层级(校验器级 .withMessage()、自定义校验器级 throw/reject、字段级第二参数)、消息优先级规则、动态消息函数(支持 i18n 翻译)、复杂错误对象以及 oneOf() 的特殊消息机制,帮你写出面向用户、易于国际化的校验错误输出。

默认行为:一切失败都返回 Invalid value

express-validator 的设计哲学是"默认覆盖所有字段,但不替你做任何主观判断",因此当你在链路上没有为任何校验器指定消息时,错误消息就是一个简单的 Invalid value。

这一默认值在源码中体现在 src/context.ts 的 addError 方法:

const msg = opts.message || this.message || 'Invalid value';

消息的最终取值遵循 opts.message(本次校验的指定消息)→ this.message(上下文/字段级消息)→ 'Invalid value'(默认值) 的链式回退。理解这条优先级链路,是掌握下文三个层级的前提。

注:oneOf() 的默认消息则不同,是 Invalid value(s),详见下文"oneOf 的消息"一节。

错误消息的三个层级

官方文档将自定义消息划分为三个层级,由细到粗依次为:校验器级、自定义校验器级、字段级。

Validator 级:用 .withMessage() 精确控制每个校验器

当你希望对每一条校验规则分别给出错误提示时,使用链式方法 .withMessage(message)。它总是作用于前一个校验器:

const { check } = require('express-validator/check');

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
});

上述例子中,如果 password 长度小于 5,报告的消息为 must be at least 5 chars long;如果它还不包含数字,则额外报告 must contain a number。每条规则独立判定、独立报错,互不影响。

从源码看,.withMessage() 的实现是把消息挂到上一次添加的校验器实例上,见 src/chain/validators-impl.ts:

withMessage(message: FieldMessageFactory | ErrorMessage) {
  this.lastValidator.message = message;
  return this.chain;
}

由于链是可变的(每次调用都在给同一条链追加行为),lastValidator 会随每次校验器注册而更新,因此 .withMessage() 永远绑定它前面的那一个校验器,而不是整条链。

自定义校验器级:throw 或 reject 的内容即消息

当使用 .custom() 自定义校验器时,校验器本身可以通过抛异常或 reject Promise 来表达校验失败,而错误消息就等于抛出/拒绝的内容:

const { check } = require('express-validator/check');

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
});

底层逻辑在 src/context-items/custom-validation.ts:当自定义校验器抛错时,会用 this.message || (err instanceof Error ? err.message : err) 作为消息——即如果该校验器后面跟了 .withMessage(),则用它覆盖;否则字符串直接作为消息,Error 对象取 .message 属性:

} catch (err) {
  if (this.negated) return;
  context.addError({
    type: 'field',
    message: this.message || (err instanceof Error ? err.message : err),
    value,
    meta,
  });
}

因此,若你希望复用同一个自定义校验器到多个路由、又希望在不同路由给出不同的上下文相关提示,可以继续在它后面追加 .withMessage() 来覆盖从校验器得到的消息:

check('email')
  .custom(isEmailAlreadyInUse)           // 可能 reject('E-mail already in use')
  .withMessage('This e-mail is registered'); // 覆盖为更贴合当前路由的说法

Field 级:check(field, message) 的第二参数作为兜底

消息还可以在字段级指定,即创建校验链时的第二个参数:

const { check } = require('express-validator/check');

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
});

该消息作为兜底:只有当校验器没有通过 .withMessage() 指定自己的消息时才会使用。上面例子中,password 长度不足 5 或不含数字时,报 The password must be 5+ chars long and contain a number(这两个校验器没指定消息);而命中 isIn 黑名单时,则报 Do not use a common word as the password(该校验器显式指定了消息)。

在源码里,这个字段级消息保存在 Context 的 message 字段,参与 addError 中的 opts.message || this.message || 'Invalid value' 回退链(见 src/context.ts)。

三层级优先级一览

层级 配置方式 优先级 生效场景
Validator 级 .withMessage(msg) 最高 紧跟其后的那一个校验器失败
自定义校验器级 throw / Promise.reject(...) 次之 自定义校验器失败且未配 .withMessage()
Field 级 check(field, msg) 第二参数 第三 其余所有未指定消息的校验器失败
默认 无 最低 以上均未配置,输出 Invalid value

动态消息:消息函数与国际化(i18n)

在任何支持消息的位置,你都可以提供一个函数来代替字符串。函数会在校验失败时被调用,并接收当前字段的 value 与 meta(包含 req、location、path),返回值即为最终错误消息。这对接入翻译库(如 i18next、自定义 req.translate)特别有用:

// 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');
});

注意 oneOf() 的消息函数签名与其他位置不同:check/.withMessage 的函数收到 (value, { req, location, path }),而 oneOf 只收到 ({ req })。这一点在两个类型定义中也有明确区分,见 src/base.ts:

export type FieldMessageFactory = (value: any, meta: Meta) => any;

export type AlternativeMessageFactory = (
  nestedErrors: FieldValidationError[],
  opts: { req: Request },
) => any;

其中 Meta 结构(src/base.ts)包含 req(Express 请求对象)、location(取值来源:body/cookies/headers/params/query)、path(字段在请求对象内的完整路径)等元信息。动态求值发生在 src/context.ts:typeof msg === 'function' ? msg(opts.value, opts.meta) : msg。

实践要点:由于消息函数只在失败时才求值,你可以放心地在函数内访问 req 上的用户语言、地区等上下文信息,而不必担心未失败的字段产生额外开销。

复杂错误:消息不只是字符串

错误消息可以是比 string 更复杂的类型。例如提供一个带多个属性的对象,便于前端按 errorCode 分支处理:

// check(field, withMessage) 和 .withMessage() 的用法完全一致
check('email').isEmail().withMessage({
  message: 'Not an email',
  errorCode: 1,
});

这在类型层面得到支持:ErrorMessage 被定义为 string | number | symbol | boolean | object | any<a href="https://link.gitcode.com/i/0f082c3d855af96fc8e282afd843e879" target="_blank">](见 [src/base.ts),context.addError 的 message 字段同样接受任意类型(message?: any,见 src/context.ts)。最终错误对象会原样携带该 msg,可在 validationResult(req).array() 中读取。

小提示:若使用复杂对象消息,建议约定统一的结构(如 { message, errorCode, fieldHint }),并确保前端与错误处理中间件对此结构有一致的契约,避免只取字符串导致展示层失效。

oneOf 的消息机制

oneOf() 用于保证传入的若干条校验链中至少一条通过;若全部失败,错误会被推送到 _error 伪字段下,默认消息为 Invalid value(s),源码见 src/middlewares/one-of.ts:

const message = options.message || 'Invalid value(s)';

其动态消息函数接收的参数也与众不同——收到的是嵌套错误列表与请求对象(见上文类型定义)。完整的 oneOf 用法参见 docs/api/one-of.md 及 docs/api/check.md。

相关 API 与延伸阅读

小结

自定义错误消息是 express-validator 中最常用也最容易被低估的能力。合理运用本文的三个层级(校验器级、自定义校验器级、字段级)与动态消息函数,可以让错误响应既精确到每条规则,又能随请求上下文动态生成、天然支持多语言;再配合复杂对象消息,你甚至可以在一个 msg 里携带结构化的错误码信息,为前端提供一致的错误契约。记住优先级链路 opts.message → context.message → 'Invalid value',你就能在任何场景下准确预测最终输出的错误消息。

登录后查看全文
express-validator