要点
- 01由 Ajv 提供支持，最广泛使用的 JavaScript JSON 架构验证工具 — 在 Node.js、Fastify 和大多数 JS 工具链中通过的内容在此也通过。
- 02一次报告每个验证错误（allErrors 模式），而不是仅第一个失败。
- 03每个错误包括失败字段的 JSON 指针路径，用于快速导航。
- 04架构和数据完全在浏览器中运行 — 无上传。
为什么针对架构验证 JSON?
JSON 架构是描述 JSON 文档形状的标准方法 — 必填字段、允许的类型、值约束、嵌套对象结构。在有效负载到达生产前针对架构验证会捕获类型不匹配、缺少的必填字段和约束违反，当它们便宜修复时。
最常见的用例是测试 API 请求和响应体、验证配置文件、检查 OpenAPI 示例对象和验证数据导出与已知结构。Handytool 的验证工具使用 Ajv — 事实上的 JavaScript JSON 架构库，在 Node.js 本身内部使用 — 所以此处的结果与你的后端看到的匹配。
如何针对架构验证 JSON
- 01
粘贴你的 JSON 架构
在左面板中粘贴架构。这可以是具有 type、properties、required、items、anyOf、allOf 的 Draft 7 或 2019-09 或 2020-12 架构 — 任何标准 Ajv 支持的关键字。
- 02
粘贴你的 JSON 数据
在右面板中粘贴你想要验证的数据文档。这是实例 — API 请求体、配置对象、导出记录或来自 OpenAPI 规范的单个示例。
- 03
单击验证
Ajv 以 allErrors: true 运行验证，意味着它收集每个失败而不是在第一个处停止。
- 04
审查错误列表
每个错误显示失败值的 JSON 指针路径（例如 /user/email）、失败关键字（type、required、minimum）和人类可读的消息。修复每个并重新验证。
开发者用 JSON 架构验证的内容
- 01REST API 请求体 — 确认有效负载在发送前与端点的预期形状匹配。
- 02OpenAPI 规范示例对象 — 针对内联架构组件验证每个示例。
- 03配置文件 — 确保必需密钥存在且值是正确类型。
- 04数据管道记录 — 抓住数据生产者和消费者之间的结构漂移。
- 05表单提交有效负载 — 测试前端验证是否镜像后端架构约束。
- 06第三方 webhook 体 — 确认文档的架构与实际有效负载匹配。
私密验证，无需服务器
Ajv 完全在浏览器中运行。架构和数据都没有发送到任何服务器 — 你可以安全地验证描述内部数据结构的架构和包含敏感字段值的数据对象。
验证工具支持 JSON 架构 drafts 6、7、2019-09 和 2020-12。现实中最常见的 draft 是 Draft 7，涵盖所有日常关键字：type、properties、required、items、minimum、maximum、pattern、enum、anyOf、allOf、oneOf、not 和 $ref。
JSON 架构验证工具常见问题
支持哪些 JSON 架构 drafts?
Ajv 支持 drafts 6、7、2019-09 和 2020-12。Draft 7 在现有代码库中最常见，涵盖所有标准关键字。
为什么我的 $ref 架构不解析?
外部 $ref URL 在此仅浏览器工具中不被获取。使用 $defs 和本地 JSON 指针如 #/$defs/MyType 内联所有引用的架构。
我的架构或数据上传到任何服务器吗?
不会。Ajv 完全在浏览器中运行 — 架构和数据都保留在你的设备上。
我可以用这个验证 OpenAPI 3 规范吗?
你可以验证单个架构组件和示例对象。验证整个 OpenAPI 文档需要理解规范 meta-schema 的专用 OpenAPI 验证工具。
为什么我看到多个错误而不是仅仅第一个?
验证工具配置了 allErrors: true，这使 Ajv 收集每个失败而不是在第一个处停止。这是故意的 — 你可以在一次通过中修复所有问题，而不是重复验证。