large-repo-refactor

大仓库重构

何时用

• 需要对大型或老代码库做结构性调整：抽函数、移动模块、重命名、拆分大文件。
• 已有功能运行正常，但代码组织混乱、可读性差，需要在不改变外部行为的前提下清理内部结构。
• 接到"把这个模块重构一下"或"把这些文件整理整理"的任务，改动会波及多个文件或多处调用方。
• 团队准备迁移到新架构，需要分阶段、可回退地把现有代码逐步搬过去。

核心规则

1. 先立测试护栏

规则： 确认关键路径有测试覆盖再动手重构；若测试不存在或覆盖不足，先补特征测试（characterization test）锁住当前行为，再开始结构调整。

为什么： AI 做重构时最常见的事故不是"改错了逻辑"，而是"改完觉得没问题，其实已经悄悄改变了行为"。没有测试护栏，重构后的代码和重构前的代码在输入输出上是否完全一致，只能靠肉眼比对，这在大仓库里几乎不可能做到。特征测试的目的不是验证"代码应该做什么"，而是记录"代码现在实际做什么"——包括那些可能是 bug 的行为，先把它们冻结下来，重构完再讨论要不要修。

怎么做：

• 重构前先跑现有测试套件，确认全部通过，建立基准绿灯。
• 找出重构目标的关键输入输出（函数签名、HTTP 响应、数据库写入格式），用现有输出写断言，不是写"预期应该怎样"而是写"现在实际是怎样"。
• 特征测试不需要优雅，只需要覆盖：把现有行为的真实输出直接复制进断言，宁可多写几个边界用例。
• 补完测试，跑一遍确认全绿，再切到重构任务。

---

2. 行为不变原则

规则： 重构只允许改代码结构，不允许同时改外部可见行为；每完成一个重构步骤立刻跑测试，确认行为与改前完全一致。

为什么： AI 在重构时极容易把"顺手改进逻辑"和"结构调整"混在一起——改参数顺序"因为这样更合理"，修掉一个"顺眼的边界条件"，调整返回值结构"更符合最佳实践"。每一处单独看都是好意，但混在重构里有两个危险：一，下游调用方可能依赖这个"不合理"的行为；二，一旦测试挂掉，无法判断是结构改动破坏的还是逻辑改动破坏的。重构和行为修改必须是两次独立的提交。

怎么做：

• 每个重构步骤结束后立刻跑测试，不要攒几步再跑。
• 若发现现有代码有 bug 或值得改进的逻辑，记录下来，不在当前重构 PR 里动，单独开任务处理。
• 提交信息中明确写"refactor: 只改结构，行为不变"，让 reviewer 知道这一步不含逻辑变更，可以用更轻量的方式审查。
• 若测试挂掉，先还原到上一步绿灯状态，找出哪一处结构改动影响了行为，再修正，不要在挂掉状态下继续推进。

---

3. 单一变换，每步可独立回退

规则： 每次提交只做一种重构操作——改名就只改名，抽函数就只抽函数，移动文件就只移动文件；绝不在同一个提交里混合多种变换。

为什么： AI 被要求"重构这个模块"时，会倾向于一口气生成"改完的最终状态"：函数名换了、目录结构调了、逻辑抽象层加了、import 路径更新了——全在一个 diff 里。这类大爆炸式提交在代码 review 时几乎无法有效审查，出问题时更无从用 git bisect 定位。出了问题只能整体回滚，等于白做。单一变换的核心价值是：每一步都可以被精确撤销，问题定位可以缩到一次提交粒度。

怎么做：

• 把重构计划拆成操作列表，每条对应一个提交：

  步骤 1: 把 processOrder 里的金额计算逻辑抽成 calculateAmount 函数
  步骤 2: 把 calculateAmount 移到 src/domain/pricing.ts
  步骤 3: 将所有调用方的 import 路径更新为新路径
  步骤 4: 把 processOrder 重命名为 handleOrderSubmission
  

• 每步提交前跑测试确认绿灯，再提交，再进行下一步。
• 若某步执行中发现需要同时改另一件事，先把当前步骤提交或暂存，再另起一个步骤。

---

4. 自动化优先，不手动批量改

规则： 能用 IDE 重构工具、代码迁移脚本（codemod）、语言服务器安全执行的重构，不要用手写替换或正则批量改；手改正则是大仓库重构引入 bug 的重灾区。

为什么： AI 遇到"把全仓库 500 处 getUserById 改名成 findUserById"时，最容易的做法是写个正则替换脚本或直接生成修改后的文件列表。问题是：正则不理解语法，会改到字符串字面量、注释、不同作用域下同名但含义不同的函数；手工批量替换会跳过动态调用（obj[methodName]()）、装饰器、反射场景。IDE 的语言感知重命名会处理这些边界情况，而 AI 生成的正则脚本几乎不会。