import cycle not allowed 错误源于包间 import 闭环，而非多模块本身；需通过提取 internal/contract 契约包、清理测试文件、使用 go list/go mod graph 定位并重构依赖链来解决。
go build 报 import cycle not allowed，不是模块问题，是包结构问题
Go 的 import cycle not allowed 错误从不源于多模块本身（比如两个独立的 go.mod），而是由模块内或跨模块的 Go 包（.go 文件）之间实际的 import 语句闭环触发。即使你用了 replace 或多个 go.mod，只要 a/pkg1 导入 b/pkg2，而 b/pkg2 又导入 a/pkg1（直接或经由中间包），编译器立刻失败。
常见误判场景：
- 把“服务 A 调用服务 B 的 client”和“服务 B 的 handler 实现”放在同一模块里，client 包偷偷引入了 handler 所需的 error 定义或回调接口
- 测试文件（
*_test.go）为了方便，直接 import 了本不该依赖的业务包，导致构建时路径闭合 -
replace指向本地路径后，两个模块共用一个未隔离的shared子目录，但该目录下包又反向 import 任一主模块
用 internal/contract 统一 RPC 契约，切断跨模块 import 链
微服务或多模块项目中，最常踩的坑是把 DTO、接口、错误类型散落在各服务包里。结果 service/user import service/order 的 User 结构体，service/order 又 import service/user 的 ErrNotFound —— 本质是契约没收敛。
正确做法是新建一个只读、无依赖的契约包：
- 路径必须是
internal/contract或api/v1（不能是shared，否则外部模块可 import，失去隔离性） - 运行
go list -f '{{.Imports}}' ./internal/contract，输出应为空或仅含errors、time等标准库 - DTO 只含字段和 JSON tag，不写方法；接口只暴露当前调用必需的 1–2 个方法，例如：
type UserGetter interface { GetByID(context.Context, int64) (*User, error) } - 所有模块（
service/user、service/order、client/user）都只 importinternal/contract，彼此不再 import
重构时优先检查 go mod graph 和 go list 输出
IDE 报红往往只提示起点和终点，真正闭环可能绕三四个包。靠肉眼翻代码效率极低，必须用命令定位：
-
go mod graph | grep your-module-name：看模块级依赖流向，确认是否真有跨模块闭环（正常应为单向树） -
go list -f '{{.ImportPath}}: {{.Imports}}' ./... | grep -E "(pkgA|pkgB)"：筛出可疑包的完整 import 列表，找谁在拉谁 -
go build -x ./...：加-x查看实际执行的 compile 命令，错误前最后一行常暴露触发点 - 若仍卡住，临时删掉所有
*_test.go，再构建——很多循环来自测试文件的隐式引用
别用 replace 掩盖包结构缺陷
replace github.com/org/a => ./a 是开发期联调手段，不是解循环的方案。它只会让问题更隐蔽：
- CI 环境禁用
replace，构建直接失败，此时再修已晚 - replace 后
go list -m all显示路径映射，但 import 图校验照常进行，该报错还是报错 - 真正要动的是源码：把共用类型提到
internal/contract，把回调逻辑改为函数参数注入，把初始化逻辑从包级变量移到构造函数 - 如果两个模块实在密不可分（如
user和profile总是一起变更），合并为一个模块 + 一个包，比硬抽离更诚实
循环依赖从来不是技术限制，而是设计信号——它在提醒你：这两个东西本就不该分开存在，或者它们之间的交互方式错了。强行“绕过”只会让下次重构成本翻倍。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
