SuperAPI AI 工具集

typescript-circular-dependency

编程与开发

查看项目

更新于 10-16 06:38

技能介绍

用途

该技能用于检测并解决 TypeScript/JavaScript 项目中的循环导入依赖问题。循环依赖会出现在模块 A 导入模块 B、而 B 又直接或间接导入 A 的情况下。TypeScript 编译可以通过,但运行时某个导入会因模块尚未完成初始化而求值为 undefined。

触发场景

常见错误信息:

  • ReferenceError: Cannot access 'UserService' before initialization
  • TypeError: Cannot read properties of undefined (reading 'create')
  • TypeError: (0 , _service.doSomething) is not a function

提示存在循环导入的症状:

  • 导出确实存在,但导入却是 undefined
  • 错误只在运行时出现,不在 TypeScript 编译期间出现
  • 移动 import 语句会改变哪一个导入变为 undefined
  • 测试失败但应用正常(或相反)
  • 在文件顶部添加 console.log 会改变行为

第一步:检测循环

使用工具可视化依赖关系:

# 安装 madge
npm install -g madge

# 查找循环依赖
madge --circular --extensions ts,tsx src/

# 生成可视化图
madge --circular --image graph.svg src/

或使用 TypeScript 编译器:

# 检查循环(需要 tsconfig 设置)
npx tsc --listFiles | head -50

第二步:识别模式

常见的循环依赖模式:

  • 模式 A:服务对服务:services/userService.ts → services/orderService.ts → services/userService.ts
  • 模式 B:类型导入:types/user.ts → types/order.ts → types/user.ts
  • 模式 C:索引 barrel 文件:components/index.ts → components/Button.tsx → components/index.ts

第三步:解决策略

策略 1:抽取共享依赖

处理前:

// userService.ts
import { OrderService } from './orderService';
export class UserService { ... }

// orderService.ts  
import { UserService } from './userService';
export class OrderService { ... }

处理后:

// types/interfaces.ts(新文件——不从 services 导入)
export interface IUserService { ... }
export interface IOrderService { ... }

// userService.ts
import { IOrderService } from '../types/interfaces';
export class UserService implements IUserService { ... }

策略 2:依赖注入

// orderService.ts
export class OrderService {
  constructor(private userService: IUserService) {}
  
  // 而不是直接导入 UserService
}

// main.ts
const userService = new UserService();
const orderService = new OrderService(userService);

策略 3:动态导入

// 只在需要时导入,而不是在模块顶层
async function processOrder() {
  const { UserService } = await import('./userService');
  // ...
}

策略 4:使用仅类型导入

如果只需要类型(而非值),使用仅类型导入:

// 这不会创建运行时依赖
import type { User } from './userService';

策略 5:重构 barrel 文件

处理前(有问题):

// components/index.ts
export * from './Button';
export * from './Modal';  // Modal 从 './index' 导入 Button

处理后:

// components/Modal.tsx
import { Button } from './Button';  // 直接导入,而非从 index 导入

第四步:防止未来出现循环

添加到 CI/构建流程:

// package.json
{
  "scripts": {
    "check:circular": "madge --circular --extensions ts,tsx src/"
  }
}

或配置 ESLint:

// .eslintrc.js
module.exports = {
  plugins: ['import'],
  rules: {
    'import/no-cycle': ['error', { maxDepth: 10 }]
  }
};

验证

  • 运行 madge --circular src/ ——应报告无循环
  • 运行测试套件——之前为 undefined 的导入应正常工作
  • 删除 node_modules 并重新安装——应用仍应正常工作
  • 生产构建——无运行时错误

示例

问题:OrderService 在 UserService 中被导入时为 undefined

检测:

$ madge --circular src/
Circular dependencies found!
  src/services/userService.ts → src/services/orderService.ts → src/services/userService.ts

修复:抽取共享接口

// 新增:src/types/services.ts
export interface IOrderService {
  createOrder(userId: string): Promise<Order>;
}

// 修改:src/services/userService.ts
import type { IOrderService } from '../types/services';

export class UserService {
  constructor(private orderService: IOrderService) {}
}

// 修改:src/services/orderService.ts  
// 不再导入 UserService
export class OrderService implements IOrderService {
  async createOrder(userId: string): Promise<Order> { ... }
}

注意事项

  • TypeScript 的 import type 很有用——它在运行时被擦除,不会造成循环
  • Barrel 文件(index.ts)是意外循环的常见来源
  • 当存在循环时,文件中导出的顺序可能有影响
  • Jest/Vitest 处理模块解析的方式可能与打包工具不同
  • 某些打包工具(Webpack、Vite)对循环的处理比其他工具更好
  • require() 有时会掩盖 import 暴露出的循环依赖问题