先用go mod graph | grep -E 'pkgA|pkgB'快速定位回边，或执行go list -f '{{.ImportPath}} -> {{join .Imports " -> "}}' ./...结合grep过滤可疑包；注意_test.go、embed和generate代码可能隐式引入循环依赖。
go build 报 import cycle not allowed 怎么快速定位源头
Go 编译器只报错不指路，import cycle not allowed 这条错误本身不带路径链，你得自己补全环。最有效的方法不是猜，而是让工具吐出依赖边：
- 运行
go list -f '{{.ImportPath}} -> {{join .Imports " -> "}}' ./...，再用grep过滤可疑包名（比如grep 'pkgA\|pkgB'），一眼看出哪几行连成了环 - 更省事的是
go mod graph | grep -E 'pkgA|pkgB'，如果同时看到pkgA pkgB和pkgB pkgA两行，基本就是它了 - 注意：测试文件（
_test.go）也会参与 import 图计算，错误信息里带(test)后缀的，八成是测试代码悄悄拉了生产包又反向被引用
为什么 go list -f '{{.Imports}}' 看不出完整环
这个命令只展一层 import，比如 A → B、B → C，但不会继续展开 C 的 imports，所以 A → B → C → A 这种三跳环根本不会显形。你得手动追：
- 对每个中间包单独跑
go list -f '{{.Deps}}' pkgpath，再逐层grep，直到回到起点 - 如果项目用了
replace或vendor，加-mod=readonly参数，否则go list可能查线上路径而非实际构建路径 - 别信 IDE 的“当前文件无报错”提示——Go 的循环依赖是构建期全局检查，单文件保存时完全不触发
接口该提进哪个包：调用方、实现方，还是新建 iface
接口位置错了，等于把循环依赖埋得更深。核心原则就一条：接口定义必须放在依赖它的一方的对面包里，也就是既不在调用方包，也不在实现方包。
- 放在实现方包（如
repo/sql）→ 调用方（如handler）被迫 import 实现细节，违背依赖倒置 - 放在调用方包 → 实现方得 import 调用方，容易引发新环（比如
repo/sql想用handler的日志工具） - 新建
internal/port或contract是稳妥选择，但必须确保这个包不 import 任何业务实现包（如repo、service），否则又绕回去了
重构后怎么确认循环真被破除了
改完别急着提交，先验证。光看 go build 成功还不够，要排除隐性残留：
- 执行
go list -f '{{.ImportPath}}: {{.Imports}}' ./...扫一遍所有包，人工确认没有双向引用（比如 A 导入 B，B 也导入 A） - 跑
go mod graph | grep your-module，重点看有没有反向指向自己的边（如your-module/a your-module/b和your-module/b your-module/a同时存在） - 如果仍报错，检查
go.mod里是否有replace导致同一包被多个路径引入（如replace example.com/pkg => ./local-pkg和require example.com/pkg v1.0.0并存），统一路径即可
真正难缠的不是明面上的 import 语句，而是 //go:generate 生成的代码、embed 引入的文件、甚至 init 函数里偷偷调用的跨包函数——这些都可能在你不注意时悄悄闭合了环。
