📚 课程目录第4章 API版本管理策略

4. API版本管理策略：URI版本、请求头版本、兼容性策略与废弃流程

特征平台API的版本管理是保障上游消费方（模型训练、在线推理、特征工程管道）稳定性的核心防线。版本策略选择不当会导致接口混乱、消费方频繁适配、甚至线上故障。本节从URI版本、请求头版本、兼容性策略与废弃流程四个维度展开，结合特征平台场景给出可落地的治理方案。

4.1 URI版本 vs 请求头版本：两种主流模式对比

对比维度	URI版本（路径版本）	请求头版本（Header版本）
示例	`GET /api/v1/features/user_age`	`GET /api/features/user_age` `Accept: application/vnd.featureplatform.v1+json`
可见性	显式，URL中直接体现版本号	隐式，版本信息在HTTP头部
缓存友好性	高，不同版本URL天然隔离	低，需依赖Vary头部或自定义缓存键
调试/测试	方便，直接修改URL即可切换版本	需修改请求头，工具链支持要求高
特征平台推荐度	★★★★★（强烈推荐）	★★☆☆☆（仅限内部服务间调用）

  特征平台实践建议： 对外部消费方（如模型训练框架、在线推理服务）统一使用URI版本。原因：特征平台API调用频率极高，缓存命中率直接影响延迟；URI版本天然支持CDN/反向代理缓存，且消费方代码中版本号一目了然，降低误调用风险。

4.2 URI版本管理规范

特征平台URI版本采用主版本号（Major）机制，不引入次版本号或补丁版本号到URL中。主版本号变更代表不兼容的协议变更。

# 规范格式
GET /api/v{主版本号}/features/{特征名称}

# 示例
GET /api/v1/features/user_age          # v1版本
GET /api/v2/features/user_age          # v2版本（不兼容变更）
GET /api/v1/features/batch             # 批量特征查询（v1）

版本号起始规则： 特征平台首个正式发布版本从 v1 开始，不使用 v0 或 v0.1 等非稳定版本号。内部开发阶段可通过 feature flag 控制，不暴露版本号。

4.3 兼容性策略：向前兼容与向后兼容

特征平台API兼容性策略分为两个层次：语义兼容和行为兼容。下表列出常见变更场景及兼容性判定：

变更类型	变更示例	兼容性	版本策略
新增可选字段	响应体增加 `feature_version` 字段	向后兼容	同版本内发布
新增特征	新增 `user_credit_score` 特征	向后兼容	同版本内发布
删除特征	下线 `user_age_v1` 特征	不兼容	需新版本 v2
修改特征数据类型	`int` → `float`	不兼容	需新版本 v2
修改特征默认值	默认值从 `0` 改为 `-1`	行为不兼容	需新版本 v2
新增必填请求参数	增加必填 `entity_type` 参数	不兼容	需新版本 v2

常见陷阱： 特征平台中“修改特征默认值”常被误判为兼容变更。实际场景中，消费方可能依赖默认值做异常检测或阈值判断，默认值变更会导致线上推理结果偏移，必须视为不兼容变更并发布新版本。

4.4 版本废弃流程（Deprecation & Retirement）

特征平台API版本废弃必须遵循“先公告、后废弃、再下线”的三阶段流程，确保消费方有充足时间迁移。

公告期（Deprecation Announcement）
- 在API响应头中添加 Deprecation: true 和 Sunset: Sat, 31 Dec 2025 23:59:59 GMT
- 在特征平台开发者门户发布废弃公告，明确下线时间
- 公告期至少持续 90天（特征平台建议180天）
废弃期（Deprecated）
- API仍可正常调用，但返回 Warning: 299 - "v1 is deprecated, use v2 instead"
- 监控废弃版本的调用量，主动联系TOP消费方确认迁移计划
- 废弃期内不再接受新消费方接入
下线期（Retirement）
- 到达Sunset日期后，API返回 410 Gone 状态码
- 响应体包含迁移指引链接：{ "error": "v1 retired", "migration_url": "/docs/migration/v1-to-v2" }
- 保留下线版本的历史调用日志至少 30天 用于问题追溯

  特征平台废弃流程关键指标：

  • 公告期：≥180天（内部消费方可缩短至90天）

  • 废弃期调用量阈值：低于总调用量的5% 方可进入下线期

  • 下线后日志保留：30天（满足合规审计要求）

4.5 版本生命周期状态机

下图展示特征平台API版本从发布到完全下线的完整状态流转：

4.6 特征平台版本治理清单

在特征平台日常运营中，API版本治理需纳入以下检查项：

版本数量控制： 同时维护的活跃主版本不超过 3个（当前版本 + 前两个大版本）
版本路由： 网关层统一做版本路由，业务服务不感知版本号
版本文档： 每个版本必须有独立的OpenAPI/Swagger文档，标注废弃状态
版本监控： 按版本维度监控调用量、错误率、P99延迟，废弃版本调用量异常上升时触发告警
版本测试： 新版本发布前，必须通过旧版本的兼容性测试套件（确保新增字段不影响旧消费方）

特征平台版本治理自动化： 建议在CI/CD流水线中集成版本合规检查。例如：当检测到某个版本调用量连续7天低于总调用量的1%时，自动触发废弃流程，创建废弃公告工单并通知版本负责人。