1. 课程导论：什么是循环依赖？为什么循环依赖是Go项目中的常见故障？
1.1 什么是循环依赖？
循环依赖（Circular Dependency）是指两个或多个模块（包）之间形成直接或间接的相互引用，导致编译或运行时无法确定加载顺序的一种结构性问题。在 Go 语言中，循环依赖特指 import 语句形成的环状引用链。
核心定义： 当包 A 直接或间接导入了包 B，而包 B 又直接或间接导入了包 A，就构成了循环依赖。
循环依赖有三种常见形态：
| 形态 | 描述 | 示例 |
|---|---|---|
| 直接循环 | 两个包互相导入 | pkgA → pkgB → pkgA |
| 间接循环 | 三个或以上包形成环 | pkgA → pkgB → pkgC → pkgA |
| 隐式循环 | 通过接口、函数参数或全局变量间接引用 | pkgA 调用 pkgB 方法，pkgB 回调 pkgA 注册的函数 |
1.2 为什么循环依赖是Go项目中的常见故障？
Go 语言在编译层面严格禁止循环导入。当编译器检测到 import 环时，会直接报错并终止编译。这与其他一些语言（如 Java、C++）允许循环依赖但可能引发运行时问题不同，Go 的循环依赖是编译期硬性故障。
循环依赖在 Go 项目中频繁出现，主要原因包括：
- 领域边界模糊：团队在划分包（package）职责时，没有遵循单一职责原则，导致两个包互相需要对方的类型或函数。
- 过度使用全局状态：全局变量、单例模式或共享注册表容易在包之间形成隐式耦合。
- 分层架构被打破：在经典的三层架构（handler → service → repository）中，如果下层包反向引用上层包，就会形成环。
- 接口定义位置不当：将接口定义在消费者包而非生产者包中，容易导致双向依赖。
- 缺乏依赖注入：直接通过
import硬编码依赖，而不是通过接口或函数参数解耦。
常见误区： 很多开发者认为循环依赖只是“编译报错，改一下就好”。实际上，循环依赖往往是架构腐化的信号，表明包的职责边界已经混乱，如果不及时重构，后续的维护成本会指数级上升。
1.3 循环依赖的典型症状
当 Go 项目出现循环依赖时，你会看到类似以下的编译错误：
import cycle not allowed
package myapp/handler
imports myapp/service
imports myapp/repository
imports myapp/handler除了编译错误，循环依赖还会引发以下问题：
| 问题类型 | 具体表现 | 影响程度 |
|---|---|---|
| 编译失败 | import cycle not allowed 错误 |
致命，无法构建 |
| 初始化顺序不可控 | 即使通过某些技巧绕过编译检查，运行时 init() 函数执行顺序也不确定 |
高，可能导致空指针或状态不一致 |
| 测试困难 | 无法单独 mock 或 stub 依赖包，单元测试需要加载整个环 | 中，降低测试效率 |
| 重构成本高 | 修改一个包可能引发环内所有包的连锁变更 | 高，阻碍迭代速度 |
1.4 本课程的学习目标
通过本课程，你将掌握以下核心能力：
- 识别能力：快速定位 Go 项目中的循环依赖及其根因。
- 诊断能力：使用
go mod graph、静态分析工具和依赖可视化手段分析依赖关系。 - 修复能力：掌握接口隔离、依赖注入、事件驱动、适配器模式等 6 种主流解环方案。
- 预防能力：在项目初期建立领域边界规范，从架构层面避免循环依赖。
- 实战能力：通过 3 个真实项目案例（微服务、单体应用、遗留系统）演练完整的故障排查流程。
1.5 适用人群
本课程适合以下读者：
- Go 后端开发工程师（1-5 年经验）：希望提升项目架构能力和故障排查效率。
- 技术负责人 / 架构师：需要制定团队依赖管理规范，预防架构腐化。
- 代码审查者：希望在 CR 阶段快速识别循环依赖风险。
- 从其他语言转 Go 的开发者：理解 Go 在依赖管理上的独特约束和最佳实践。
前置要求： 读者应具备 Go 语言基础语法知识，了解
package 和 import 机制，有至少一个 Go 项目的开发经验。