2、API版本管理基础：语义化版本规范(SemVer)、URI版本控制 vs Header版本控制、版本兼容性策略。

API版本管理是API生命周期管理的核心环节。在自动化驱动的弃用迁移与灰度验证实践中，版本管理不仅是技术规范，更是流程控制的基础。本章将系统讲解语义化版本规范、两种主流的版本控制方式以及版本兼容性策略，为后续的自动化工具链设计奠定基础。

2.1 语义化版本规范（SemVer）

语义化版本规范（Semantic Versioning，简称SemVer）是目前业界最广泛采用的版本号管理标准。它通过主版本号.次版本号.修订号（MAJOR.MINOR.PATCH）的三段式结构，清晰表达API变更的兼容性影响。

SemVer在API管理中的典型应用场景：

• MAJOR版本递增：删除或重命名端点、修改请求/响应字段类型、更改认证方式
• MINOR版本递增：新增可选参数、增加响应字段、添加新端点
• PATCH版本递增：修复文档错误、优化性能、修正边界条件Bug

# 版本号递增示例
v1.0.0 → v1.0.1  # PATCH：修复了查询接口的分页Bug
v1.0.1 → v1.1.0  # MINOR：新增了批量查询接口（向后兼容）
v1.1.0 → v2.0.0  # MAJOR：删除了已弃用的v1接口字段

2.2 URI版本控制 vs Header版本控制

在API的版本标识方式上，业界主要存在两种流派：URI版本控制和Header版本控制。两种方式各有优劣，选择取决于团队习惯、工具链支持以及客户端生态。

URI版本控制示例：

GET /api/v1/users/123      # 返回v1版本的用户数据
GET /api/v2/users/123      # 返回v2版本的用户数据（可能包含更多字段）

Header版本控制示例（使用Accept头）：

# 请求v1版本
GET /api/users/123
Accept: application/vnd.mycompany.users-v1+json

# 请求v2版本
GET /api/users/123
Accept: application/vnd.mycompany.users-v2+json

2.3 版本兼容性策略

版本兼容性策略决定了API在演进过程中如何处理新旧版本之间的关系。合理的兼容性策略能够降低客户端迁移成本，同时为服务端提供足够的演进空间。

2.3.1 向后兼容（Backward Compatibility）

向后兼容是指新版本的API能够正确处理旧版本客户端的请求。这是API演进中最基本的要求。向后兼容的变更包括：

• 新增可选请求参数（旧客户端不发送，服务端使用默认值）
• 新增响应字段（旧客户端忽略未知字段）
• 放宽输入约束（如扩大枚举值范围）
• 新增端点（不影响已有端点）

2.3.2 向前兼容（Forward Compatibility）

向前兼容是指旧版本的API能够正确处理新版本客户端的请求。这在实践中较难实现，但通过以下设计可以部分达成：

• 服务端忽略未知请求字段（宽容解析）
• 客户端忽略未知响应字段（宽容解析）
• 使用扩展点设计（如Map结构承载未来字段）

2.3.3 兼容性策略矩阵

2.4 版本兼容性自动化验证要点

在自动化驱动的API管理体系中，版本兼容性验证需要嵌入到CI/CD流水线的各个阶段：

1. 规范差异分析：使用OpenAPI Diff等工具自动对比新旧API规范，识别字段新增、删除、类型变更、约束变化等
2. 契约测试：为每个活跃版本维护契约测试套件，确保新版本通过所有旧版本的契约测试
3. 流量回放验证：将生产环境的真实请求流量回放到新版本API，验证响应兼容性
4. 灰度对比测试：在灰度环境中同时运行新旧版本，对比相同请求的响应差异

# 自动化兼容性检查流水线示例（伪代码）
pipeline:
  stage: compatibility-check
  steps:
    - run: openapi-diff --old=spec-v1.yaml --new=spec-v2.yaml
    - if: diff.hasBreakingChanges
      then:
        - notify: "破坏性变更检测，需启动弃用流程"
        - trigger: deprecation-pipeline
      else:
        - run: contract-tests --versions=v1,v2
        - run: traffic-replay --source=production --target=staging-v2