Codex 教程
用 Codex 重构项目
用 Codex 重构项目的完整指南，覆盖重构目标、行为保护、依赖关系分析、分阶段改动、验证命令、API 配置边界、Diff 审查和常见误区。
用 Codex 重构项目，适合在功能稳定后整理结构、减少重复、拆分模块、改善命名或降低维护成本。重构的前提是行为不变，并且有测试、构建或人工验收步骤证明行为仍然正确。
好的重构不是“把代码改得更像某种风格”，而是让下一次修改更容易、更安全、更好 review。Codex 可以承担读代码、画依赖关系、提取重复逻辑和跑验证的苦活，但重构边界要由你写清楚。
| 项目 | 说明 |
|---|---|
| 阅读时间 | 约 6 分钟 |
| 更新时间 | 2026-07-03 |
| 适合读者 | 开发者、技术负责人、独立项目维护者、正在让 Codex 接手旧项目的人 |
| 你会获得 | 重构判断表、依赖分析流程图、可复制 Goal Prompt、分阶段路线、Diff 审查清单和 API 接入边界 |
| 场景 | 适合程度 | 重构目标 | 前提 |
|---|---|---|---|
| 拆分过大的组件 | 高 | 让视图、状态和副作用分层 | 有视觉和交互验收 |
| 提取重复逻辑 | 高 | 减少重复分支和复制粘贴 | 有单元测试或样例输入 |
| 整理 API 客户端 | 高 | 统一错误、超时、日志和配置 | 不改变调用方协议 |
| 改善命名和目录 | 中 | 降低阅读成本 | 能全局搜索引用 |
| 更换状态管理 | 中 | 减少隐式状态和跨层耦合 | 分阶段迁移 |
| 重写架构 | 低 | 需要设计方案，不应直接改代码 | 需要人工评审和迁移计划 |
什么时候先别重构
Section titled “什么时候先别重构”| 信号 | 原因 | 更合适的动作 |
|---|---|---|
| 需求仍在变 | 重构目标会反复漂移 | 先稳定需求和接口 |
| 没有复现或验收路径 | 行为变化难发现 | 先补测试或验收清单 |
| 线上事故未关闭 | 改动范围会干扰修复 | 先修 Bug，再单独重构 |
| 涉及生产数据迁移 | 风险不只在代码层 | 先写迁移设计和回滚方案 |
| 需要换框架 | 这通常是架构迁移 | 拆成设计、试点、迁移阶段 |
Martin Fowler 对重构的经典定义强调：它是一系列保持行为不变的小步转换，用来改善既有代码的设计。把这个原则放进 Codex Goal 里，可以显著减少“顺手改需求”的风险。
重构安全闭环
Section titled “重构安全闭环”推荐目录结构
Section titled “推荐目录结构”project/ src/ components/ lib/ hooks/ services/ tests/ docs/ AGENTS.md重构前先让 Codex 列出依赖关系、调用路径、导出接口和副作用边界。不要直接让它移动文件；先确认哪些路径被外部引用、哪些行为必须保持、哪些验证命令可以证明结果。
可复制 Goal Prompt
Section titled “可复制 Goal Prompt”Goal: 重构 [模块/页面/组件]，在不改变用户可见行为和公开接口的前提下提升可维护性。
Context:- 目标路径：[填写文件或目录]- 当前痛点：[重复逻辑 / 文件过大 / 命名混乱 / API 客户端分散]- 必须保持的行为：[列出用户路径、API 响应、配置项或输出]- 验证命令：[npm test / npm run build / npm run check / 其他]
请先读取：- 目标文件和调用方- 现有测试、快照、Storybook、README 或验收说明- AGENTS.md 中的项目规则- package.json 中的验证命令
要求：- 先输出依赖关系、重构计划、风险点和分阶段顺序。- 每个阶段只服务一个目标，例如“提取工具函数”或“拆分组件”。- 不改变公开 API、路由、环境变量名称、响应结构和用户可见行为。- 不引入新框架或新生产依赖，除非单独说明收益和成本。- 每阶段运行验证命令，并报告结果。- 如果发现需要功能改动，停止并说明应拆成新任务。
Done when:- 测试、构建或人工验收清单通过。- diff 能按阶段阅读。- 行为变化为零，或所有变化都被明确标记为非本次重构。- 给出后续可以单独处理的改进项。OpenAI Codex 官方手册建议在任务中提供 Goal、Context、Constraints 和 Done when，并要求 Codex 验证、测试和 review 自己的改动。重构任务尤其需要这些约束，因为“看起来更干净”的代码不一定等于更安全的代码。
- 写清重构目标和非目标，例如“拆分组件，不改交互”。
- 建立基线：测试、构建、截图、API 样例或人工验收清单。
- 让 Codex 分析依赖关系、调用方、公开导出和副作用。
- 选择一个最小阶段，例如提取纯函数、移动类型、拆分子组件。
- 执行后立即运行相关验证，不把多个阶段攒到一起验。
- 审查 diff，确认没有需求改动、配置改动、隐式行为改动。
- 记录下一阶段建议，但只在当前阶段稳定后继续。
重构决策矩阵
Section titled “重构决策矩阵”| 痛点 | Codex 适合做什么 | 必须保留什么 | 验证方式 |
|---|---|---|---|
| 文件过长 | 按职责拆分组件、hooks、utils | 路由、props、事件和视觉结果 | 组件测试、截图、人工路径 |
| 重复分支 | 提取纯函数或策略表 | 输入输出和错误语义 | 单元测试和边界样例 |
| API 客户端散落 | 集中封装 base URL、超时、错误处理 | 环境变量和调用协议 | mock 测试、smoke test |
| 类型混乱 | 收窄类型、拆分 DTO 和 ViewModel | 对外类型兼容性 | typecheck、调用方编译 |
| 副作用难追踪 | 隔离网络、存储、时间、随机数 | 用户路径和失败处理 | mock、日志、错误用例 |
| 目录不清晰 | 移动文件并更新 import | public export 和文档路径 | 构建、链接检查、搜索引用 |
| 阶段 | 目标 | Codex 输出 | 是否适合提交 |
|---|---|---|---|
| 0. 建立安全网 | 确认现有行为 | 测试命令、截图或验收清单 | 是 |
| 1. 命名和文件整理 | 降低阅读成本 | 更清楚的变量、目录和导出 | 视 diff 大小而定 |
| 2. 提取纯逻辑 | 让核心规则可测试 | lib/ 或 utils/ 中的小函数 |
是 |
| 3. 拆分视图层 | 控制组件复杂度 | 子组件、hooks、局部状态边界 | 是 |
| 4. 统一外部依赖 | 收拢 API、日志、错误处理 | 单一 client 或 service 层 | 是 |
| 5. 删除旧路径 | 清理重复和废弃代码 | 删除说明、迁移备注 | 是，但要单独审查 |
大项目不要追求一次完成。每个阶段都应该能解释“为什么现在做、改了哪些行为边界、用什么证明没有回归”。
示例：拆分过大的页面
Section titled “示例：拆分过大的页面”假设一个 DashboardPage.tsx 同时负责筛选栏、图表、API 请求、错误提示和导出按钮，可以让 Codex 先给出拆分计划，再按阶段执行。
DashboardPage.tsx -> DashboardFilters.tsx -> DashboardChart.tsx -> DashboardExportButton.tsx -> useDashboardData.ts -> dashboard-formatters.ts这个拆分的验收点不是“文件变多了”，而是：
- 页面 URL、筛选参数和默认状态不变。
- 图表数据、加载状态、错误提示和导出结果不变。
- API 请求仍在同一层完成，密钥不会进入前端。
- 测试或人工截图能覆盖主要用户路径。
- diff 中不夹带新需求、新样式方案或无关依赖。
API 配置边界
Section titled “API 配置边界”如果项目中有 AI API 调用，重构时不要改变环境变量名称、密钥读取方式和服务端边界。Base URL 应保持为配置项，而不是写死在业务逻辑深处。
OPENAI_BASE_URL=https://api.ofapp.cn/v1OPENAI_API_KEY=sk-xxxx在 OfApp.cn 场景中，OpenAI / Codex 生态的 Base URL 可以使用 https://api.ofapp.cn/v1。不要在重构中编造模型名、套餐、额度或能力；需要确认时，写明“请以 OfApp.cn 控制台或官方文档为准。”
Diff 审查清单
Section titled “Diff 审查清单”| 检查项 | 通过信号 | 需要警惕 |
|---|---|---|
| 范围 | 改动只服务重构目标 | 同时改需求、文案、视觉或接口 |
| 行为 | 测试和验收路径通过 | 删除错误处理或改变默认值 |
| API | 配置项、请求头、响应结构不变 | Key 泄露、Base URL 写死 |
| 类型 | 类型更准确，调用方仍能编译 | 为了通过编译把类型放宽 |
| 依赖 | 没有无关生产依赖 | 为小重构引入大框架 |
| 可回滚 | 每阶段能单独撤回 | 一个 diff 混合多个方向 |
Codex app 的 review 面板会显示当前 Git 工作树中的改动，包括 Codex、用户和其他未提交变化。重构后应按文件审查，而不是只看最终测试是否变绿。
常见错误排查
Section titled “常见错误排查”| 错误 | 表现 | 修复 |
|---|---|---|
| 重构和功能混在一起 | review 不知道哪些变化是有意的 | 拆成两个任务，先保行为 |
| 未建立基线 | 行为变化无法判断 | 先补测试、截图或 API 样例 |
| 一次移动太多文件 | 冲突多、回滚困难 | 先提取小模块，再移动目录 |
| 类型被放宽 | 编译通过但约束变弱 | 收窄类型，增加边界测试 |
| API 配置被写死 | 本地可用，部署失败 | 保持环境变量和 server-only 边界 |
| 只听 Codex 解释 | 实际 diff 与解释不一致 | 逐文件 review，运行验证命令 |
| 风险 | 处理方式 |
|---|---|
| 顺手改需求 | Goal 中写明行为不变，并把新需求放进后续任务。 |
| 测试不足 | 先补关键回归测试，再进入结构调整。 |
| 大文件拆分过细 | 按职责拆，不按行数机械拆。 |
| import 路径混乱 | 使用构建和类型检查验证所有调用方。 |
| 隐式副作用 | 把网络、时间、存储和随机数隔离到明确边界。 |
| 团队不理解新结构 | 在 PR 描述或 README 里说明分层原则。 |
- Refactoring, Martin Fowler：重构强调小步、保持行为不变和降低错误风险。
- OpenAI Codex 官方手册：Codex 任务说明、验证、review 和 AGENTS.md 指令建议。
- OfApp.cn API 文档：Base URL、API Key、Codex / OpenAI 生态接入入口。
- OfApp.cn 天才游乐场：聊天、写作、读文件和图片参数调试入口。
什么时候不该让 Codex 重构？
Section titled “什么时候不该让 Codex 重构？”需求不稳定、测试缺失、核心业务规则不清楚、线上事故未关闭或涉及生产数据迁移时，不应直接大规模重构。
重构需要分多次提交吗？
Section titled “重构需要分多次提交吗？”任务较大时建议分阶段提交。每个阶段都应有清晰目标、验证结果和可回滚边界，便于 review 和定位问题。
Codex 可以判断架构好坏吗？
Section titled “Codex 可以判断架构好坏吗？”Codex 可以提供依赖分析、风险点和候选方案，但架构取舍仍应由维护者结合团队经验、代码规模和未来路线决定。
没有测试还能重构吗？
Section titled “没有测试还能重构吗？”可以做非常小的命名整理或注释清理，但不适合做结构性改动。先补关键路径测试、截图验收或 API 样例，再让 Codex 拆模块。
重构时发现 Bug 怎么办？
Section titled “重构时发现 Bug 怎么办？”不要把 Bug 修复混进同一个重构 diff。记录复现路径，暂停重构，单独开修复任务并补回归测试。
AI API 客户端应该怎么重构？
Section titled “AI API 客户端应该怎么重构？”把 Base URL、Key、超时、重试、日志脱敏和错误转换集中到服务端 client 层。业务代码调用稳定接口，不直接拼接密钥或请求头。
- 用 Codex 生成测试：重构前建立安全网。
- 用 Codex 写代码：功能完成后再整理结构。
- 用 Codex 修 Bug：把 Bug 修复和重构拆开。
- 用 Codex 排查报错：处理重构后的失败。
- 用 Codex 配置 GitHub 工作流：让重构进入 CI 验证。
- Codex 本地项目使用指南：让 Codex 先读项目结构和指令。
- Codex Goal 提示词模板：复制分阶段重构模板。
- AI 辅助开发：把写代码、测试、重构和提交串成开发流程。
- 如何配置 Base URL：保持 API 配置可迁移。
用 Codex 重构项目时，要把“行为不变、范围可控、分阶段验证、diff 可审查”写进 Goal。重构不是展示技巧，而是让项目更容易理解、测试和继续开发。