接口设计中的兼容性取舍：如何让 API 平滑演进

一、兼容性从设计开始

接口一旦对外发布，修改成本就会指数级上升。与其事后补救，不如在设计阶段就确定演进策略：哪些字段可以加、哪些不能删、哪些语义不能变。把这条底线写进团队的接口规范，比任何评审都有效。

二、加法优于减法

新增字段是向后兼容的，删除字段和修改语义则不是。所以接口演进应优先做加法：新增可选字段、新增枚举值、新增独立接口。确需下线时，先标记废弃并给足过渡期，同时在响应里返回弃用提示。

三、版本与内容协商

版本号不要滥用。能用字段级兼容解决的就不要开新版本，否则版本会迅速爆炸。确实存在破坏性变更时，用路径版本或请求头版本，并保证旧版本在约定周期内可用。

四、默认值与幂等

新增字段必须有合理的默认值，老客户端不传也能正常工作。写接口要支持幂等键，避免客户端超时重试导致重复创建。这两点能消除大部分线上事故。

五、契约测试

把接口契约固化成测试：字段类型、必填项、错误码、枚举范围。服务端改动后自动跑一遍契约测试，能提前发现破坏性变更。契约文档与代码同源，避免文档过期。