2. 语义化版本控制(SemVer)

语义化版本控制（Semantic Versioning，简称 SemVer）是 API 版本演进的事实标准。它通过一套严格的三段式版本号规则，让开发者仅凭版本号就能判断变更的兼容性。在 Go REST API 设计中，SemVer 既是模块发布的依据，也是接口版本管理的核心工具。

2.1 主版本号、次版本号、补丁号的含义

SemVer 格式为 MAJOR.MINOR.PATCH（主版本号.次版本号.补丁号），每个部分的递增都对应特定的变更类型：

2.2 API 版本与 SemVer 的映射关系

在 REST API 实践中，SemVer 的版本号与 API 的版本标识之间存在多种映射策略。以下是三种主流映射模式：

1. 直接映射（URL 路径版本）：将 MAJOR 版本直接嵌入 URL，如 /api/v1/users、/api/v2/users。这是最直观的方式，但要求每次 MAJOR 变更都更新客户端。
2. 请求头映射（Accept Header）：通过自定义请求头传递版本号，如 Accept: application/vnd.myapi.v2+json。这种方式将版本信息与 URL 解耦，适合微服务内部调用。
3. 查询参数映射：在 URL 后附加版本参数，如 /api/users?version=2。这种方式简单但容易被缓存污染，不推荐用于生产环境。

下表总结了不同 API 变更场景下的 SemVer 版本号变化：

2.3 Go 模块的 SemVer 实践

Go 语言从 1.11 版本开始内置了模块系统（Go Modules），并强制要求模块版本遵循 SemVer 规范。以下是 Go 模块中 SemVer 的关键实践：

2.3.1 模块路径与版本号

Go 模块的版本号直接体现在模块路径中。对于 MAJOR 版本大于等于 2 的模块，必须在模块路径后添加 /v2、/v3 等后缀：

// go.mod 示例
module github.com/mycompany/orders-api/v2

go 1.21

require (
    github.com/mycompany/common-lib v1.4.2
    github.com/mycompany/payment-gateway/v3 v3.0.1
)

这种设计使得 Go 编译器可以同时导入同一个模块的不同 MAJOR 版本，从而支持渐进式迁移。

2.3.2 版本标签与发布

Go 模块的版本通过 Git 标签来标记。标签格式必须为 vMAJOR.MINOR.PATCH，例如 v1.0.0、v2.3.1。发布流程如下：

1. 在模块根目录执行 git tag v1.0.0 创建标签
2. 执行 git push origin v1.0.0 推送标签到远程仓库
3. 其他项目通过 go get github.com/mycompany/orders-api@v1.0.0 引用该版本

2.3.3 预发布版本与构建元数据

Go 模块支持 SemVer 2.0 的预发布版本和构建元数据：

• 预发布版本：在 PATCH 后添加连字符和标识符，如 v1.0.0-alpha.1、v2.0.0-rc.3。预发布版本优先级低于正式版本。
• 构建元数据：在版本号后添加加号和标识符，如 v1.0.0+build.20240301。构建元数据不影响版本优先级。

Go 模块对预发布版本的处理较为严格：go get 默认不会自动升级到预发布版本，必须显式指定版本号。

2.3.4 最小版本选择（MVS）

Go 模块采用最小版本选择（Minimal Version Selection，MVS）算法来解析依赖。MVS 的核心原则是：

• 对于每个依赖模块，选择所有依赖项中声明的 最大需求版本
• 如果两个依赖项要求同一个模块的不同 MAJOR 版本，则同时保留两个版本（因为模块路径不同）
• 如果两个依赖项要求同一个模块的同一 MAJOR 版本的不同 MINOR/PATCH 版本，则选择较大的版本

这种机制确保了构建的可重复性，同时避免了“依赖地狱”。

2.4 SemVer 与 API 版本的生命周期管理

下图展示了 SemVer 版本号与 API 版本生命周期各阶段的对应关系：

2.5 版本兼容性矩阵

在实际开发中，理解不同版本段变更对 API 消费者的影响至关重要。下表总结了各类变更的兼容性判定：

2.6 版本号选择决策树

当面临 API 变更时，可以使用以下决策树快速确定应递增的版本段：

2.7 Go 模块版本兼容性检查清单

在发布 Go 模块新版本前，建议对照以下清单进行兼容性检查：

• 导出接口检查：使用 go doc 或 gorelease 工具对比新旧版本的导出 API 差异
• 行为兼容性：确保相同输入产生相同输出（包括错误类型和错误消息）
• 序列化兼容性：JSON/Protobuf 序列化格式是否发生变化
• 依赖兼容性：是否升级了依赖模块的 MAJOR 版本
• 构建兼容性：是否修改了 go.mod 中的 Go 版本要求