【GO】Go的依赖管理-叩町coding

构建一个 Go 程序的过程包括确定依赖包及其版本、编译这些包，并将编译后的目标文件链接为最终可执行文件。

Go 依赖管理模式大致经历了三个阶段：

GOPATH 模式：编译器在 $GOPATH/src 下查找第三方依赖。早期常通过 go get 拉取依赖，通常会拿到当时的最新版本，缺乏版本锁定，容易产生不可复现或因依赖升级导致的构建问题。
Go 1.5 引入的 vendor 机制：优先从项目的 vendor 目录查找依赖，便于在仓库中固定依赖代码，减少上游不兼容升级造成的构建风险。
Go Modules：自动解析与管理依赖版本（含传递依赖），提供更完善的版本选择、校验与可复现构建能力，是当前推荐方式。

基于 Go Modules 的依赖管理

将已有项目初始化为一个 module 并构建，通常包括以下步骤：

使用 go mod init 创建 go.mod，把当前项目初始化为一个 module。
使用 go mod tidy 自动补全与整理依赖（添加缺失依赖、移除未使用依赖），并更新 go.sum。
执行 go build 构建项目。

例如在某个空目录下创建 main.go 并写入：

// ch5/modulemode/main.go
package main

import "github.com/sirupsen/logrus"

func main() {
	logrus.Println("hello, go module mode")
}

在该目录执行：

go mod init github.com/hanxuanyu/module-mode

执行完成后会生成 go.mod，内容类似：

module github.com/hanxuanyu/module-mode

go 1.22.0

go 指令表示该 module 期望使用的 Go 语言版本语义（常见为 1.20、1.21、1.22 等），通常不带补丁号；其具体值以你本机 go 版本与初始化时的行为为准。

然后执行：

go mod tidy

该命令会分析源码，确定直接依赖与间接依赖的模块及其版本，并下载到本地模块缓存中。模块缓存默认位于 GOMODCACHE；若未显式设置，则通常为 $GOPATH/pkg/mod（Go 会从环境推导 GOPATH，即使你未手动设置）。

可通过 GOPROXY 为依赖下载提供代理，默认通常为 https://proxy.golang.org,direct。在国内可按需设置为更可用的代理，例如：https://goproxy.cn,direct。

此时 go.mod 会包含依赖信息（示例）：

module github.com/hanxuanyu/module-mode

go 1.22.0

require github.com/sirupsen/logrus v1.9.3

require golang.org/x/sys v0.17.0 // indirect

同时会生成/更新 go.sum，其中记录了依赖模块内容与 go.mod 的校验和，用于确保依赖内容可校验、构建可复现。go.mod 与 go.sum 通常都应提交到版本管理系统中。

接着执行：

go build

会生成可执行文件 module-mode（Windows 下为 module-mode.exe）。运行即可得到预期输出。

常见的 Go Modules 操作

添加依赖

当代码需要引入新的第三方包时：

在源码中导入新包：

package main

import (
	"github.com/google/uuid"
	"github.com/sirupsen/logrus"
)

func main() {
	logrus.Println("hello, go module mode")
	logrus.Println(uuid.NewString())
}

使用 go get 或 go mod tidy 同步依赖

推荐：直接执行 go mod tidy 让工具自动解析并更新依赖。
也可执行 go get github.com/google/uuid@latest（或指定版本）以显式添加/升级依赖。

执行后 go.mod 会出现相应 require 记录，go.sum 也会随之更新。

在现代 Go 版本中，go get 更偏向“调整依赖版本/添加依赖”，而 go mod tidy 用于“按源码实际使用情况整理依赖”。对复杂项目变更，go mod tidy 通常更高效、更不易遗漏。

升级/降级依赖版本

Go Modules 使用语义化版本（SemVer）：

vX.Y.Z
- X：主版本号（不兼容变更）
- Y：次版本号（通常向后兼容）
- Z：补丁版本号（通常仅修复问题）

Go 的语义导入版本（Semantic Import Versioning）规定：当模块主版本号 大于 1 时，导入路径需包含 /vN，例如：

import "github.com/someone/somelib/v2"

查看某个模块的可用版本：

go list -m -versions github.com/sirupsen/logrus

切换到指定版本（升级或降级均可）：

go get github.com/sirupsen/logrus@v1.7.0

也可以先编辑 go.mod 再整理：

go mod edit -require=github.com/sirupsen/logrus@v1.7.0
go mod tidy

添加主版本号大于 1 的依赖

当引入主版本号大于 1 的模块时，需要使用带版本后缀的导入路径，例如：

import "github.com/user/repo/v2/xxx"

然后使用：

go get github.com/user/repo/v2@latest

或指定版本获取。

升级到不兼容的新主版本

升级到不兼容的新主版本通常需要两步：

修改源码中的导入路径（例如 /v3）。
执行 go get github.com/user/repo/v3@latest（或指定版本），再 go mod tidy。

移除依赖

仅删除 .go 文件中的 import 并不会立刻从 go.mod 中移除依赖记录。推荐做法是：

go mod tidy

它会自动移除不再使用的依赖。

也可以显式移除某个依赖（较少使用）：

go get github.com/user/repo@none

兼容 vendor

在不便访问外网或希望将依赖随源码一并分发的场景，可使用 vendor：

go mod vendor

该命令会在 vendor/ 下放置依赖副本，并生成 vendor/modules.txt 记录依赖与版本信息。

基于 vendor 构建：

go build -mod=vendor

自 Go 1.14 起，如果项目存在 vendor 目录且 go.mod 的 go 版本为 1.14 及以上，go 命令默认倾向于使用 vendor（除非指定 -mod=mod）。

替换依赖（replace）

可通过 replace 将某个依赖替换为其它来源（fork、私有镜像或本地路径），可通过编辑 go.mod 或使用 go mod edit -replace 完成。

替换为自定义 fork 版本

适用于上游未合并修复、需要临时采用自维护分支的情况：

require github.com/example/foo v1.0.1
replace github.com/example/foo => github.com/ourfork/foo v1.0.1

锁定依赖到指定版本

可用 replace 将依赖强制指向某个版本（一般更推荐直接在 require 中固定版本，除非需要覆盖传递依赖的版本选择）：

replace github.com/example/bar => github.com/example/bar v0.3.0

替换为本地目录

用于本地调试或未发布版本验证：

require github.com/example/private v0.3.2
replace github.com/example/private => /path/to/our/local/copy

需要注意：go.mod 通常要提交并共享，本地绝对路径对其他开发者与 CI 环境不可用，容易导致无法构建。

为解决多模块本地联调且不污染 go.mod 的问题，Go 在 1.18 引入了 工作区（workspace） 机制（go work），用于在本地将多个 module 组合到同一工作区内进行开发与构建。