Codex CLI 代码重构指南：安全重构工作流与实战技巧

代码重构是软件工程中最高风险的操作之一——修改已运行的代码，在不改变外部行为的前提下改善内部结构。Codex CLI 通过沙箱隔离、逐步审查和自动测试，将重构风险降到最低。本指南覆盖从单函数提取到 10 万行 TypeScript 迁移的完整重构工作流。

1. 为什么用 AI 重构代码？

手动重构的核心风险在于：人类难以在修改代码的同时保持所有行为不变，尤其是跨文件的命名重构、大型函数拆分等操作极易引入遗漏。Codex CLI 通过以下机制显著降低重构风险：

• 沙箱隔离：每次操作在独立沙箱中执行，对原始代码库没有直接影响，直到你明确确认才应用
• 全局一致性：跨文件重命名时，Codex 会扫描所有引用点，确保不遗漏
• 测试驱动验证：可以在同一任务中先生成测试、再重构、再运行测试，形成闭环
• 可审查的 diff：在 suggest 模式下，每个改动以 diff 形式呈现，人工确认后才应用

2. 安全重构五步工作流

无论重构范围大小，遵循以下五步工作流可以将风险降到最低，同时保持最高的操作效率。

第一步：用 dry-run 评估改动范围

在执行任何实际修改之前，先用 --dry-run 参数了解 Codex 计划做什么：

# 预览重构方案，不做实际修改
codex exec --dry-run "重构 UserService 类：
- 把 createUser、updateUser、deleteUser 拆分为独立模块
- 提取公共的参数验证逻辑到 validateUserInput 函数
- 保持所有公开方法签名不变"

# 查看将会涉及哪些文件
codex exec --dry-run "把 src/utils.ts 中超过 50 行的函数全部提取到独立文件"

dry-run 输出会告诉你：将要修改哪些文件、新增哪些文件、删除哪些文件，以及预估的改动行数。这让你在付出实际代价之前就能判断重构方案是否合理。

第二步：创建 git 分支保护现有代码

# 创建专用重构分支
git checkout -b refactor/extract-user-service

# 也可以让 Codex 帮你创建分支并执行重构
codex exec "创建 git 分支 refactor/user-service，然后重构 src/services/user.ts：
把超过 80 行的 processUserData 函数拆分为三个独立函数，
分别处理数据验证、数据转换和数据存储"

第三步：在 suggest 模式下逐步审查

# suggest 模式（默认）——展示 diff 等待确认
codex "提取 src/api/users.ts 中的重复错误处理代码到 handleApiError 函数，
放在 src/utils/errors.ts，更新所有调用处的 import"

# 查看 diff 后，选择应用或跳过每个改动

第四步：运行测试验证行为不变

# 应用 Codex 的改动后，立即运行测试
npm test

# 或者让 Codex 在重构完成后自动运行测试
codex exec "重构 UserService，完成后运行 npm test，
如果有测试失败，列出失败原因并修复"

第五步：Code Review 再合并

# 查看完整的分支 diff
git diff main..refactor/extract-user-service

# 创建 PR（如果使用 GitHub）
gh pr create --title "refactor: extract UserService into modules" \
  --body "Codex 辅助重构，测试全部通过，行为无变化"

# 确认无误后合并
git merge refactor/extract-user-service

3. 三种核心重构场景

场景一：函数提取（Extract Function）

将大函数中的某段逻辑提取为独立函数，是最常见的重构操作。以下是一个典型的提取流程：

# 识别并提取：让 Codex 找出可以提取的逻辑
codex "分析 src/checkout/payment.ts 中的 processPayment 函数（约 120 行），
识别其中可以提取为独立函数的逻辑块，生成提取方案（不要执行，只列出建议）"

# 执行提取：按照方案逐步提取
codex "提取 processPayment 中的卡号验证逻辑为 validateCardNumber(cardNumber: string): boolean，
保持原有的 processPayment 调用 validateCardNumber，不改变函数的外部行为"

codex "提取 processPayment 中的金额计算逻辑为 calculateFinalAmount(items, discounts, tax): number，
包括折扣计算和税率应用，保持原函数调用新函数"

场景二：命名重构（统一命名约定）

项目积累了不一致的命名风格时，跨文件重命名是最容易引入 Bug 的操作，也是 Codex 最有优势的场景：

# 统一变量命名：camelCase
codex "扫描 src/ 目录下所有 TypeScript 文件，
把所有使用 snake_case 的变量名和函数名改为 camelCase，
不要修改：对象的 key（因为可能来自 API）、文件名、类名"

