【API 设计之道】09 版本演进策略：激进废弃与平滑过渡的艺术
大家好，我是Tony Bai。
欢迎来到我们的专栏 《API 设计之道：从设计模式到 Gin 工程化实现》的第九讲。
在前面的讲解中，我们已经构建了一个设计规范、传输高效、且具备防御能力的 API 系统。现在，假设这个系统已经上线运行了一年，积累了 100 万用户。
突然有一天，业务部门提出了一个新的需求：
“Tony，用户的
name字段不能只是一个字符串了，我们需要拆分成first_name和last_name，以适配国际化需求。而且，旧的age字段涉及隐私，我们要删掉，换成birth_year。”
这是一个典型的破坏性变更（Breaking Change）。
如果你直接修改代码，发布上线，那么所有没更新 App 的老用户，他们的应用会瞬间崩溃（Crash）。
你面临着两个选择：
由此产生技术债：在代码里写满
if/else补丁，在该返回first_name的地方硬塞一个name给老用户。发布新版本：保留 V1 接口不动，新功能写在 V2 接口里。
绝大多数架构师都会选择方案 2。但方案 2 带来了新的问题：V1 版本要保留多久？代码结构怎么组织才不会乱？如何通知客户端迁移？
今天这一讲，我们就来聊聊 API 的版本演进策略。我们将参考 像Google AIP-180等版本化标准，并在 Gin 项目中落地一套优雅的多版本共存与废弃机制。
核心策略：多版本共存
在 API 设计领域，有一个经典的生命周期模式叫做"Two in Production"（双版本并行）。
它的核心思想是：在任何时刻，生产环境中最多只保留两个主要版本（Major Versions）：当前版本（Current）和 弃用版本（Deprecated）。
当你要发布 V3 时，V1 必须下线，V2 变成弃用版本，V3 变成当前版本。
这种策略既保证了业务能快速迭代，又避免了维护历史包袱（想想维护 V1 到 V10 十个版本的恐怖场景）。
架构决策：URL 还是 Header？
在落地版本化之前，我们还必须解决一个争论已久的问题：版本号放哪里？