面经策

API 网关如何实现接口版本管理？如果要同时支持 v1、v2、v3 多个版本的接口，你会怎么设计？ ​

  • 标签：后端、系统设计、场景题、API网关

🏛 业务架构师 ​

网关层接口版本管理（v1/v2/v3 并存），技术上半小时讲完，但我会把重点放在版本生命周期治理——真正的难题不是"怎么同时支持多版本"，而是"怎么让老版本体面地消失"。版本只增不减，成本（服务器、双份逻辑维护、测试矩阵）线性上涨，是慢性技术债。

路由层设计

/api/order/v1/create → 路由到 order-service-v1 (或同服务的v1实现)
/api/order/v2/create → 路由到 order-service-v2
  • URI 路径版本（最直观、缓存友好）为主，header 版本（Accept-Version）适合不改客户端路径的场景
  • 网关路由规则配置化，版本映射到不同服务组或同服务的不同实现（Spring @RequestMapping("/v2/...")）
  • 同一份领域模型，薄适配层：v2/v3 只是接口契约差异，内部尽量收敛到同一核心逻辑，差异在入口适配层转换——避免三份业务代码三份 bug

版本共存策略（N-1 原则）

  • 最多稳定支持 N 和 N-1 两个版本；新版本上线即宣布旧版本弃用时间表（deprecation timeline）
  • 老版本响应头带弃用提示（Deprecation / Sunset header），日志监控各版本流量占比

推动下线（业务侧，架构师重点）

  • 流量看板驱动：v1 流量 < 1% 时启动下线，通知窗口 → 灰度返回 410 Gone → 全量下线
  • 客户端强更联动：移动端最低版本要求（不发版就升不了级）配合服务端版本退役——版本治理需要客户端团队和运营联动，不是服务端单方面的事
  • 开放 API 面向第三方：弃用要提前 3~6 个月公告 + 邮件触达 TOP 调用方，这是合同义务不是技术选择

收尾：接口版本化是"契约精神"的体现——不 break 老客户是底线，让老版本尽快退役是纪律，两者平衡才是版本管理的全貌。

🏗 系统架构师 ​

多版本接口共存是 API 治理的必修课，我按版本策略 → 路由实现 → 数据兼容 → 退役流程讲。

1. 版本化策略选型（先定规则）

  • URL 路径版本 /api/v1/order：直观、可缓存、网关路由最简单——我的默认选择
  • Header 版本（Accept: application/vnd.xxx.v2+json）：REST 纯粹派，但调试麻烦、CDN 不友好
  • 同一资源只保留 2~3 个活跃版本，v1/v2/v3 共存的前提是版本生命周期有治理

2. 网关层路由实现 路由表按"版本→后端集群"配置，版本就是路由条件的一维：

text
/api/v1/order/* → order-service-v1 (老代码实例组)
/api/v2/order/* → order-service (当前版本)
/api/v3/order/* → order-service (灰度中)

关键设计：版本与部署解耦——可以是同一应用内的代码分支（OrderControllerV1/V2 类级隔离），也可以是独立部署组（推荐：老版本单独小集群缩容省钱，新版本全量集群）。配置中心改路由映射即可切版本流量，支持按比例灰度切换（v3 从 1% → 10% → 100%）。

3. 应用内版本组织

  • Controller 层按版本分包，Service 层尽量共享：用策略模式隔离差异逻辑，OrderServiceV1Impl/V2Impl，公共能力下沉 CoreService，避免三份代码各自腐烂
  • DTO 版本转换器（V1DTO ↔ V2DTO），新旧字段映射显式声明，禁止共用 DTO 导致"改一个字段三个版本炸"
  • 契约先行：OpenAPI 按版本分文档，客户端 SDK 按版本发布

4. 兼容性与退役（体现治理成熟度）

  • 优先用向后兼容的非破坏演进：加字段不改语义就不必升大版本（新增字段老客户端忽略），只有破坏性变更才升 v
  • 版本监控：按版本的调用量统计，v1 流量 < 1% 且持续下降 → 发退役公告 → 网关返回 410 Gone + 引导文档 → 下线代码
  • 版本 SLA：对外承诺版本支持窗口（如 12 个月），给客户端升级时间

一句话：URL 版本 + 网关版本路由 + Service 策略隔离 + 调用量驱动的退役机制。

💻 全栈开发专家 ​

多版本共存的核心是版本标识、路由隔离、协议兼容、生命周期治理四件事。

版本标识怎么选

  • URL 路径版本（/api/v1/orders）：直观、可缓存、网关路由最简单，B 端开放 API 的事实标准。
  • Header 版本（Accept: application/vnd.company.v2+json 或自定义 X-Api-Version）：语义更 RESTful，适合内部服务。
  • 我的选择：对外网关层用 URL 版本，网关内部改写到对应服务，客户端无感知内部实现。

网关路由实现

yaml
# SCG 按前缀路由到不同版本的服务实例（K8s 两个 Deployment）
- id: order-v1
  uri: lb://order-service-v1
  predicates: [ "Path=/api/v1/orders/**" ]
- id: order-v2
  uri: lb://order-service-v2
  predicates: [ "Path=/api/v2/orders/**" ]

实例通过注册中心元数据（version=v2）区分，配合权重路由还能做 v2 小流量灰度。APISIX 用 traffic-split 插件按 header/权重分流，更原生。

兼容性设计（比路由更重要）

  • 向后兼容承诺：新增字段可忽略、新增接口可不用，老客户端不发版也能跑；破坏性变更才升级大版本。
  • 复用实现：v2 内部调 v1 的 Handler 或共享 Service 层，只差 DTO 转换，避免两套代码漂移。
  • 数据库/消息契约（schema）同样分版本兼容，Avro/Protobuf 走 schema registry。

生命周期治理

  • 版本注册台账：上线时间、调用量、下线计划。
  • 监控各版本 QPS（网关打点），v1 调用量归零并保留一个观察期后下线。
  • 下线前"通知 + 返回 Sunset 响应头 + 强升级"三步走，别直接 404。