Go多模块拆分核心是每个go.mod对应一个独立发布单元；必须新建go.mod的三种场景：对外提供SDK、跨团队异步升级依赖、需隔离测试/构建约束；开发时用replace指向本地路径，上线前须删除并发布正式版本。
Go 多模块项目拆分的核心原则：每个 go.mod 管理一个独立发布单元
Go 的模块（module）不是“代码组织目录”，而是**语义化版本发布的最小单位**。拆分模块前必须明确：这个子目录是否需要被其他项目独立 go get、是否拥有自己的 v1.2.0 版本号、是否要独立 CI/CD 和依赖管理。如果只是内部包整理，用目录+子包（如 pkg/auth、pkg/storage）就够了，无需新建模块。
什么时候必须新建 go.mod？看这三种典型场景
以下情况建议在子目录中运行 go mod init example.com/myproject/storage 创建新模块：
- 该部分要作为 SDK 对外提供（如
storage模块供其他公司服务调用） - 不同团队维护不同子系统，且依赖升级节奏不一致（如
auth模块坚持 Go 1.20，而api模块已切 Go 1.22） - 需要隔离测试依赖或构建约束（如
storage/s3模块只在 Linux 下启用，且依赖aws-sdk-go-v2，但主模块不需要）
replace 和 require 在多模块协作中的实际用法
主模块（如 cmd/server）引用本地子模块时，不能直接写 import "example.com/myproject/storage" 就完事——它会去 proxy 下载远端版本，而非你本地修改的代码。开发阶段必须用 replace 显式指向本地路径：
module example.com/myproject/cmd/server
go 1.22
require (
example.com/myproject/storage v0.0.0
)
replace example.com/myproject/storage => ../storage
注意：replace 只在当前模块生效，不会传递给下游；上线前需删掉 replace 并发布真实版本号，否则别人 go build 会失败。
立即学习“go语言免费学习笔记（深入）”；
拆分后最常踩的坑：循环依赖与 internal 包误暴露
模块间禁止循环 import。比如 storage 引了 auth，而 auth 又引了 storage，Go 会报错 import cycle not allowed。解决方式只有两个：
- 合并为一个模块（多数内部服务适用）
- 提取公共接口到第三个模块（如
interfaces），让storage和auth都只依赖它
另外，internal 目录在模块边界失效——一旦新建 go.mod，internal 就只对该模块内有效，无法阻止其他模块 import 它。若需真正私有，只能靠文档约定 + 代码审查，或者把敏感逻辑下沉到未导出函数中。
