用途:在规划 API 版本化策略、应对破坏性变更或管理 API 废弃时使用,帮助 API 随时间演进而不破坏客户端。
主要能力:介绍多种版本化策略,包括 URL 路径版本(如 /v1/users)、请求头版本(Accept 或 API-Version 头)、查询参数版本(?version=1)与内容协商,并对比各策略在可见性、实现难度与缓存上的取舍。同时覆盖版本编号方案:整数版本、语义化版本(major.minor.patch)与日期版本(如 2023-10-16)。还给出破坏性变更与非破坏性变更的判定清单,多版本并行运行的实现方式(分离代码库、共享代码库分支、转换层)、版本路由(API 网关)、默认版本处理、响应中携带版本信息,以及废弃生命周期(当前、维护、废弃、下线)与沟通手段(Deprecation、Sunset、Link 响应头)。
使用方式:作为规划与评审参考,按资料中的策略对比表选择方案;对公共 API 倾向 URL 路径版本,内部 API 可考虑请求头版本;结合破坏性变更清单判断是否需要新大版本。
适用场景:公共或内部 API 的版本策略选型、破坏性变更规划、多版本管理、废弃与迁移支持。
限制:资料未提供自动化工具或脚本,具体实现细节、代码示例与时间线数值仅为示例,落地需结合自身情况调整;版本号命名与支持周期等未给出统一强制规范。