typescript-circular-dependency

此技能提供了一套系统化的方法，用于诊断和修复 TypeScript 与 JavaScript 项目中的循环依赖问题。当模块之间直接或间接互相导入时，会发生循环依赖，导致运行时因模块尚未完成初始化而使导出值变为 undefined。此工具适用于在复杂模块化代码库中工作的软件工程师，他们常遇到因导入顺序不同而导致间歇性运行时 TypeError 或 ReferenceError 的问题。

• 使用 madge 库进行自动循环检测，以可视化并识别出问题的依赖图。

• 针对常见架构问题（如服务对服务循环、index.ts 桶装文件污染、过度的类型与数值耦合）提供基于模式的诊断策略。

• 实际解决方案，包括依赖注入、将共用类型提取至专用接口文件，以及使用动态导入来打破同步依赖链。

• 实施仅类型导入（Type-only imports），以消除仅供接口使用的依赖项在运行时的负担。

• 提供 CI/CD 集成指南，通过将循环依赖检查嵌入自动化构建脚本或 ESLint 配置中，防止未来的回归问题。

• 目标情境包含运行时 ReferenceErrors、意外的 undefined 导出，以及尽管编译有效但测试却因模块解析问题而失败的情况。

• 建议用于使用 Jest、Vitest、Webpack 或 Vite 等框架的开发者，这些框架的模块解析时机与标准 TS 编译不同。

• 用户需提供源目录作为输入，并准备好将共享逻辑重构为解耦模块。

• 限制条件包括解耦紧密耦合服务时可能需要的重构工作，以及在大型项目中维护一致导入模式的需求。