Go 1.11+ 多模块项目要求每个模块独立且不可嵌套，必须有唯一模块路径和 go.mod 文件；初始化须按逻辑单元分目录执行 go mod init；跨模块 import 必须严格匹配 module 声明路径；go.work 仅用于本地联合开发，不提交生产。
Go 1.11+ 多模块项目的核心约束：每个 go.mod 独立且不可嵌套
Go 不支持传统意义上的“父模块统一管理子模块”的 Maven-style 多模块结构。所谓“多模块项目”，实际是多个**彼此独立但可相互依赖的模块（module）**，通过 go.mod 显式声明依赖关系。关键前提是：每个模块必须有唯一、可解析的模块路径（如 github.com/yourorg/auth），且其根目录下存在 go.mod 文件。任何子目录若未运行 go mod init，就只是普通包，不构成模块。
初始化顶层模块与子模块的正确顺序
不要先在根目录 go mod init 再拆分子模块——这会导致主模块意外依赖自身路径，引发 invalid import path 或循环引用。应按物理边界先行切分：
- 为每个逻辑单元（如
auth、payment、api）单独建 Git 仓库或至少独立目录 - 进入
auth/目录，执行go mod init github.com/yourorg/auth - 进入
payment/目录，执行go mod init github.com/yourorg/payment - 最后在
api/（主应用）中运行go mod init github.com/yourorg/api，再用go get github.com/yourorg/auth@v0.1.0显式添加依赖
本地开发时，可用 replace 指向本地路径绕过版本发布：
replace github.com/yourorg/auth => ../auth
跨模块调用时的 import 路径必须匹配 module 声明
模块路径不是文件系统路径。假设 auth/go.mod 声明为 module github.com/yourorg/auth，那么在 api/main.go 中必须写：
import "github.com/yourorg/auth"，而非
import "./auth" 或 import "auth"。常见错误包括：
立即学习“go语言免费学习笔记（深入）”；
- IDE 自动补全生成相对路径，手动改为模块路径
- Git 仓库名变更后未同步更新
go.mod中的module行 - 使用
go get安装时拼错模块路径，导致下载到$GOPATH/pkg/mod的缓存路径与代码中import不一致
go.work 文件仅用于本地多模块联合开发，不提交到生产
当多个模块需同时修改（如改 auth 同时调试 api），可在工作区根目录创建 go.work：
go work init go work use ./auth ./payment ./api。这会让
go 命令在当前工作区下将这些模块视为一个整体编译，跳过版本校验。但注意：
-
go.work不替代go.mod，每个模块仍需自己的go.mod - CI/CD 流水线中不应依赖
go.work，它只解决本地开发连贯性问题 - 一旦用
replace或go.work，务必在提交前运行go mod tidy并检查go.sum是否稳定
真正容易被忽略的是：模块路径的稳定性比目录结构更重要。只要 import 和 go.mod 中的 module 保持一致，模块可以放在任意磁盘位置，甚至不同 Git 仓库——Go 的模块系统只认路径，不认物理关系。
