express-validator 自定义错误消息完全指南:Validator 级、自定义校验器级与字段级消息机制

原创2026-10-09 09:30:421,826 阅读
文章标签:后端

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 构建出完全贴合业务语义的校验错误体系。

登录后查看全文
express-validator