多module适用于需独立发布、解耦协作的大型Go项目，通过replace实现本地开发依赖，结合独立tag与Goreleaser发布，提升模块自治与版本控制粒度。
在大型 Go 项目中，随着功能模块增多、团队协作复杂化，单一 module 很难维持清晰的结构和高效的依赖管理。Go 官方从 1.11 版本引入了 Module 概念，而从 1.18 开始支持多 module 工程（multi-module repository），使得在一个仓库中管理多个独立 module 成为可能。合理使用多 module 结构，有助于解耦业务逻辑、提升构建效率、控制版本发布粒度。
何时需要多 module 结构
单个 go.mod 适用于中小型项目，但以下场景建议考虑多 module：
- 不同模块需独立发布版本（如 SDK、API 服务、CLI 工具）
- 部分代码需作为公共库被外部项目引用
- 团队按模块划分职责，希望减少相互影响
- 某些模块有特殊构建或测试流程
多 module 工程组织方式
常见目录结构如下：
myproject/
├── go.mod # 根 module（可选）
├── cmd/
│ └── app/
│ └── main.go
├── service/
│ └── user/
│ ├── go.mod
│ ├── handler.go
│ └── service.go
├── pkg/
│ └── auth/
│ ├── go.mod
│ └── auth.go
├── internal/
│ └── util/
│ └── helper.go
└── api/
├── go.mod
└── v1/
└── user.proto
每个子目录下的 go.mod 定义一个独立 module，例如：
立即学习“go语言免费学习笔记（深入）”；
service/user/go.modmodule myproject/service/user <p>go 1.21</p><p>require ( myproject/pkg/auth v0.0.0-00010101000000-000000000000 )
pkg/auth/go.mod
module myproject/pkg/auth <p>go 1.21
这种结构让每个 module 可独立打 tag 发布，比如 v1.2.0 对应 pkg/auth 的版本。
本地开发与依赖管理技巧
在同一个仓库内，多个 module 之间可能存在相互引用。由于这些 module 尚未发布正式版本，直接用 require 会失败。解决方案是使用 replace 指令。
用大白话操作当前项目的 Git/GitHub——配置 GitHub（装 gh CLI + 登录 + 建仓库）、备份、拉取下载、查询历史、回滚代码、管理分支。当用户用日常语言表达 git 意图时触发（例如"git备份一下""git下载项目""git拉下来""git看看我改了啥""git回退到上一个版本""git新建个分支搞新功能""git合并到主分支""git
在根目录或任意 module 的 go.mod 中添加：
replace myproject/pkg/auth => ./pkg/auth replace myproject/service/user => ./service/user
这样在本地开发时，Go 命令会直接读取本地路径，而非尝试下载远程模块。CI/CD 流水线中可通过条件判断是否移除 replace（例如发布时）。
另一种做法是在根目录保留一个主 go.mod，通过它统一管理所有子 module 的依赖和 replace，适合强耦合场景。
版本控制与发布策略
每个 module 应有自己的版本生命周期。推荐做法：
- 为每个 module 设置独立的 Git tag 前缀，如
pkg/auth/v1.0.1、service/user/v0.5.0 - 使用工具如 Goreleaser 自动识别路径并打包多个 module
- 发布后更新其他 module 的依赖版本，保持一致性
注意：Go Proxy（如 proxy.golang.org）支持按路径索引模块，只要 tag 正确命名，即可被外部项目直接引用。
优缺点权衡
优点：
- 模块高度自治，可独立测试、构建、发布
- 更细粒度的版本控制
- 便于开源部分组件而不暴露核心代码
缺点：
- 维护多个
go.mod增加复杂性 - replace 使用不当易导致构建不一致
- 新人理解成本较高
对于大多数团队，若无明确的模块拆分需求，建议优先采用单 module + 良好包结构的方式。当确实需要独立演进多个组件时，再引入多 module。
基本上就这些。多 module 不是银弹，关键是根据项目规模和协作模式选择合适方案。结构清晰比技术炫酷更重要。
