向后兼容是API设计中最容易被忽视但又最重要的问题。一个破坏性的API变更可能会导致依赖方系统崩溃或数据错误。本文总结十大向后兼容最佳实践，帮助开发者在迭代API时避免踩坑。
响应字段兼容
响应中只增加字段不删除字段是最基本的兼容规则。新增字段使用optional，客户端不需要修改代码就能适应。不要改变已有字段的数据类型，如把int改为string会导致客户端解析错误。不要改变已有字段的语义，如字段值从0表示关闭1表示打开改为1表示关闭0表示打开。响应中已有的枚举值不能删除，只能新增。
请求参数兼容
请求参数只增加不删除，新增参数设置为optional。不要改变已有参数的必填状态，optional改为required是破坏性变更。不要改变参数的数据类型和取值范围。不要改变参数的校验规则，如字符串长度上限从50改为30会导致已有请求失败。新增参数使用默认值，客户端不传时行为与旧版本一致。
接口行为兼容
接口行为兼容性比字段兼容更隐蔽。不要改变已有接口的幂等性，如原来幂等的操作改为非幂等。不要改变已有接口的缓存行为，如原来可缓存的GET请求突然返回动态内容。不要改变错误响应的状态码，如原来返回400改为返回422。不要改变认证和授权要求，如原来不需要认证的接口突然要求认证。
破坏性变更检查清单
以下操作是破坏性变更需要进行版本升级：删除字段或API端点、修改字段数据类型、改变参数必填状态、修改响应状态码、添加新的认证要求、修改已有枚举值含义、改变接口幂等性行为。在发布前使用兼容性检查工具自动扫描API变更，发现破坏性变更及时阻止。兼容性检查纳入CI/CD流水线，在代码合并时自动执行。
以上内容围绕API向后兼容十大最佳实践展开详细讲解，结合实际项目经验和行业最佳实践，帮助开发者深入理解API接口设计的核心要点和常见问题的解决方案，在实际工作中灵活运用这些知识提升接口质量。