# 重命名特定函数（跨文件）
codex "把 getUserData 函数重命名为 fetchUserProfile，
更新 src/ 下所有调用处（包括测试文件），
同时更新相关的注释和文档字符串"

# 统一接口命名：I 前缀
codex "把 src/types/ 下所有不以 I 开头的 interface 添加 I 前缀（如 User → IUser），
更新所有引用这些接口的文件"

场景三：文件拆分（Split Large Files）

当单个文件超过 1000 行时，维护成本急剧上升。以下是将大文件拆分为模块的标准流程：

# 第一步：分析文件职责
codex "分析 src/api.ts（约 1200 行），识别其中有几个独立的职责领域，
建议如何按职责拆分为多个文件，给出文件结构建议（不执行）"

# 第二步：按职责逐步拆分
codex "把 src/api.ts 中的用户相关 API（createUser、getUser、updateUser、deleteUser）
提取到 src/api/users.ts，保持 src/api.ts 中的 re-export 以兼容现有 import"

codex "把 src/api.ts 中的产品相关 API 提取到 src/api/products.ts，
同样在 src/api.ts 中保持 re-export"

# 第三步：清理入口文件
codex "src/api.ts 现在只有 re-export，把它转换为标准 barrel 文件（index 风格），
更新直接从 src/api.ts import 具体函数的调用处，改为从子模块 import"

4. TypeScript 迁移重构

将 JavaScript 项目迁移到 TypeScript 是一种特殊的重构：不改变运行时行为，只添加静态类型信息。Codex CLI 可以大幅加速这一过程。

添加类型注解

# 批量添加基础类型注解
codex "把 src/utils/string.js 改为 TypeScript：
- 重命名为 string.ts
- 为所有函数参数和返回值添加类型注解
- 使用精确类型（不要用 any）
- 不改变任何业务逻辑"

# 为已有的 JS 文件生成独立的 .d.ts 声明文件（渐进式迁移）
codex "为 src/legacy/payment.js 生成 TypeScript 声明文件 payment.d.ts，
通过分析函数的实际调用模式推断类型"

修复 any 类型

# 找出并修复 any 类型
codex "扫描 src/ 下所有 TypeScript 文件，找出所有使用 any 的地方，
对于能推断出具体类型的，替换为精确类型；
对于确实无法确定类型的，替换为 unknown 并添加 TODO 注释说明原因"

# 修复特定文件的 any
codex "修复 src/services/api.ts 中的所有 any 类型：
- API 响应类型参考 src/types/api.ts 中已有的接口定义
- 事件处理函数参数使用正确的 DOM 事件类型
- 第三方库回调参数查看库的类型定义"

接口抽取

# 从实现中提取接口
codex "分析 src/services/UserService.ts，
为 UserService 类提取 IUserService 接口（只包含公开方法），
放在 src/interfaces/IUserService.ts，
让 UserService 实现这个接口（implements IUserService），
更新依赖 UserService 的代码改为依赖接口（面向接口编程）"

# 从 JSON 数据推断接口
codex "根据 src/mock/user-response.json 中的数据结构，
在 src/types/user.ts 中生成对应的 TypeScript 接口，
处理可选字段（用 ? 标注可能为 null 的字段）"

5. 测试驱动重构（TDD 重构）

TDD 重构的核心理念：先有测试覆盖，再动代码。测试是重构的安全网——有了测试，重构就变成了一件有保障的事。

第一步：让 Codex 生成测试覆盖现有行为

# 为准备重构的代码生成全面的测试
codex "为 src/services/order.ts 中的 calculateOrderTotal 函数生成完整的单元测试：
- 覆盖正常情况（有折扣/无折扣/多件商品）
- 覆盖边界情况（空购物车/金额为 0/超大金额）
- 覆盖错误情况（无效商品 ID/负数数量）
测试文件放在 src/services/__tests__/order.test.ts，使用 Jest"

# 确认测试全部通过（验证测试本身正确）
npm test src/services/__tests__/order.test.ts

第二步：执行重构

# 测试通过后，执行重构
codex "重构 src/services/order.ts 中的 calculateOrderTotal 函数：
- 提取折扣计算逻辑为 applyDiscounts(items, discounts)
- 提取税率计算逻辑为 applyTax(subtotal, taxRate)
- 主函数只做编排，不含具体计算逻辑
- 保持函数签名不变：calculateOrderTotal(items, options): number"

第三步：验证测试仍然通过

# 重构后运行测试，确保行为不变
npm test src/services/__tests__/order.test.ts

