API 版本管理怎么做？接口升级如何兼容旧客户端？

知识点详解：兼容的不是字段表，而是调用方式

哪些变化最容易被漏掉？

假设旧接口返回 amount: 100，约定单位是元。升级后还是返回数字 100，却改成单位为分，类型检查可能完全通过，用户看到的金额含义已经变了。

再比如原来不传 page_size 会返回全部数据，后来默认只返回第一页。即使新增参数是可选的，旧客户端没有分页逻辑，也可能误以为结果只有这些。

所以兼容性检查至少要覆盖输入要求、输出结构、默认行为和业务语义。Google 的 AIP-180也特别提醒：新增能力必须维持旧调用行为，响应枚举增加新值同样要谨慎。

新增字段为什么也可能出问题？

多数设计良好的客户端应该容忍未知响应字段，但某些严格解析器、生成代码或签名计算可能不允许额外字段。服务端不能在没有了解客户端契约的情况下，把“新增永远兼容”作为结论。

新增响应枚举值也很常见。旧客户端可能只认识 pending 和 done，遇到新值 paused 时进入异常分支。因此需要提前定义未知值处理规则，而不是等上线后再希望客户端自动理解。

对自己能控制、能同时升级的内部调用方，兼容策略可以更紧；面对外部客户或更新节奏不可控的 App，就要保留更长的演进空间。

路径版本和请求头版本怎么选？

路径版本容易看出请求属于哪套契约，调试、日志和路由也比较直观。请求头或媒体类型版本可以让资源路径保持一致，但网关、缓存和排错工具都要正确识别版本差异。

选择要与现有协议和基础设施匹配。不能说把 /v1 改成请求头，就天然更加 REST 或更容易维护。

更重要的是版本边界应该清楚。所有小改动都复制一套完整接口，会增加维护成本；真正的不兼容变化却偷偷混进旧版，又会让版本失去意义。

适配层负责守住旧契约

假设新版内部模型更复杂，旧版仍需要原来的字段。可以让不同版本的入口转换请求，再把统一业务结果转换成各版本的响应。

这种做法不等于旧版永远没有成本。适配逻辑、测试样例、文档和监控都要维护；有些语义变化也根本无法无损转换。

因此迁移计划应该明确：哪些变化兼容，哪些需要客户端升级，旧版的支持范围是什么，以及满足什么条件后才考虑退役。

怎样证明旧客户端还能用？

保留旧版真实契约样例，测试旧请求、旧响应解析和默认行为。不能只检查 OpenAPI 文档里是否还有那个字段。

监控还要区分版本与调用方。请求量下降不等于没有重要客户使用；客户端是否在线、是否能更新、是否依赖低频接口，都影响下线判断。

退役日期需要提前沟通，并准备异常回退或延期方案。对外承诺要和实际支持能力一致，不能只写一封“新版更好”的通知。

面试官继续追问

直接给所有接口加版本号就够了吗？

不够。版本号只是标识，没有明确契约、兼容测试和迁移规则，照样会在同一版本里破坏旧行为。

bug 修复算不兼容变化吗？

要看客户端是否依赖该行为，以及既有契约如何定义。安全修复还可能要求优先消除风险，但仍需评估影响和通知，不能用“是 bug”跳过所有迁移工作。

内部接口也需要长期保留旧版吗？

不一定。能协调所有调用方并验证整体升级时，可以缩短兼容期。前提是确实知道调用方，而不是以为只有本团队使用。

面试速记卡

• 兼容对象：输入、输出、默认行为与语义契约。
• 新增能力：也要保证旧请求维持原行为。
• 不兼容升级：明确版本，必要时保留适配层。
• 验证方式：旧客户端契约测试，不只检查文档字段。
• 退役依据：调用方迁移与支持承诺，不是新版上线时间。