每个独立可构建、可版本化的单元必须有且仅有一个 go.mod，应按发布粒度切分模块：主应用放根目录，可复用库单独设模块，cmd/ 下二进制共享根模块；replace 仅限开发阶段使用，ci 前须清除；import cycle 需重构包职责，避免越界依赖；go.sum 必须每个模块独立维护。
多模块项目中 go.mod 文件该放在哪一级目录
每个独立可构建、可版本化的单元必须有且仅有一个 go.mod，不能靠“上级目录有就复用”。常见错误是把所有代码堆在根目录下只建一个 go.mod，结果 internal/ 里的包被其他项目 go get 时意外暴露，或子服务无法单独 go test。
正确做法是按发布粒度切分模块：
- 主应用（如 API 服务）：根目录放
go.mod，module github.com/yourorg/app - 可复用库（如通用工具、领域模型）：单独目录如
pkg/util或domain/user，各自含go.mod，module github.com/yourorg/pkg-util -
cmd/下多个二进制（cmd/api、cmd/worker）不单独建模块，它们共享根模块，只通过main.go分离入口
别为了“整洁”把 pkg/ 下的子目录全设成模块——如果 pkg/db 永远不被外部项目引用，它就不该有 go.mod，直接作为根模块的子包更轻量。
replace 指令只在开发阶段有效，CI 构建前必须清理
replace 是本地联调的临时胶水，不是长期依赖方案。CI 环境默认禁用 replace（尤其当设置了 GOFLAGS="-mod=readonly"），此时若没删干净，会直接报 cannot load xxx: module xxx is not a dependency。
典型误用场景：
- 在主模块
go.mod中写replace github.com/yourorg/lib => ./lib，但./lib目录下没有go.mod或其module声明与 replace 路径不一致 - 发布前忘记删
replace行，导致下游项目go get时解析失败 - 用
replace绕过私有仓库权限问题，却没配GOPRIVATE，CI 中go mod download仍走 proxy 失败
建议流程：本地开发用 replace + go mod tidy；提交前运行 go mod edit -dropreplace=github.com/yourorg/lib；CI 第一步加 go mod verify 校验 checksum 完整性。
在 Go 中使用 google/wire 实现编译时依赖注入——wire.NewSet、wire.Build、wire.Bind（接口→实现）、wire.Struct、wire.Value、wire.Interface
import cycle 不是模块问题，是包设计越界
看到 import cycle not allowed 错误，第一反应不该是“怎么让 Go 忽略”，而是检查包职责是否清晰。模块之间能 replace，但包之间循环 import 会被编译器硬性拦截。
高频诱因和解法：
- 把错误码、常量、DTO 放在两个业务模块都依赖的“中间包”，结果 A → shared → B，B 又反向 import A 的 handler —— 正确做法是抽离
shared/errors模块，并确保它不 import 任何业务包 -
internal/config被internal/server和internal/middleware共用，但 middleware 又需要调用 server 的某些函数 —— 这说明 middleware 已越权，应改为由 server 初始化时注入所需能力 - 用
go mod graph | grep yourmodule快速定位实际引入链，比盲猜快得多
记住：internal/ 是模块内边界，不是跨模块通信通道；跨模块调用必须走定义在 pkg/ 下的 interface，且实现由调用方注入。
go.sum 必须每个模块独立维护，不能合并或忽略
go.sum 不是“校验文件”，它是模块可信构建的契约。主模块的 go.sum 不包含子模块的 checksum，子模块更新依赖后，若主模块不运行 go mod tidy，就会出现 checksum mismatch —— 因为主模块记录的是旧版子模块的哈希值。
实操要点：
- 子模块变更依赖后，必须在子模块目录下执行
go mod tidy，生成/更新自己的go.sum - 主模块要同步子模块变更，需先
cd ./submod && git pull && go mod tidy && cd ..，再对主模块运行go mod tidy - 禁止删除子模块的
go.sum；也禁止把多个go.sum手动合并成一个——Go 工具链不认这种操作 - CI 构建脚本里加一行
find . -name "go.sum" -exec sha256sum {} \;，可快速发现未提交的go.sum变更
最易被忽略的一点：go.sum 的路径绑定的是 go.mod 所在目录，不是 GOPATH 或工作区根目录。哪怕用了 go.work，每个模块的 go.sum 依然只管自己那一亩三分地。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
