单体Go工程不能在子目录反复go mod init，因Go模块机制不支持嵌套，强行初始化会导致import路径与模块名不匹配、依赖解析失败、CI构建异常；官方推荐多模块应独立仓库并语义化版本发布。
单体 Go 工程没法再用 go mod init 直接拆出子模块——Go 的 module 机制不支持嵌套 module，强行在子目录里初始化会破坏依赖解析和 go build 行为。
为什么不能在子目录里反复 go mod init
Go 的 module 是扁平的、以路径唯一标识的。当你在 ./api 下执行 go mod init example.com/project/api，它就变成一个独立 module；但主 module（如 example.com/project）无法 import 它，因为 Go 不会从本地子路径自动 resolve 到该 module——除非你用 replace，而 replace 在 CI 或他人 clone 后失效。
- 本地开发看似能跑，
go build ./...会报no required module provides package -
go list -m all显示多个 module，但只有顶层被真正识别为“主模块” - 第三方工具（如
golangci-lint、go-swagger）按 module 边界扫描，跨 module 时类型/注释丢失
真正的多模块结构只有一种合法形态：每个 module 独立仓库或独立路径
Go 官方推荐的多模块协作方式，是让每个逻辑单元（如 auth、storage）成为独立的 Git 仓库，并使用语义化版本发布。主工程通过 require 声明依赖，而非物理嵌套。
Alibabacloud Sdk Client Initialization For Golang
下载
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
- 如果必须保留在单仓内，可用
replace暂时指向本地路径，例如：replace example.com/project/storage => ./storage
-
replace只对当前 module 生效，不能被下游 module 继承；上线前必须删掉或改用真实版本 - CI 中需提前
go mod edit -replace=...并go mod tidy，否则go build失败
go mod vendor 不解决多模块问题，反而掩盖路径错误
有人试图用 go mod vendor 把子目录代码“打进 vendor”，以为能绕过 module 边界——不行。vendor 只缓存依赖，不改变 import 路径解析规则；如果你 import 的包路径不属于当前 module 的 module 声明，go build 仍报错。
立即学习“go语言免费学习笔记（深入）”；
- vendor 目录里出现
example.com/project/api，但主 module 是example.com/project，Go 不认为这是“自己人” -
go mod vendor后运行go build -mod=vendor，照样找不到example.com/project/api/handler - vendor 是临时方案，不是模块解耦手段；长期依赖它会让重构更难
最易被忽略的一点：Go module 的 import path 必须与实际文件系统路径一致，且不能靠 replace 长期伪装。迁移不是“把代码挪进子目录”，而是重新定义每个模块的边界、版本节奏和发布流程。
