企业官网建设流程全解析

revalidator自定义错误消息教程：让JSON Schema校验错误提示对用户友好

【免费下载链接】revalidatorA cross-browser / node.js validator powered by JSON Schema项目地址: https://gitcode.com/gh_mirrors/re/revalidator

revalidator 是一款跨浏览器 / Node.js 的 JSON Schema 数据校验库，调用revalidator.validate(obj, schema)即可拿到校验结果与错误列表。它的默认错误提示是英文（如is required、is not a valid url），直接展示给终端用户往往让人摸不着头脑。本教程带你掌握revalidator 自定义错误消息的完整方法：只需在 JSON Schema 中加入messages/message配置，就能把校验错误提示改写成友好易懂的中文文案，显著提升表单与接口的用户体验。

一、为什么默认的校验错误提示不够友好？

当用户提交的数据不符合 JSON Schema 约束时，revalidator 返回的每条错误长这样：

{ attribute: 'maxLength', // 哪条约束不满足 property: 'title', // 哪个字段出错 expected: 140, // 期望值（来自 schema） actual: '一段很长的标题……', // 用户实际提交的值 message: 'is too long (maximum is 140 characters)' }

message里的英文文案是给开发者看的。如果想直接把errors原样返回给前端用户，体验就很差。好消息是：revalidator 内置了轻量级的自定义消息机制，三层配置、几行代码就能搞定。

二、快速上手：安装 revalidator 并跑通第一次 JSON Schema 校验

# 安装到项目（推荐） npm install revalidator # 或克隆源码查看实现 git clone https://gitcode.com/gh_mirrors/re/revalidator

用最小示例跑一遍校验，感受默认错误提示：

var revalidator = require('revalidator'); var result = revalidator.validate( { email: 'not-an-email' }, { properties: { email: { type: 'string', format: 'email', required: true } } } ); console.log(result.valid); // false console.log(result.errors); // [{ attribute: 'format', property: 'email', message: 'is not a valid email', ... }]

返回结构始终是{ valid, errors }，非常方便在业务代码里统一拦截。

三、默认错误消息从哪里来：validate.messages 消息表

所有默认英文文案都定义在核心源码lib/revalidator.js的validate.messages消息表（第 97–116 行）中。校验失败时，error()函数（同文件第 423–434 行）会按规则取出文案并拼装进errors。常用的默认消息如下：

📌 这些默认值只是"出厂设置"，下面三种方式都能在任意层级覆盖它们。

四、自定义错误消息的 3 种方式与配置优先级

revalidator 生成消息时的查找顺序是：字段级messages.约束名→ 字段级message→ 全局validate.messages（对应error()函数中的拼接逻辑）。

方式一：用 messages 精准覆盖单条约束

在字段中写一个messages对象，键是约束名，值是你想展示的文案：

var schema = { properties: { email: { type: 'string', format: 'email', required: true, messages: { required: '请输入邮箱地址', format: '邮箱格式不正确，请检查后重新填写' } } } };

此时缺少email，用户看到的是"请输入邮箱地址"；格式写错，看到的是"邮箱格式不正确，请检查后重新填写"——每条提示都精准对应该条约束。

方式二：用 message 设置字段级兜底消息

当字段使用conform自定义校验函数，或约束很多、不想逐条编写文案时，一条message就能作为统一兜底：

{ conform: function (v) { /* 你的自定义校验逻辑 */ }, message: '该字段的值不合法，请重新填写' }

💡 注意：messages与message可以共存——同一约束以messages优先，message只负责兜底其他错误。

方式三：全局修改 validate.messages 统一风格

对于多页面、多接口的项目，可以在应用启动时把默认英文消息整体替换为中文，让所有 schema 自动继承新风格，不必逐字段配置：

var revalidator = require('revalidator'); // 全局替换默认文案（加载 schema 前执行一次即可） revalidator.validate.messages.required = '此项为必填项'; revalidator.validate.messages.type = '类型应为 %{expected}'; revalidator.validate.messages.minLength = '太短了（最少 %{expected} 个字符）';

三种方式可自由组合：全局打底 + 重点字段精确覆盖，是配置成本最低的组合。

五、占位符技巧：%{expected} 与 %{actual} 让错误提示更具体

自定义消息字符串支持占位符，会被自动替换成真实值（替换逻辑见lib/revalidator.js第 426 行）：

{ type: 'string', maxLength: 140, messages: { maxLength: '最多输入 %{expected} 个字符，当前已超长，请精简内容' } } // 实际提示：最多输入 140 个字符，当前已超长，请精简内容

⚠️ 占位符必须小写且带花括号（%{expected}），写成%{Expected}不会被替换。

六、实战：在接口中把校验错误友好地返回给用户

参考仓库示例example/webservice.js（第 114 行起）中 REST 服务的做法：先校验，不合法就把错误返回给用户。业务代码中常见的写法是：

var validation = revalidator.validate(requestBody, schema); if (!validation.valid) { // errors 中仍保留 expected / actual 等细节，方便开发者排查； // 展示给用户时只取友好的 message var userErrors = validation.errors.map(function (e) { return { field: e.property, msg: e.message }; }); // res.status(400).json({ errors: userErrors }) return; }

这样前端拿到的是友好中文文案；e.property保留了字段名，前端还能据此高亮出错输入框——用户友好与可调试性兼得。

七、常见问题：revalidator 自定义消息的 3 个疑问

Q1：同一个字段既写了 message 又写了 messages，为什么感觉没生效？两者都生效，只是有优先级：同一约束以messages.约束名优先，message只兜底该字段的其他错误。

Q2：每个字段都要写一遍自定义消息吗？不需要。先用"方式三"全局替换validate.messages，再对少数有复杂业务规则的字段用messages/message精确覆盖即可。

Q3：自定义消息在浏览器里能用吗？可以。revalidator 同时支持浏览器与 Node.js；在浏览器中引入revalidator.js后，校验函数挂载在window.validate上，消息机制完全一致。

最佳实践清单：

• ✅ 文案写"怎么做"而不是"违反了什么规则"（如"请输入 11 位手机号"，而非"pattern invalid"）
• ✅ 多用%{expected}/%{actual}，避免把数字写死在文案里
• ⚠️ 面向用户的文案避免 JSON Schema、约束等术语
• ⚠️ 保留property字段名，便于前端定位并高亮错误输入

八、小结：让 JSON Schema 校验提示对用户友好

revalidator 的自定义错误消息机制分为三层：字段级messages（精准）、字段级message（兜底）、全局validate.messages（默认），再配合%{expected}、{actual}四个占位符，几乎可以把任何默认英文消息改写成用户看得懂、愿意照做的友好提示。做表单校验或接口参数校验时，把错误文案定制好，就是"能用"到"好用"的最后一公里。

相关文件速查：

• 核心校验逻辑、默认消息表与error()函数：lib/revalidator.js
• REST 接口中校验错误的返回示例：example/webservice.js
• 自定义消息的测试用例（如messages: { required: "is essential for survival" }）：test/validator-test.js
• 官方文档 Custom Messages 章节：README.md

【免费下载链接】revalidatorA cross-browser / node.js validator powered by JSON Schema项目地址: https://gitcode.com/gh_mirrors/re/revalidator