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

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 才不是“文档附件”，而是你接口质量体系的一部分。