排查循环依赖错误需先识别加载时依赖关系，再通过生成依赖图定位循环链，最后用按需加载、提取公共契约和依赖倒置解耦。
排查 requires 循环依赖错误，核心在于识别“谁在加载时需要谁”，而不是运行时行为。这类错误常见于构建系统（如 maven/gradle）、模块打包（go modules、node.js commonjs）或依赖注入框架（spring、fastapi）中，本质是编译期或初始化阶段无法解析依赖顺序。重构变量引用逻辑的关键不是绕过限制，而是让依赖方向清晰、单向、可推导。
定位循环链：从报错日志和依赖图入手
直接看错误信息中的模块名和调用路径，例如：
- Maven 报错提示
cycle detected: A -> B -> C -> A，说明构建器已识别闭环； - Go 编译报错
import cycle not allowed后紧跟两个包路径，就是最短循环链； - Node.js 启动时报
Cannot access 'xxx' before initialization，大概率是 CommonJS 模块在require阶段访问了未导出完的变量。
用工具生成依赖图能快速暴露隐性路径：
- Go：执行
go list -f '{{.ImportPath}} -> {{join .Deps "\n\t-> "}}' ./... | grep -E "(A|B)"查找 A/B 相关引用； - Java/Maven：运行
mvn dependency:tree -Dverbose | grep -A 10 "circular"； - Node.js：使用
madge --circular --extensions js,ts ./src扫描源码。
解耦变量引用：避免顶层直接导出互依赖值
循环常源于模块顶部导出的变量被对方直接 require/import —— 这类引用在加载阶段就锁死，无法延迟。例如 config.js 导出一个对象，logger.js 又在顶层 require 它并立即读取字段，而 logger 本身又被 config require。
改法很简单：把变量访问移到函数体内，变成“按需加载”：
- 不写
const config = require('./config')在文件顶部； - 改为在具体函数里写
const { level } = require('./config')； - 或者更推荐：把 config 提取为独立配置服务，由上层统一注入，下层只依赖接口。
这样变量不再参与模块加载顺序判定，循环链自然断开。
提取公共契约：用 interface / types / constants 包承接共享定义
当 A 和 B 都要用同一个结构体、枚举或常量，不要让 A import B 的类型、B 再 import A 的常量。应该新建一个 shared 或 types 包，只放纯定义，不包含任何逻辑或实现。
- Go 中：新建
pkg/types，放type UserID string、const StatusActive = "active"； - Java 中：建
common-model模块，仅含@Data实体类和enum； - TypeScript 中：建
types/index.ts，导出interface User和type Role = 'admin' | 'user'。
A 和 B 都只 import 这个包，彼此不再有直接依赖关系。
重构依赖流向：让调用方持有接口，被调用方实现它
如果 A 调用 B 的某个方法，B 又要回调 A 的某个通知逻辑，这不是“互相需要”，而是 A 需要 B 的能力 + B 需要 A 的策略。应把 A 的策略抽象成接口，由 B 接收该接口实例，而非导入 A 包。
- A 包内定义
type EventHandler interface { OnSuccess(data interface{}) }； - B 包实现业务逻辑，接收
handler EventHandler作为参数； - A 创建 B 实例时传入自己的实现：
b := NewB(a)（a 实现了 EventHandler）； - B 不 import A，只依赖 A 定义的接口 —— 依赖方向变为 A → interface ← B。
这种“依赖倒置”是消除循环最稳健的设计手段，也便于单元测试和替换实现。
