📚 课程目录第2章语义化版本控制(SemVer)

语义化版本控制（SemVer）：主版本号、次版本号、修订号的定义与Go模块中的实践

语义化版本控制（Semantic Versioning，简称 SemVer）是 Go 模块依赖管理和接口版本演进的核心契约。它通过 主版本号（MAJOR）、次版本号（MINOR）、修订号（PATCH） 三个数字位，向模块使用者传递明确的兼容性信号。在 Go 项目中，遵循 SemVer 不仅是社区惯例，更是 go mod 工具进行版本选择和最小版本选择（MVS）算法的前提。

3.1 SemVer 格式与核心定义

标准 SemVer 格式为：MAJOR.MINOR.PATCH（例如 v1.4.2）。每个数字位递增时，代表不同的变更语义：

版本位	名称	递增条件	对使用者的影响
MAJOR	主版本号	做了不兼容的 API 修改（破坏性变更）	需要手动迁移代码，可能涉及接口重写
MINOR	次版本号	新增了向后兼容的功能（新接口、新字段）	自动兼容，无需修改现有代码
PATCH	修订号	做了向后兼容的问题修正（Bug 修复、性能优化）	完全透明，直接替换即可

核心原则：一旦发布了某个版本的包，该版本的内容就不可变。任何变更都必须以新版本号发布，禁止修改已发布的标签或模块内容。

3.2 Go 模块中的版本号实践

Go 模块对 SemVer 有严格的执行规则，主要体现在版本标签格式和导入路径上：

标签前缀：所有版本号必须以小写 v 开头，例如 v1.2.3，不能省略 v。
主版本零兼容：主版本号为 0（即 v0.x.x）时，不保证任何兼容性，可以随时进行破坏性变更。
主版本导入路径：当主版本号 >= 2 时，模块路径必须追加 /v2、/v3 等后缀，以允许同一模块的不同主版本共存。
预发布标签：使用 - 分隔预发布标识，如 v1.5.0-beta.1，此类版本不被 go mod 自动选择，需显式指定。

Go 模块版本标签示例：

# 稳定版本
v1.0.0
v1.2.3
v2.0.0

# 预发布版本
v1.5.0-rc.1
v2.0.0-alpha.2

# 主版本 >= 2 时，模块路径示例
module github.com/myorg/mylib/v2

3.3 版本号递增决策流程

在实际开发中，判断应该递增哪个版本位，可以遵循以下决策树：

3.4 Go 模块中的版本兼容性矩阵

以下表格总结了 Go 模块在不同版本变更场景下的兼容性表现和导入路径规则：

变更类型	版本号变化	导入路径变化	go mod 自动升级	使用者是否需要修改代码
Bug 修复	v1.2.3 → v1.2.4	不变	是（自动选择最新 PATCH）	否
新增功能	v1.2.3 → v1.3.0	不变	是（自动选择最新 MINOR）	否（除非使用新功能）
破坏性变更	v1.2.3 → v2.0.0	追加 `/v2`	否（需手动升级）	是（必须迁移）
预发布版本	v1.3.0-alpha.1	不变	否（需显式指定）	视情况而定

3.5 常见实践误区与避坑指南

⚠ 常见误区：

误用主版本号：仅仅因为“改动很大”就递增 MAJOR，但实际接口并未破坏向后兼容。应严格按 SemVer 定义判断。
忘记修改导入路径：当 MAJOR 版本 >= 2 时，必须修改 go.mod 中的 module 路径，否则 go mod 会报错或产生歧义。
在 v0.x.x 阶段承诺兼容性：v0 版本允许任意破坏性变更，使用者应锁定精确版本（如 v0.3.2）而非范围。
发布后修改已打标签的版本：一旦发布 v1.0.0，该标签对应的模块内容就不可变。任何修改都必须发布新版本。

3.6 在 go.mod 中声明依赖版本

Go 模块通过 go.mod 文件声明依赖版本，支持精确版本和版本范围（通过 go get 命令管理）。以下是一个典型的 go.mod 片段：

module github.com/myorg/my-service

go 1.21

require (
    github.com/pkg/errors v0.9.1
    github.com/gin-gonic/gin v1.9.1
    github.com/myorg/mylib/v2 v2.3.0
    github.com/someuser/experimental v0.4.2
)

最佳实践：

对于生产依赖，始终使用稳定版本（MAJOR >= 1）。
对于 v0 依赖，在 go.mod 中锁定精确版本，避免自动升级导致意外破坏。
使用 go get module@version 显式升级，避免使用 go get -u 盲目升级所有依赖。
在 CI/CD 流程中运行 go mod verify 确保依赖完整性。