使用 Codex 修改中大型项目时，经常会遇到一种不容易立即发现的问题：功能可以运行，代码也能通过部分测试，但模块之间的依赖关系开始越来越复杂。

常见表现包括：

• 修改用户模块后，订单模块也必须跟着调整；

• 工具层反向引用业务层；

• 两个服务互相导入，启动时出现 undefined；

• 删除一个文件后，多个无关模块同时报错；

• TypeScript 类型检查正常，运行时却无法完成初始化；

• 为了复用一个函数，引入了一整条不必要的依赖链；

• Codex 每修复一次循环引用，又在其他位置增加新的中间层。

这类问题通常不是某一行代码写错，而是项目的模块边界已经被破坏。

一、什么是循环依赖？

假设项目中存在两个模块：

userService
→ 引用 orderService

orderService
→ 又引用 userService

此时两个模块互相依赖，就形成了循环引用。

JavaScript 或 TypeScript 项目中，循环依赖不一定立即报错。有些场景下项目仍能启动，但模块初始化顺序可能发生变化。

例如：

// user.service.ts
import { getOrderCount } from "./order.service";

export function getUserSummary(userId: number) {
  return {
    userId,
    orderCount: getOrderCount(userId)
  };
}

// order.service.ts
import { getUserSummary } from "./user.service";

export function getOrderCount(userId: number) {
  const user = getUserSummary(userId);
  return user ? 10 : 0;
}

这两个文件互相导入，运行时可能出现函数尚未初始化、返回值为 undefined，甚至递归调用无法结束。

二、为什么Codex容易引入循环依赖？

Codex 通常根据当前任务寻找“最短实现路径”。

例如开发者要求：

在订单列表中显示用户等级。

Codex 发现用户等级逻辑已经存在于 userService，于是让 orderService 直接引用它。

但如果 userService 本身已经依赖订单数据，就形成了反向引用。

开发者熟悉项目整体结构，知道哪些模块属于底层、哪些模块属于业务层；Codex 如果没有明确架构规则，更容易根据局部代码完成复用，而忽略长期依赖方向。

三、先画出项目依赖方向

排查循环依赖前，可以先把项目划分为几个层级：

接口层
↓
业务服务层
↓
领域或核心逻辑层
↓
基础设施层

一个比较稳定的依赖方向是：

Controller
→ Service
→ Repository
→ Database

通常不应该出现：

Repository
→ Service

基础工具
→ 具体业务模块

公共类型
→ 页面组件

底层模块如果反向引用高层业务，后续几乎一定会增加耦合。

可以让 Codex 在修改前先输出：

请先不要修改代码。

分析当前任务涉及的模块，并说明：

1. 每个模块属于哪一层；
2. 当前依赖方向；
3. 是否存在反向依赖；
4. 修改后会不会形成循环引用；
5. 哪些公共逻辑应该下沉。

四、不要用“公共工具”隐藏业务逻辑

有些循环依赖被发现后，Codex 可能会把函数移动到 utils 中：

userService
orderService
↓
utils/common.ts

如果 common.ts 里放的是纯格式转换或通用计算，这种处理没有问题。

但如果它包含：

• 用户权限判断；

• 订单状态流转；

• 数据库查询；

• 业务对象组合；

• 特定接口调用；

它就不再是真正的工具模块，只是换了一个名字继续承载业务耦合。

工具层应该尽量保持：

• 无业务状态；

• 无数据库依赖；

• 无具体页面依赖；

• 输入和输出明确；

• 可以独立测试。

五、把共享逻辑放到更低层

如果用户模块和订单模块都需要某段逻辑，可以考虑抽取到更底层的领域服务。

例如：

userService
orderService
    ↓
customerPolicy

customerPolicy 只负责用户等级、订单数量和规则计算，不反向依赖两个上层服务。

示例：

export function calculateCustomerLevel(
  orderCount: number,
  totalAmount: number
) {
  if (orderCount > 20 && totalAmount > 10000) {
    return "vip";
  }

  return "normal";
}

用户模块和订单模块都可以使用它，但它不需要知道具体数据库或页面结构。

六、通过依赖倒置减少直接引用

有时两个模块确实需要协作，但不应该互相导入具体实现。

可以通过接口进行隔离。

export interface UserReader {
  getUserLevel(userId: number): Promise<string>;
}

订单模块只依赖接口：

export class OrderService {
  constructor(
    private readonly userReader: UserReader
  ) {}

  async getOrderDetail(userId: number) {
    const level =
      await this.userReader.getUserLevel(userId);

    return { level };
  }
}

