API 版本化最小主义：不升版本才是目标

背景与问题

移动端用户更新慢，后端改坏一个字段=旧版本 app 集体出错。API 版本化的教科书方案很多，solo 需要的是最小主义：什么时候才真的需要 /v2，日常如何用「增量变更」绕开版本化。

发现

（来源访问日期均为 2026-09-17）

• 事实（daily.dev 策略对比）：三大方式=URI（/v1/）、header、body——URI 版本对移动端最实用（cache-friendly、易调试、客户端无法控 header 时也成立）；header 版本 URL 干净但难手工测试且缓存复杂。
• 事实（Speakeasy 的演进指南）：共识是用增量变更（可选字段、新端点）维持后向兼容，让升版成为最后手段——版本号是逃生舱不是日常工具。
• 事实（生产实践文 2026-03）：移动端特殊在于用户更新慢——旧版本要长期支持或走 sunset 流程（deprecation 头+宽限期）。
• 事实（APIs You Won't Hate 的经典立场）：版本化没有唯一正解——重要的是规则先写下来并一致执行。
• 推测：solo 的版本化失败模式是「隐式破坏」——响应里删字段、改字段类型、改变语义（同名字段含义变了）。这些都不触发「新版本」，但全都是破坏。

结论

1. 兼容性三禁（日常执行）：不删响应字段、不改字段类型、不改字段语义。新增=永远安全（新字段/新端点随便加）。
2. /v1 只在破坏不可避免时开：开了 v2 就要双版本并行+日历化 sunset（旧版给 90 天+响应带 deprecation 头）——所以先榨干增量变更的空间。
3. 与 opc-old-version-support-policy 对齐：API 版本生命周期挂在 app 版本支持策略上——「支持 app v2.x = API v1 继续」的关系写死在文档。
4. 字段加 extra 逃生口：响应对象预留一个自由对象（如 meta），临时调试信息放这里不动主 schema——降低「想加字段」的 schema 改动频率。

待办 / 下次继续

• 现有 API 响应对照「三禁」自查（有无已删字段历史）。
  
• API 文档里补「版本生命周期=app 版本策略」一行。
  

关联

opc-old-version-support-policy opc-receipt-validation-minimum opc-db-migration-safety opc-cache-ttl-strategy