3、版本管理：语义化版本（SemVer）、Git Tag管理、Go Module版本管理、发布版本号策略

版本管理是发布与回滚的基石。没有清晰的版本号体系，团队无法判断哪个版本包含破坏性变更、哪个版本只是修复了漏洞，也无法在 Go 生态中正确发布 Module。本章从语义化版本规范出发，串联 Git Tag 操作、Go Module 版本解析与发布版本号策略，形成一套可落地的版本管理方案。

3.1 语义化版本（SemVer）规范

语义化版本（Semantic Versioning，简称 SemVer）是目前最广泛使用的版本号格式。其核心格式为：

主版本号.次版本号.补丁号（MAJOR.MINOR.PATCH）

每个字段的递增规则如下：

此外，SemVer 允许附加预发布标识和构建元数据：

• 预发布标识：追加在补丁号之后，以 - 连接，例如 1.0.0-alpha.1、2.0.0-rc.3。预发布版本优先级低于正式版本。
• 构建元数据：追加在版本号末尾，以 + 连接，例如 1.0.0+build.20250301。构建元数据不参与版本优先级比较。

3.2 Git Tag 管理

Git Tag 是版本号在代码仓库中的物理锚点。每个 Tag 对应一个不可变的 commit，确保发布版本可被精确回滚。

3.2.1 轻量标签 vs 附注标签

3.2.2 常用 Git Tag 操作

# 创建附注标签
git tag -a v1.2.3 -m "Release v1.2.3: 新增用户权限模块"

# 推送单个标签到远程
git push origin v1.2.3

# 推送所有本地标签
git push origin --tags

# 删除本地标签
git tag -d v1.2.3

# 删除远程标签
git push origin --delete v1.2.3

# 查看标签列表
git tag -l 'v1.*'

3.3 Go Module 版本管理

Go Module 的版本管理严格遵循 SemVer，并在此基础上增加了 Module 路径与版本号的绑定规则。

3.3.1 版本号与 Module 路径

当主版本号大于等于 v2 时，Go 要求 Module 路径必须追加版本后缀：

3.3.2 go.mod 中的版本声明

// 依赖声明示例
require (
    github.com/gin-gonic/gin v1.9.1
    github.com/go-redis/redis/v9 v9.0.5
    github.com/user/repo/v2 v2.1.0
)

Go 会自动解析 go.sum 文件校验版本哈希，确保依赖的完整性与安全性。

3.4 发布版本号策略

在实际项目中，版本号策略需要结合开发流程、发布频率和回滚需求来制定。以下是一套经过验证的策略：

3.4.1 版本号生命周期

1. 开发阶段：使用 v0.x.x 或预发布标识，例如 v0.5.0-alpha.1、v0.5.0-dev。
2. 测试/灰度阶段：使用 v1.0.0-rc.1、v1.0.0-beta.2，通过预发布标识区分迭代。
3. 正式发布：使用标准 SemVer，例如 v1.0.0、v1.1.0、v2.0.0。
4. 热修复：从上一个正式版本的 Tag 创建 release/v1.0.x 分支，修复后发布 v1.0.1。

3.4.2 分支与 Tag 对应关系

3.5 版本管理流程总览

下图展示了从代码提交到版本发布的核心流程，以及 SemVer、Git Tag、Go Module 之间的协作关系：

3.6 常见问题与避坑

• Tag 与 commit 不匹配：打 Tag 前务必确认当前 commit 是期望的版本，避免 Tag 指向错误代码。
• v0 版本处理：v0.x.x 不保证稳定性，Go Module 默认不缓存 v0 版本，适合快速迭代阶段。
• 伪版本（Pseudo-version）：当没有 Tag 时，Go 会自动生成 v0.0.0-20250301120000-abcdef123456 格式的伪版本，仅用于开发依赖，不可用于正式发布。
• Tag 删除风险：远程 Tag 被删除后，已拉取该版本的开发者仍可使用本地缓存，但新开发者无法获取。正式发布后禁止删除 Tag。