🏠 主目录 | ⬅️ 上一章 (Ch.08) | ➡️ 下一章 (Ch.10) | 🌐 English
Ch.09 架构复苏：混乱遗留系统的全景解析与渐进式解耦
🎯 具体工程麻烦：接手几万行无文档、无测试的屎山系统，改一行崩三处，重构不敢碰，盲目重写又交不了差。
💡 可运行实战代码与落地收益：全景逆向拓扑生成 Prompt（提取 ER 图与路由）；接口行为快照基准测试（Golden Master）；微创解耦三步法。
⚡ 社交传播 / 截图金句：“面对几十万行没文档的遗留系统，别冲动推倒重来。先让 AI 画出地图、补上防崩测试，再做微创手术。”
在独立开发或承接外包项目时，接手前人留下、无文档且无单测的「屎山」系统，远比从零构建更令人棘手，任何微小改动都伴随着潜在风险。
针对此类项目，并不建议盲目推倒重来。借助 Codex 的全景分析与推理能力，我们可以对遗留系统实施渐进式解耦与重构。本章将介绍如何指挥 Codex 进行项目分析与分层解耦。
9.1 第一步：全景逆向，建立代码拓扑图
接手混乱项目的首要任务是画出地图。别自己去翻代码，让 Codex 帮你进行项目逆向工程。
1. 逆向生成数据库依赖关系
如果项目使用了 Prisma 或 SQL，你可以让 Codex 直接根据数据库配置文件逆向出 Mermaid 实体关系图（ERD）。
在本地向 Codex 派发任务 Specs：
# 🎯 Goal
分析当前项目的数据库配置，生成一个包含核心表结构与外键关联的 Mermaid ERD 图。
# 🛑 Constraints
- 只分析 /prisma/schema.prisma 或 /src/db/models/ 下的文件。
- 排除临时表和第三方元数据表。
# 🧪 Validation Specs
- 在 /docs/database_topology.md 中输出渲染正确的 Markdown Mermaid 代码块。Codex 会自动解析表之间的关系，并生成直观的拓扑图，这比你人肉去翻数据库关系要快上百倍。
9.2 第二步：安全红线，编写行为基准测试
重构遗留代码的铁律是：先保证旧行为不被改坏，再动刀子。
我们需要让 Codex 自动为现有的关键接口（例如购物车结算、OAuth 登录回调）编写行为基准测试，以此作为重构过程中的安全红线。
实战：向 Codex 下达基准测试指令
# 🎯 Goal
为 src/pages/api/checkout.ts 接口编写单元测试，捕捉当前的请求行为与返回格式。
# 🛑 Constraints
- 不要修改 src/pages/api/checkout.ts 中的任何逻辑。
- 使用本地沙盒中的 Jest / Vitest 运行测试。
# 🧪 Validation Specs
- 至少覆盖三种场景：商品正常结算、库存不足报错、未登录拦截。
- 确保测试运行通过率 100%。有了这些基准测试（也就是 AI 的验收警戒线），后续的任何重构改动一旦破坏了历史逻辑，都会立刻在沙盒的编译测试中被拦截。
9.3 第三步：微创手术，实施渐进式解耦
拥有了“地图”（拓扑图）和“防线”（基准测试）后，我们就可以指挥 Codex 实施重构了。
1. 解耦胖控制器 (Fat Controllers)
假设我们有一个 500 行的 API 路由，里面混杂了“鉴权、折扣计算、发送邮件、扣库存、记录日志”等一堆逻辑。我们可以让 Codex 进行“逻辑抽离”：
# 🎯 Goal
将 src/pages/api/checkout.ts 中的“折扣计算逻辑”抽离到单独的服务类 src/services/discountService.ts 中。
# 🛑 Constraints
- 保证外部调用接口入参与出参不变。
- 严禁影响 checkout.ts 的其他核心逻辑。
# 🧪 Validation Specs
- 运行 npm run test，确保之前编写的结算基准测试 100% 通过。
- 运行 npm run lint 无任何语法错误。2. 局部验证与安全回滚
当 Codex 开始重构时，它会在沙盒中执行修改并自动运行测试。如果测试失败，它会在 CoT 思维链中判断是自己的重构逻辑写错了，还是基准测试写错了。
通过这种“抽取逻辑 -> 运行测试 -> 报错回滚 -> 重新调整”的微创重构循环，你可以在短短几个小时内，把一个几万行、无法维护的遗留系统重构为清晰、模块化、带测试覆盖的现代系统。
不要害怕屎山，用 Specs 和测试做你的盾牌，把手写重构的工作让渡给 Codex。