真正实现由外部注入。

这样订单模块不需要直接引用完整的用户服务，也更容易进行单元测试。

七、事件机制适合降低跨模块耦合

如果订单创建后，需要通知用户模块更新统计，不一定要直接调用：

orderService
→ userService.updateStatistics()

可以发布事件：

order_created

用户模块监听事件后自行处理。

这种方式适合：

• 订单创建后更新积分；

• 用户注册后发送通知；

• 支付成功后生成报表；

• 文件上传后触发异步处理。

但事件机制也会增加排查难度，因此需要明确：

• 事件名称；

• 消息结构；

• 消费失败策略；

• 是否允许重复消费；

• 日志与 Trace ID。

不要为了避免一个简单的函数引用，就过度引入复杂消息系统。

八、如何快速发现循环依赖？

除了人工阅读代码，还可以使用项目依赖分析工具。

重点关注：

• 互相导入的文件；

• 底层包引用上层包；

• 公共模块引用具体页面；

• 同一模块出现多条反向路径；

• 包之间形成闭环。

也可以先让 Codex 根据导入语句生成依赖清单：

请分析 src 目录中的 import 关系。

输出：

1. 直接循环依赖；
2. 间接循环依赖；
3. 跨层反向引用；
4. 风险最高的5条依赖链；
5. 最小改动方案。

不要直接要求它“自动修复所有循环依赖”，因为大范围移动文件可能引入更多路径和构建问题。

九、一次只处理一条依赖链

例如发现：

userService
→ orderService
→ reportService
→ userService

不要同时重构三个模块。

可以先找到依赖环中最不合理的一条边，例如：

reportService
→ userService

然后判断：

• 能否只传入必要数据；

• 能否抽取接口；

• 能否下沉计算逻辑；

• 能否通过事件处理；

• 是否属于真正必要的依赖。

每次只断开一条环，修改后立即运行测试和构建，更容易控制风险。

十、把依赖规则写入AGENTS.md

长期使用 Codex 的项目，可以增加：

# 模块依赖规则

- Controller可以依赖Service
- Service可以依赖Repository
- Repository不能反向依赖Service
- 公共工具不得包含具体业务流程
- 类型包不能依赖页面或组件
- 禁止两个业务Service互相直接导入
- 跨模块协作优先使用接口或明确事件
- 修改公共模块前必须检查所有引用
- 发现循环依赖时只处理最小依赖链
- 修改完成后必须运行类型检查和构建

这样可以让 Codex 在生成代码时优先遵循现有架构，而不是只追求局部复用。

十一、修改后要验证哪些内容？

断开循环依赖后，至少需要检查：

npm run lint
npm run type-check
npm run test
npm run build

同时检查：

• 模块初始化是否正常；

• 是否出现新的 undefined；

• 是否增加重复实现；

• 公共接口是否保持兼容；

• 测试是否仍然可以独立运行；

• 是否产生新的跨层引用；

• 构建产物是否包含错误依赖。

如果项目支持依赖图生成，还应重新生成一次，确认原来的环已经消失。

十二、Plus与Pro怎么选？

如果主要使用 Codex 完成：

• 单文件修改；

• 小型模块重构；

• 简单依赖排查；

• 类型错误修复；

• 中小项目的导入关系分析；

Plus 通常已经能够覆盖多数需求。

如果日常需要：

• 分析完整代码仓库；

• 处理多层循环依赖；

• 连续进行跨模块重构；

• 多轮运行测试与构建；

• 同时维护多个大型项目；

• 长时间保留架构上下文；

则可以根据任务中断频率和实际开发强度评估 Pro。

Pro 更适合高频、长任务和复杂仓库场景，但更大的使用空间不能替代清晰的模块边界。项目规则不明确时，Codex 仍可能继续产生新的依赖环。

总结

Codex 越改项目依赖越乱，通常不是因为代码无法运行，而是局部复用逐渐破坏了整体依赖方向。

通过建立依赖层级、识别反向引用、下沉共享逻辑、使用接口隔离，并一次只处理一条依赖链，可以降低循环依赖和模块耦合。

真正稳定的项目架构，不是所有模块都可以互相调用，而是每个模块都清楚自己应该依赖谁，以及哪些依赖绝不能反向出现。

CSDN文章描述

本文介绍使用 Codex 修改项目时，如何通过依赖图、模块分层、依赖倒置、事件机制和 AGENTS.md 规则，解决循环依赖与模块耦合问题，并分析 ChatGPT Plus 与 Pro 的适用场景。

推荐标签

循环依赖
依赖倒置
软件架构
TypeScript