3. API版本管理策略：URI版本控制、请求头版本控制、兼容性治理
API版本管理是治理体系中最容易引发生产故障的环节之一。在Mock隔离场景下，版本不匹配会导致模拟响应与真实行为脱节，进而产生“假绿”或“真红”的误判。本节从三种主流策略出发，结合兼容性治理给出可落地的决策框架。
3.1 三大版本控制策略对比
| 策略 | 实现方式 | 可缓存性 | 治理复杂度 | Mock隔离适配 |
|---|---|---|---|---|
| URI版本控制 | /api/v1/orders、/api/v2/orders |
高（URL唯一） | 低（路由直观） | 直接匹配路径前缀 |
| 请求头版本控制 | Accept: application/vnd.company.v1+json |
中（需解析头） | 中（头规则分散） | 需Mock引擎支持头匹配 |
| 查询参数版本控制 | /api/orders?version=1 |
低（参数易变） | 高（污染缓存键） | 不推荐用于Mock隔离 |
治理建议：在Mock隔离故障排查中，优先采用URI版本控制。它使Mock路由规则与生产路由规则保持一一对应，降低“版本误匹配”导致的假阳性报告。
3.2 URI版本控制：最直观的隔离基础
URI版本控制将版本号嵌入路径，例如 /api/v1/users 与 /api/v2/users。这种策略在Mock环境中的优势在于：
- 路由确定性：Mock服务可直接按路径前缀匹配，无需解析请求头或参数。
- 缓存友好：不同版本的响应可独立缓存，不会互相污染。
- 日志可追溯：访问日志中版本信息一目了然，便于证据报告归因。
但需注意：URI版本控制容易导致代码中散布大量版本分支，长期维护成本上升。治理上应设定“版本存活周期”，例如每个大版本最多维护18个月。
3.3 请求头版本控制：灵活但需额外治理
请求头版本控制通过自定义媒体类型（如 Accept: application/vnd.myapi.v2+json）或自定义头（如 X-API-Version: 2）来指定版本。其优势在于URL保持整洁，但给Mock隔离带来三个挑战：
- Mock引擎必须支持头匹配：多数轻量Mock工具默认只匹配路径，需额外配置头规则。
- 版本协商逻辑复杂：服务端可能同时支持多个版本范围，Mock端需同步维护该逻辑。
- 证据报告归因困难：请求头在日志中容易被截断或忽略，导致版本追溯失败。
实践建议：如果团队已采用请求头版本控制，应在Mock服务中强制要求显式版本头，拒绝“默认版本”回退行为。这能避免因版本头缺失而误用错误Mock响应。
3.4 兼容性治理：向后兼容与破坏性变更
版本管理的核心矛盾是“演进速度”与“兼容性”之间的平衡。兼容性治理需要明确的规则和自动化检查手段。
3.4.1 向后兼容性检查清单
| 检查项 | 兼容要求 | 违规后果 |
|---|---|---|
| 新增字段 | 必须为可选，且提供默认值 | 消费者解析失败 |
| 删除字段 | 禁止在同一个大版本内删除 | 消费者数据丢失 |
| 修改字段类型 | 仅允许扩大范围（如int→long） | 序列化/反序列化异常 |
| 修改枚举值 | 仅允许新增，禁止删除或重命名 | 消费者逻辑分支失效 |
| 修改端点路径 | 必须通过新版本发布，旧路径保留 | 404错误 |
| 修改请求方法 | 禁止在同一个版本内变更 | 405 Method Not Allowed |
3.4.2 破坏性变更的版本升级流程
当必须引入破坏性变更时，应遵循以下治理流程：
- 发布新版本（如v2），旧版本（v1）继续运行。
- 设置废弃通知：在v1响应中添加
Sunset头，告知消费者迁移截止日期。 - 并行运行期：至少保持两个大版本并行运行一个完整发布周期（通常≥3个月）。
- 流量监控：持续监控v1流量，当低于阈值（如总流量的5%）时启动下线流程。
- Mock同步：在废弃v1的同时，删除对应的Mock服务实例，避免遗留Mock产生误导。
3.5 版本治理在Mock隔离中的特殊考量
常见陷阱：Mock服务中“版本回退”行为是故障排查中最隐蔽的问题。例如，当Mock引擎找不到v2的响应定义时，自动回退到v1的响应，导致测试通过但生产失败。治理上必须禁用任何隐式版本回退。
在基于证据报告的Mock隔离故障排查中，版本管理策略直接影响证据链的完整性。建议在Mock响应中强制包含以下版本证据字段：
X-Mock-Version：实际响应的API版本号X-Mock-Matched-Rule：匹配到的Mock规则IDX-Mock-Fallback：是否发生了版本回退（true/false）
这些头信息将作为证据报告的核心字段，帮助排查人员快速定位版本不匹配导致的隔离故障。