go 中 import cycle not allowed 是设计约束而非 bug，强制解耦：接口应抽离至独立 contract 包，common 包仅放无业务语义的抽象，延迟注入替代 init 依赖，以换取清晰边界。

为什么 import cycle not allowed 无法绕过

Go 编译器在解析依赖时必须确定初始化顺序和符号可见性，一旦检测到 import cycle not allowed，构建直接失败——没有编译期开关、没有注解、也没有运行时补救。这不是 bug，是设计约束：它强制你暴露契约、拆分职责、避免隐式耦合。常见报错形式包括：import cycle: github.com/x/y imports github.com/x/z imports github.com/x/y，或 IDE（如 gopls）只标红却不提示完整路径链。

用接口解耦时，接口该放哪

错误做法是把回调接口定义在被调用方包里（比如 service 包定义 Notifier 接口，再让 event 包 import 它），这仍构成反向依赖。正确做法是将最小契约抽离到双方都能 import 的独立位置：

• 新建 pkg/contract 或 internal/iface 包，仅含接口定义（如 type EventHandler interface { Handle(event Event) error }）
• service 包只 import pkg/contract，并在构造函数中接收 contract.EventHandler 实例
• event 包也只 import pkg/contract，不 import service；具体实现由 main 或 wire 注入

这样依赖方向变为单向：两个业务包都依赖 contract，而 contract 不依赖任何业务包。

Go语言（Golang）1.26.0

Go语言（Golang）1.26.0版本官方下载，版本号 1.26.0，适合旧项目维护、兼容性测试和指定版本开发环境搭建。

下载

common 包不是万能解药，容易踩的坑

把共用结构体、常量、工具函数一股脑塞进 common 包，短期见效快，长期会演变成“上帝包”，导致职责模糊、版本升级困难、测试隔离失效。关键判断标准是：common 里只放真正跨领域、无业务语义的抽象：

• ✅ 允许：type Result[T any] struct { Data T; Err error }、const DefaultTimeout = 5 * time.Second
• ❌ 禁止：type OrderStatus int（这是领域模型）、func SendSMS(...)（这是基础设施行为）
• ⚠️ 风险：type User struct { ID int; Name string } —— 若后续 user 包和 auth 包都依赖它，但各自对 Name 的校验规则不同，就会产生隐式耦合

延迟注入比提前 import 更可靠

当两个包逻辑上必须协作（如 A 初始化时需触发 B 的注册逻辑），不要在包级变量或 init() 中直接调用对方函数。改为显式传递行为：

• 在 A 包定义 type Registrar func(name string, handler Handler) 类型
• A 的构造函数接收该函数作为参数，不 import B
• main 函数中组合：newA(B.Register)
• 若使用 wire，声明 provideB 和 provideA，让 DI 容器在运行时绑定

这种写法彻底切断编译期依赖，还能让单元测试轻松 mock 协作方。真正的难点不在代码怎么写，而在团队是否愿意接受“多写几行注入代码”来换取清晰边界——这点最容易被忽略。

golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！