express-validator 自定义错误消息完全指南:从 Validator、Field 到动态多级消息

原创2026-10-09 13:22:371,889 阅读
文章标签:后端

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 方式与链式调用最终共享同一套消息机制。

最佳实践小结

  1. 校验器级消息优先用于规则本身含义明确、失败原因各不相同的场景(如密码的长度、复杂度要求),用 .withMessage() 逐条定制;
  2. 自定义校验器直接 throw/reject 有意义的描述(如 E-mail already in use),无需额外配置;
  3. 字段级消息作为该字段所有未指定消息规则的兜底,适合"字段整体要求"的统一提示;
  4. 函数消息适合接入 i18n 翻译库或需要把字段路径、当前值注入提示的场景;
  5. 记住默认值 Invalid value(字段)与 Invalid value(s)(oneOf),它们只在任何层级都未指定消息时出现。
登录后查看全文
express-validator