express-validator 自定义错误消息完全指南:Validator 级、字段级与动态消息的优先级与实战

原创2026-10-09 15:42:341,991 阅读
文章标签:后端

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

实战建议

  1. 优先用字段级消息做兜底文案:为每个字段写一条总括性的错误说明,再用 .withMessage() 覆盖需要精确区分原因的少数校验器,避免链上每行都重复写文案。
  2. 自定义校验器尽量抛出带语义的 Error:如 throw new Error('Password confirmation is incorrect'),这样消息可读且无需额外配置;若想让自定义校验器的错误与其它文案风格统一,可用 .withMessage() 覆盖。
  3. 动态消息函数适合多语言场景:将 req.translate 替换为实际 i18n 库的翻译方法,即可按 value、location、path 组合出精准的本地化文案。
  4. 记住 oneOf 签名的差异:它在失败时产生的是聚合错误,消息函数只收到 { req },不要误用字段级签名。

至此,你已经掌握了 express-validator 错误消息从默认值到三层定制、再到函数式动态消息的完整链路,可以在生产项目中为每个校验场景产出清晰、可读、可国际化的报错信息。

登录后查看全文
express-validator