概念定义
API 错误契约：API 是契约，契约的价值是让客户端与服务器独立演进的稳定性——破坏契约就破坏你无法控制的客户端。
工作机制
版本化使变更显式：新字段是加性的，删除或改类型是破坏性的，客户端必须能忽略它不理解的内容。分页、过滤与错误格式是契约的一部分而非事后补记。文档从模式生成故不会漂移。弃用给客户端跑道，在头部与日志中标记，然后才移除。
使用场景
凡多于一个客户端消费接口时应用。误区是把 API 当实现的反映——因内部类改了就改 URL、把数据库列暴露为字段。另一是按 URL 路径版本化并累积 N 个并行代码库而非按能力版本化并演进一个。
延伸说明
补充说明：API 错误契约要求在设计与运维中持续权衡效率、正确性与可维护性，任何单一维度的过度优化都可能引入另一维度的风险。实践上应结合具体场景的约束、团队规模与变更频率，在小步验证中积累证据，而非凭一次假设或单一指标下结论。