对外 API 的契约纪律：版本化、幂等和错误语义，是三件不能事后补的事

API 是一份长期契约，但很多团队把它当成“先跑通再说”的东西，直到客户端开始依赖某个字段的某个行为，才发现改不动了。2026 年比较务实的 API 设计共识可以收敛成三条纪律，每一条都不是“最佳实践建议”，而是“事后补成本极高”的决策。

第一条，从第一天就版本化。URL 路径版本（/api/v1/）对公开 API 最实用，破坏性变更通过新版本隔离，旧版本按明确的废弃策略退出。很多团队觉得“第一个版本不需要版本号”，结果第一次破坏性变更时，要么被迫永久兼容旧行为，要么让所有客户端同时升级。版本化的成本不是多写一个路由，而是旧版本要维护多久、废弃是否提前公告、监控能不能区分新旧版本的流量。

第二条，写操作必须幂等，而且幂等键应该由调用方生成。创建、扣款这类操作，调用方传入 Idempotent-Key，服务端用原子机制锁住这个 key，重试时返回首次执行的结果，而不是重新执行。“幂等”的意思是重复同一个意图请求产生同一个意图效果，不是每个响应字节都相同。服务端自动去重看起来更省事，但只有调用方知道哪两次请求在业务语义上是同一次。

第三条，错误语义要结构化。错误码、是否可重试、建议动作，这些信息应该出现在响应体里，而不是让调用方从 HTTP 状态码猜。一个“500”不告诉调用方该重试还是该放弃；一个结构化的 retryable: true 加 suggested_action 才能让客户端做出正确决策。

这三条的共同点是：它们都是“接口形状”层面的决策，一旦有客户端依赖，修改成本远高于实现成本。API 设计不是“把功能暴露出去”，而是“定义一个未来三年别人可以依赖的契约”。契约的稳定性，比单个接口的优雅程度更重要。