large-repo-refactorlisted

# 大仓库重构 ## 何时用 - 需要对大型或老代码库做结构性调整：抽函数、移动模块、重命名、拆分大文件。 - 已有功能运行正常，但代码组织混乱、可读性差，需要在不改变外部行为的前提下清理内部结构。 - 接到"把这个模块重构一下"或"把这些文件整理整理"的任务，改动会波及多个文件或多处调用方。 - 团队准备迁移到新架构，需要分阶段、可回退地把现有代码逐步搬过去。 ## 核心规则 ### 1. 先立测试护栏 **规则：** 确认关键路径有测试覆盖再动手重构；若测试不存在或覆盖不足，先补特征测试（characterization test）锁住当前行为，再开始结构调整。 **为什么：** AI 做重构时最常见的事故不是"改错了逻辑"，而是"改完觉得没问题，其实已经悄悄改变了行为"。没有测试护栏，重构后的代码和重构前的代码在输入输出上是否完全一致，只能靠肉眼比对，这在大仓库里几乎不可能做到。特征测试的目的不是验证"代码应该做什么"，而是记录"代码现在实际做什么"——包括那些可能是 bug 的行为，先把它们冻结下来，重构完再讨论要不要修。 **怎么做：** - 重构前先跑现有测试套件，确认全部通过，建立基准绿灯。 - 找出重构目标的关键输入输出（函数签名、HTTP 响应、数据库写入格式），用现有输出写断言，不是写"预期应该怎样"而是写"现在实际是怎样"。 - 特征测试不需要优雅，只需要覆盖：把现有行为的真实输出直接复制进断言，宁可多写几个边��用例。 - 补完测试，跑一遍确认全绿，再切到重构任务。 --- ### 2. 行为不变原则 **规则：** 重构只允许改代码结构，不允许同时改外部可见行为；每完成一个重构步骤立刻跑测试，确认行为与改前完全一致。 **为什么：** AI 在重构时极容易把"顺手改进逻辑"和"结构调整"混在一起——改参数顺序"因为这样更合理"，修掉一个"顺眼的边界条件"，调整返回值结构"更符合最佳实践"。每一处单独看都是好意，但混在重构里有两个危险：一，下游调用方可能依赖这个"不合理"的行为；二，一旦测试挂掉，无法判断是结构改动破坏的还是逻辑改动破坏的。重构和行为修改必须是两次独立的提交。 **怎么做：** - 每个重构步骤结束后立刻跑测试，不要攒几步再跑。 - 若发现现有代码有 bug 或值得改进的逻辑，记录下来，不在当前重构 PR 里动，单独开任务处理。 - 提交信息中明确写"refactor: 只改结构，行为不变"，让 reviewer 知道这一步不含逻辑变更，可以用更轻量的方式审查。 - 若测试挂掉，先还原到上一步绿灯状态，找出哪一处结构改动影响了行为，再修正，不要在挂掉状态下继续推进。 --- ### 3. 单一变换，每步可独立回退 **规则：** 每次提交只做一种重构操作——改名就只改名，抽函数就只抽函数，移动文件就只移动文件；绝不在同一个提交里混合多种变换。 **为什么：** AI 被要求"重构这个模块"时，会倾向于一口气生成"改完的最终状态"：函数名换了、目录结构调了、逻辑抽象层加了、import 路径更新了——全在一个 diff 里。这类大爆炸式提交在代码 review 时几乎无法有效审查，出问题时更无从用 `git bisect` 定位。出了问题只能整体回滚，等于白做。单一变换的核心价值是：每一步都可以被精确撤销，问题定位可以缩到一次提交粒度。 **怎么做：** - 把重构计划拆成操作列表，每条对应一个提交： ``` 步骤 1: 把 processOrder 里的金额计算逻辑