3. 接口版本化的核心概念：语义化版本控制（SemVer）与向后兼容性

在微服务与分布式架构中，接口（API）是服务间通信的契约。当服务边界发生调整、业务逻辑演进或底层数据模型变更时，接口必然随之变化。若缺乏统一的版本化策略，将导致消费者端频繁断裂、发布拓扑混乱、回滚困难。语义化版本控制（SemVer）与向后兼容性正是解决这一问题的两大基石。

3.1 语义化版本控制（SemVer）

语义化版本控制（Semantic Versioning，简称 SemVer）是一种格式化的版本号规范，其核心思想是通过版本号的三个组成部分——主版本号（MAJOR）、次版本号（MINOR）、补丁版本号（PATCH）——来精确传达接口变更的兼容性影响。其格式为：MAJOR.MINOR.PATCH。

3.2 向后兼容性的定义与分类

向后兼容性（Backward Compatibility）是指新版本的接口能够被旧版本的消费者正常调用，而无需消费者做出任何修改。在服务边界划分的上下文中，向后兼容性直接决定了发布拓扑的平滑度。根据影响范围，可将其分为以下三类：

• 完全向后兼容：消费者无需任何适配即可直接调用新版本接口。例如：新增可选字段、扩展枚举值、放宽输入约束。
• 部分向后兼容：消费者需要做少量适配，但适配成本低且可自动化。例如：字段重命名（保留旧字段别名）、响应字段顺序调整。
• 破坏性变更：消费者必须修改代码才能继续工作。例如：删除必填字段、修改字段类型、更改端点路径。

3.3 SemVer 与向后兼容性的映射关系

理解 SemVer 与向后兼容性之间的映射关系，是制定接口版本迁移策略的前提。下图展示了版本号递增与兼容性之间的决策树：

3.4 常见破坏性变更清单

在服务边界划分与接口版本迁移过程中，识别破坏性变更是避免生产事故的关键。以下清单列出了最常见的破坏性变更模式：

3.5 向后兼容性检查策略

在持续交付流水线中，应将向后兼容性检查作为接口发布前的强制门禁。推荐采用以下策略：

1. 契约测试（Contract Testing）：使用消费者驱动的契约测试（如 Pact）验证新版本接口是否满足所有消费者的期望。
2. 自动化兼容性扫描：集成 OpenAPI/Swagger 差异分析工具（如 openapi-diff），自动识别破坏性变更。
3. 灰度发布与流量回放：在预发环境录制真实请求，回放至新版本接口，对比响应差异。
4. 版本共存期：在服务边界划分过渡期，同时运行多个主版本接口，给予消费者充足的迁移窗口。

3.6 版本化在发布拓扑中的落地形态

在服务边界划分后的发布拓扑中，接口版本化通常以以下三种形态落地：

• URL 路径版本化：如 /api/v1/orders 与 /api/v2/orders。直观易用，但可能导致代码分支混乱。
• 请求头版本化：通过 Accept-Version: v2 或自定义 Header 指定版本。保持 URL 整洁，但增加了调试复杂度。
• 查询参数版本化：如 /api/orders?version=2。简单直接，但容易与业务参数混淆。

下图展示了三种版本化形态在服务网关层的处理流程：