# 如果有失败，让 Codex 分析原因
codex "测试失败了，错误信息是：[粘贴错误信息]
分析重构后的 calculateOrderTotal 与原实现的行为差异，修复使测试通过，
不要修改测试本身"

# 运行完整测试套件，确保没有其他影响
npm test

6. AGENTS.md 重构专项配置

对于有持续重构需求的项目，在 AGENTS.md 中配置重构规范，可以让 Codex 在每次会话中自动遵循项目约定，无需重复解释。

## 重构规范
- 每次重构后运行 `npm test` 验证行为不变
- 不得删除公开 API，只能添加（向后兼容原则）
- 遵循项目命名约定：camelCase 变量，PascalCase 类，UPPER_SNAKE_CASE 常量
- 重构前先阅读 CHANGELOG.md 了解历史决策，避免重复已被放弃的方案
- 提取的工具函数放在 src/utils/，服务类放在 src/services/
- 新建文件时同步创建 __tests__/ 目录下的测试文件
- 不允许在重构中引入新的外部依赖

## 重构进度追踪
- 已完成模块记录在本文件末尾的"重构进度"章节
- 进行中的模块标注 🔄，待处理标注 ⬜，已完成标注 ✅

将以上内容保存到项目根目录的 AGENTS.md 文件中（如果已存在则追加到适当章节）。之后每次运行 Codex 重构任务，这些规范都会自动生效。

7. 50 行以上函数的拆分策略

函数长度本身不是问题，但超过一定长度后，函数往往承担了多个职责，这才是真正需要重构的信号。以下是按函数规模制定拆分策略的完整指南。

第一步：识别函数职责

# 让 Codex 分析函数的职责
codex "分析 src/controllers/checkout.ts 中的 handleCheckout 函数（约 180 行），
列出它承担的所有职责（每个职责用一句话描述），
并指出哪些职责之间有较强耦合、哪些可以独立提取"

第二步：生成提取方案（dry-run）

# 基于职责分析，生成具体的提取方案
codex exec --dry-run "根据职责分析，为 handleCheckout 生成函数提取方案：
- 每个提取的函数要有明确的名字（动词+名词）
- 确定参数和返回值类型
- 说明提取顺序（先提取无依赖的，再提取有依赖的）
不执行，只输出方案"

第三步：逐职责提取

# 一次提取一个职责，每次验证
codex "提取 handleCheckout 中的库存检查逻辑为 checkInventoryAvailability(items): Promise<void>，
该函数应抛出 InsufficientStockError 如果库存不足，
在 handleCheckout 中替换为调用新函数"

npm test  # 每次提取后立即验证

codex "提取 handleCheckout 中的支付处理逻辑为 processPaymentTransaction(paymentInfo, amount): Promise<string>，
返回交易 ID，在 handleCheckout 中替换"

npm test

8. 常见问题 FAQ

Codex 重构会改变函数行为吗？

不会，前提是你在提示词中明确要求"行为不变"或"保持函数签名不变"。Codex 在重构时会保持函数的输入输出完全一致，只调整内部结构。但语言模型并非完美，为了绝对保险，建议每次重构后运行测试套件验证。在提示词中加入"重构后运行 npm test 确认测试通过"是最佳实践。

如何保证重构不引入 Bug？

三重保障策略：

1. 预览阶段：用 --dry-run 查看改动范围，确认没有超出预期
2. 隔离阶段：在 git 分支上操作，重构失败随时 git checkout . 还原
3. 验证阶段：重构前生成测试覆盖，重构后运行测试确认行为不变

在 AGENTS.md 中写明"每次重构后运行 npm test"，让 Codex 在每个重构任务中自动执行验证，无需手动提醒。

重构大型项目（10 万行）可行吗？

完全可行，但必须采用增量策略，不能尝试一次性重构整个代码库。推荐做法：按模块分批重构，每次专注 200–500 行；从叶节点（依赖最少的工具函数）开始，逐步向核心模块推进；在 AGENTS.md 中记录重构进度（已完成/进行中/待处理），保持跨会话的上下文连贯。对于超大型代码库，用 GPT-4.1 的 1M token 上下文（codex --model gpt-4.1）处理依赖关系复杂的模块效果更好。

重构时 Codex 读取哪些文件？

Codex 会自动读取：(1) 提示词中明确提到的文件；(2) 通过静态分析发现的直接依赖文件（import 链）；(3) 相关的测试文件（如果存在）。你可以通过 --context 参数强制包含特定文件（如架构文档或类型定义），也可以用 .codexignore 排除不需要读取的目录。在 suggest 模式下，Codex 会在执行前显示所有将要修改的文件列表，这也间接告诉你读取了哪些文件。