Go模块是强制核心机制，go mod init须在根目录执行以确保模块路径正确；go mod tidy补全、清理依赖并同步校验和，保障构建确定性；内部模块应通过internal/约束访问，跨目录导入必须用完整模块路径。
Go 模块（go mod）不是可选的“工程规范”，而是从 Go 1.11 起强制介入构建链路的核心机制；不用 go mod，连 go build 都可能因导入路径解析失败而报错。
为什么 go mod init 必须在项目根目录执行
模块路径（module path）由 go.mod 第一行 module github.com/user/repo 定义，它直接决定所有相对导入路径的解析基准。若在子目录下误执行 go mod init，会生成错误的模块名（如 module repo/subdir），导致上级包无法正确 import 当前包，或引发 import cycle 报错。
- 执行前先确认当前路径是项目顶层（含
main.go或核心go文件） - 模块名应与代码托管地址一致（如 GitHub 地址
github.com/owner/project），否则go get引入时会拉取错误版本 - 已有
vendor/目录时，go mod init不会自动迁移依赖，需手动运行go mod tidy
go mod tidy 的真实作用不止是“整理依赖”
它实际完成三件事：补全缺失的 require 条目、移除未被任何 .go 文件引用的依赖、同步 go.sum 中的校验和。但很多人忽略它对构建确定性的影响：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- CI/CD 中必须运行
go mod tidy后提交go.mod和go.sum，否则不同机器上go build可能因缓存差异引入不一致的间接依赖 - 如果本地
go.sum缺失某行校验和，go build会静默下载并写入 —— 这会导致构建结果不可复现 - 使用
//go:build ignore的文件不会被扫描，其依赖也不会被tidy纳入，需人工核对
如何安全地拆分内部模块（非发布包）
Go 不支持“子模块”概念，所谓“模块化”本质是通过目录结构 + 显式 import 路径实现的逻辑划分。关键约束在于：每个子目录不能有独立的 go.mod，除非你真想把它发布为独立模块。
立即学习“go语言免费学习笔记（深入）”；
- 推荐结构：
cmd/（入口）、internal/（仅本项目可用）、pkg/（可被外部引用）、api/（协议定义） -
internal/下的包只能被同一模块内代码 import，Go 编译器会强制检查，这是防止意外泄露实现细节的唯一可靠手段 - 若误在
pkg/utils下执行go mod init，会导致主模块无法 import 它 —— 因为 Go 会把它识别为另一个模块，且无版本号匹配 - 跨目录 import 必须用完整模块路径，例如
import "github.com/user/project/pkg/config"，而非import "./pkg/config"（后者非法）
模块路径不是命名空间，而是导入标识符；go.sum 不是锁文件而是校验快照；internal/ 的保护机制只在编译期生效，运行时完全不感知 —— 这些边界一旦模糊，模块化就退化成目录套娃。
