revalidator自定义错误消息教程让JSON Schema校验错误提示对用户友好【免费下载链接】revalidatorA cross-browser / node.js validator powered by JSON Schema项目地址: https://gitcode.com/gh_mirrors/re/revalidatorrevalidator 是一款跨浏览器 / 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。常用的默认消息如下约束默认消息英文可自定义为requiredis required手机号不能为空typemust be of %{expected} type年龄必须是数字minLengthis too short (minimum is %{expected} characters)昵称太短至少 %{expected} 个字符formatis not a valid %{expected}邮箱格式不正确enummust be present in given enumerator状态只能从给定选项里选择 这些默认值只是出厂设置下面三种方式都能在任意层级覆盖它们。四、自定义错误消息的 3 种方式与配置优先级revalidator 生成消息时的查找顺序是字段级messages.约束名→ 字段级message→ 全局validate.messages对应error()函数中的拼接逻辑。优先级配置方式作用范围1最高字段内messages.约束名只覆盖该字段下的这一条约束2字段内message该字段所有校验错误的兜底文案3最低全局validate.messages未单独配置时的默认文案方式一用 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 行占位符含义%{expected}schema 中规定的期望值%{actual}实际校验到的值%{attribute}触发错误的约束名%{property}出错的字段名{ 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.jsREST 接口中校验错误的返回示例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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考