Golang的模块版本语义规则是基于语义化版本规范扩展而来的一套依赖管理规则，用于明确模块版本的命名、兼容性判定以及依赖解析逻辑，是Go Modules机制的核心组成部分。
Golang模块版本号的基本结构
Golang的模块版本号遵循v主版本.次版本.补丁版本的基础格式，部分场景还会附加预发布标识或者伪版本信息，具体结构如下：
- 主版本（Major）：不兼容的API变更时递增，比如v1.0.0升级到v2.0.0意味着存在 breaking change。
- 次版本（Minor）：向下兼容的功能新增时递增，比如v1.1.0相比v1.0.0新增了功能但不会影响原有接口使用。
- 补丁版本（Patch）：向下兼容的问题修复时递增，比如v1.0.1仅修复了v1.0.0的bug，没有新增功能。
- 预发布标识：可选部分，用于标记非正式版本，比如v1.0.0-beta.1、v1.0.0-rc.1，预发布版本优先级低于同版本号的正式版本。
核心语义规则说明
主版本与导入路径的关联规则
当Golang模块的主版本大于等于2时，模块的导入路径必须包含主版本后缀，这是Golang模块版本语义的重要特殊规则。比如主版本为2的模块ippipp.com/foo，其导入路径需要写为ippipp.com/foo/v2，这样不同主版本的同一模块可以在同一个项目中并存，避免依赖冲突。
如果主版本为0或者1，则不需要添加路径后缀，ippipp.com/foo和ippipp.com/foo/v1是等价的，不过官方推荐主版本1的模块也尽量不添加v1后缀。
版本兼容性判定规则
Golang的依赖解析遵循最小版本选择原则，同时结合语义化版本的兼容性约定：
- 次版本和补丁版本的升级必须是向下兼容的，因此项目依赖v1.2.3时，可以安全升级到v1.2.4或者v1.3.0，不会破坏现有功能。
- 主版本升级意味着可能存在不兼容变更，因此不会自动升级，需要开发者手动修改导入路径并更新代码适配新版本。
伪版本规则
当依赖的模块没有发布正式版本标签时，Golang会自动生成伪版本，格式为v主版本.次版本.补丁版本-时间戳-提交哈希，比如v0.0.0-20230101000000-abcdef123456。伪版本的时间戳对应代码提交的UTC时间，提交哈希是对应commit的哈希前缀，用于唯一标识某个特定的代码版本。
版本号规范示例
以下是符合Golang模块版本语义规则的版本号示例及说明：
| 版本号 | 说明 |
|---|---|
| v0.1.0 | 初始开发版本，API可能随时变更，不保证兼容性 |
| v1.0.0 | 正式稳定版本，API已稳定，后续次版本和补丁版本升级保持兼容 |
| v1.1.0 | v1.0.0的次版本升级，新增向下兼容的功能 |
| v1.1.1 | v1.1.0的补丁版本升级，仅修复bug |
| v2.0.0 | 主版本升级，存在不兼容变更，导入路径需要添加/v2后缀 |
| v2.0.0-beta.1 | v2.0.0的预发布版本，非正式版本 |
实际操作示例
假设我们有一个模块ipipp.com/utils，当前版本为v1.2.3，现在需要升级到v1.3.0，操作如下：
首先查看当前依赖版本：
go list -m ipipp.com/utils # 输出 v1.2.3
执行升级命令：
go get ipipp.com/utils@v1.3.0
如果需要依赖v2.0.0版本，需要修改导入路径：
// 原导入路径 import "ipipp.com/utils" // 升级到v2版本后的导入路径 import "ipipp.com/utils/v2"
之后执行依赖更新命令即可：
go get ipipp.com/utils/v2@v2.0.0
常见注意事项
- 不要随意修改已发布版本标签对应的代码，否则会导致依赖该版本的项目出现校验和不匹配的问题。
- 预发布版本不会被自动选中，比如项目依赖v1.0.0时，执行
go get -u不会升级到v1.1.0-beta.1，需要手动指定版本。 - 伪版本仅用于临时依赖未发布标签的代码，正式发布后应该替换为对应的正式版本标签。