go mod 基础

Go Modules 介绍

Go module 构建模式是在 Go 1.11 版本正式引入的，为的是彻底解决 Go 项目复杂版本依赖的问题，在 Go 1.16 版本中，Go module 已经成为了 Go 默认的包依赖管理机制和 Go 源码构建机制。

go module可以将某个项目(文件夹)下的所有依赖整理成一个 go.mod 文件，里面写入了依赖的版本

使用go module之后我们可不用将代码放置在src下了，module 隐含了一个命名空间的概念，module 下每个包的导入路径都是由 module path 和包所在子目录的名字结合在一起构成。

go.mod 中会记录当前项目的所依赖的包的信息，文件格式如下：

module gym-booking-backend

go 1.23

require (
    github.com/gin-gonic/gin v1.10.0
    github.com/spf13/viper v1.19.0
    gorm.io/driver/mysql v1.5.7
    gorm.io/gorm v1.25.12
)

go.sum记录每个依赖库的版本和哈希值，用来校验本地包的真实性。

在 go1.16 版本发布后，go module 由原来的默认值auto 变为on 了，意味着 go module 默认已经开启了

Go Modules 使用

初始化

go mod init golang-demo

如果仓库将来会改名，把正式仓库 URL 写进去，少走弯路。
项目里只需要 源码 + go.mod + go.sum，其余都随意放；不必再迁就 $GOPATH/src。

添加/升级/删除依赖

1. 添加依赖

# 直接 import 然后 go run / go test，会自动解析依赖
import "github.com/samber/lo"

# 或手动指定版本
$ go get github.com/samber/lo@v1.39.0   # 推荐显式版本

不写版本 = 拉最新 次版本 (minor)；可能引入破坏性变动，生产环境慎用。
命令
- @latest：抓最新 tag
- @v1.2.3：锁定版本
- @none：移除依赖

2. 升级依赖

# 仅补丁升级（vX.Y.Z -> vX.Y.*）
$ go get -u=patch ./...

# 升级指定包到最新次版本
$ go get -u github.com/samber/lo

3. 清理依赖

$ go mod tidy      # 删掉没用的 / 补全遗漏的
$ go mod verify    # 校验 go.sum 哈希

CI/CD 建议加一步 go vet && go test && go mod tidy && git diff --exit-code，保证合并前依赖干净。

replace / exclude：本地调试 & 急救

replace github.com/foo/bar => ../bar_fork    // 指向本地目录
replace example.com/old => example.com/new v1.4.2
exclude bad.com/broken v0.2.0                // 暂时屏蔽问题版本

replace 永远不会上传到公共 proxy，也不会被 go get 解析；适合本地调试或私有仓库。
exclude 用于某个版本炸了但作者还没修，迫不得已时救急。

私有仓库与代理

告诉 Go 哪些域名是私有的：

$ go env -w GOPRIVATE="git.summer889.com,*.internal"

配置加速代理

$ go env -w GOPROXY=https://goproxy.cn,direct

代理列表逗号分隔，Go 会按顺序兜底；direct 表示最后走源码仓库直连。

多模块仓库与 go.work（Go 1.18+）

大型 mono-repo、或前后端同仓时，常拆成多个模块：

repo/
  backend/go.mod
  web/go.mod
  shared/go.mod

在仓库根目录：

$ go work init ./backend ./shared ./web
# 生成 go.work，告诉编译器这些模块同一个「工作区」

好处：

相互 import 不再走网络，直接引用本地源码；
go run ./backend/cmd/api 时自动解析工作区内依赖；
CI 里照常 go work sync && go mod tidy

vendor：离线 / 合规场景

$ go mod vendor        # 将所有依赖复制到 ./vendor
$ go build -mod=vendor # 强制仅用本地 vendor 目录

离线环境、内网部署必备；
某些严格审计场景要求把第三方代码一并归档。

调试依赖图 & 性能

看依赖树：go mod graph | sort | less
查谁拉进了旧版本：go mod why github.com/xxx/yyy
清空本地缓存（偶尔损坏）：go clean -modcache
GOROOT/GOMODCACHE 默认在 $HOME/go/pkg/mod，可 du -sh 定期清理。

这个gmchart能直接看依赖树，但我没用过 https://github.com/PaulXu-cn/go-mod-graph-chart

总结

import -> run -> tidy 三连，依赖自然生长。
显式版本号，慎用 @latest；生产分支优先 patch 升级。
CI 验证 tidy。
replace 做本地 hack，不把 fork 塞进正式 tag。
遇事先 go mod graph，依赖图是最好的真相。

bajiu