博客首页 / API 设计

JSON Schema 实战：接口校验、错误提示与版本演进

发布于: 2026-03-21 • 分类: 后端 / API / 工程规范

JSON Schema 的价值不是“写一个大 JSON 文件”，而是把接口约束变成可执行规则。只要规则能被服务端、测试、文档和前端共同消费，联调成本会明显下降。

1. 从核心字段开始，不要一上来追求“完整语法”

很多项目失败在第一步就写得过于复杂。起步阶段建议只用四类高收益约束：

  • type：明确字段类型，避免字符串和数字混用。
  • required：确定最小输入集。
  • enum：限制状态字段取值范围。
  • additionalProperties: false：阻止未知字段静默写入。

这四项就能挡住大量脏数据进入核心链路。

2. 错误提示要“面向调用方”，不是“面向验证器”

校验失败时，如果只返回 `data/0/properties/x` 这种路径信息，业务方很难快速修。建议统一错误格式：

  • 字段路径（例如 `user.email`）
  • 错误类型（缺失、格式错误、超范围）
  • 可操作建议（期望值样例）

调用方得到的是“怎么修”，不是“哪个规则失败”。这点会直接影响对接效率。

3. 兼容升级时，优先“新增可选”，慎用“修改语义”

Schema 升级的风险通常比代码升级更隐蔽。安全策略是：

  1. 新增字段默认可选，不破坏老客户端。
  2. 字段语义变化走新字段，不要复用旧字段名。
  3. 删除字段分两阶段：先标记废弃，再延迟移除。

版本策略最好写进团队规范，否则每次接口改动都在重新博弈。

4. 把 Schema 放到 CI，避免“本地过、线上挂”

落地时建议做三道自动化检查：

  • Schema 自身合法性检查（语法和引用）。
  • 契约测试：用样例请求/响应跑验证。
  • 变更检测：破坏性改动必须显式审批。

这样可以把“接口约定被破坏”前移到提交阶段，而不是上线后才发现。

5. Schema 与文档生成共用一份源

如果文档手写、校验另写，最终必然漂移。理想状态是同一份 schema 同时驱动：

  • 接口校验
  • 示例生成
  • 开发文档与对接说明
Schema 一旦成为“唯一事实来源”，技术债会明显下降。

最小落地清单

  • 核心接口已接入请求/响应双向校验。
  • 错误结构统一，便于前端和第三方调用方处理。
  • Schema 变更进入 CI，有兼容性门禁。
  • 对外文档由 schema 自动生成或半自动生成。

做到这四条，JSON Schema 才不是“文档附件”，而是你接口质量体系的一部分。

相关工具

JSON Formatter

格式化请求样例，联调时更易定位字段问题。

Regex Tester

调试 pattern 字段的匹配规则。

Text Diff

对比 schema 版本差异与破坏性变更。