API 网关如何管理 v1、v2、v3 多版本接口？

日期：2026-07-12
标签：#面试 #八股 #后端 #API网关 #版本管理 #系统设计

一句话答案

通过路径、Header 或媒体类型显式标识版本，网关把版本映射到对应服务/适配器，并配套兼容策略、流量观测、弃用公告和生命周期治理。

面试口语版

公共 API 我更偏向路径 /api/v1/orders，直观且便于缓存和路由；内部接口也可用 Header。网关路由规则匹配 API 名和版本，转发到独立版本服务、同服务不同路由或协议适配层。新版本先灰度，旧版本继续服务；公共 DTO 不能在原版本破坏字段语义。平台维护版本状态：开发、可用、废弃、下线，记录调用方、QPS 和错误，提前通知并提供迁移指南。到期后先告警/限速，确认无调用再移除。

关键细节

• 版本应面向不兼容契约变化，不能每次内部实现变更都升版。
• 缓存 Key 必须包含版本和影响响应的 Header。
• 鉴权 Scope、限流和文档按版本管理。
• 适配层适合短期过渡，长期多版本逻辑应隔离。

面试官追问

1. 路径版本与 Header 版本如何选择？
2. 如何安全下线 v1？
3. 能否由网关把 v1 请求转换为 v3？

面试官追问参考答案

1. 路径版本与 Header 版本如何选择？

路径版本可见、易调试和 CDN 缓存，适合开放 API；Header 保持 URL 简洁，适合内部或媒体类型协商，但代理和缓存必须纳入 Header。团队应统一一种主策略。

2. 如何安全下线 v1？

统计调用方和 QPS，发布弃用日期与迁移文档，逐个通知关键客户；先返回 Deprecation/Sunset 信息、灰度告警和限额，再确认调用归零。保留紧急回滚窗口，不能直接删除。

3. 能否由网关把 v1 请求转换为 v3？

简单字段重命名和默认值可以短期适配；业务语义、事务流程或响应结构差异大时适配器会变复杂且难测试，应由独立兼容服务或保留版本实现。转换必须双向处理错误码和幂等语义。

学习清单

• 能比较版本表达方式。
• 理解弃用、迁移和兼容适配。