正确做法是统一子模块导入路径并在根go.mod中用相对于根目录的绝对路径replace，各子模块go.mod须显式声明一致go版本，通过go:generate校验跨模块接口契约，并由根tools.go单点锁定工具版本。
go.mod 中 replace 指向本地路径必须统一且可移植
多人协作时，如果 core/module 的本地依赖用 replace github.com/team/core => ../core 这种相对路径，不同人项目结构稍有差异（比如有人把项目 clone 到 /home/a/project，有人在 /work/project），go build 就会报 cannot find module providing package。
正确做法是所有子模块使用一致的导入路径，并在根目录 go.mod 中用绝对可复现的路径替换：
- 统一约定 core 模块的导入路径为
github.com/team/core（哪怕它还没发布到 GitHub） - 根
go.mod中写replace github.com/team/core => ./modules/core，路径始终相对于根目录 - 禁止出现
../或../../等向上跳转路径 - CI 和本地 pre-commit 都应运行
go mod graph | grep core校验是否真命中了本地 replace
子模块 go.mod 必须声明明确的 go version 且与团队基线对齐
一个 modules/core/go.mod 里只写 module github.com/team/core，没写 go 1.21，会导致不同开发者执行 go mod tidy 时自动补上各自本地默认版本（比如有人是 1.20，有人是 1.22），进而引发 go.sum 哈希不一致、泛型语法解析失败等问题。
实操要点：
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 每个子模块的
go.mod第二行必须显式写go 1.21（或团队锁定的 LTS 版本） - CI 流水线中加检查：
grep -r "^go [0-9]" modules/ | grep -v "1\.21"，不匹配才允许通过 - VS Code 的 gopls 会按子模块
go.mod中声明的版本选择语言特性支持，版本错位会导致 IDE 提示“invalid generic type”之类误报
跨模块接口契约需通过 go:generate + interface stub 自动校验
当 modules/user 依赖 modules/core 的 Store 接口，但某次重构中 core 删除了 Save(ctx, v interface{}) error 方法，user 模块却没改——编译不报错，因为 user 只 import 了 core 的包，没直接实现它的接口。只有运行时调用才 panic。
解决方式不是靠人工 review，而是用生成式契约检查：
- 在
modules/core中定义//go:generate go run gen_stub.go，生成core_stub.go，里面包含所有导出接口的空实现 - 在
modules/user的测试目录下写一个contract_test.go，import core_stub 并 embed 接口，让编译器强制检查实现完整性 - pre-commit hook 中跑
go generate ./...+go test ./... -run=Contract - 避免用
interface{}或any做参数类型——它们绕过静态契约，是架构一致性的最大漏洞
tools.go 必须覆盖所有子模块的工具依赖版本
团队在根目录 tools.go 里锁定了 golangci-lint@v1.57.2，但 modules/api 单独运行 go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.58.0，结果 API 模块的 lint 规则比 core 多一条 nilness，导致 PR 在 CI 中 fail，本地却 pass。
关键约束：
-
tools.go必须放在根目录，且每个子模块的构建脚本（Makefile / CI step）都先执行cd .. && go install ./...，确保工具版本来自同一份声明 - 禁止子模块单独维护
tools.go—— 它破坏“单点控制”原则 -
go list -m all | grep golangci在每个模块目录下执行，输出应完全一致；若不一致，说明有人绕过了根 tools.go - GitHub Actions 中要显式
cd ${{ github.workspace }} && go install ./...，不能只在子目录里操作
go generate 或手动 go install 工具，一致性就从那个点开始漂移。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
