4.3 代码重构

重构是危险的——如果你没有计划

重构的本质是"改变结构，不改变行为"。听起来很合理，但实际操作中极容易出现"改了结构，也顺便改了行为，还不知道"的情况。

Claude Code 在重构上能提供很大帮助，但有一个原则必须先说清楚：

重构之前，先规划。永远先规划。

---

重构的黄金三步

第一步：探索现状（Plan Mode）

进入 Plan Mode，让 Claude Code 先读懂要重构的部分，不做任何改动：

enter plan mode. analyze the authentication module in src/auth/.
I want to understand:
1. what is the current structure?
2. what are the dependencies — what does this module depend on,
   and what depends on it?
3. what would break if I change the interface?

这一步的目标是建立"改之前的全貌"。很多重构失败是因为改的时候才发现有个东西依赖了你以为没人用的接口。

第二步：制定计划

还在 Plan Mode 里，让它制定重构方案：

I want to refactor src/auth/ to separate the JWT logic from the
OAuth logic into distinct strategy classes using the Strategy pattern.

create a detailed migration plan:
- what new files need to be created?
- what existing files need to change?
- what is the safest order to make these changes?
- are there any breaking changes for callers of this module?

拿到计划之后，按 Ctrl+G 在编辑器里打开，仔细看。

这是一个被严重低估的功能——你可以直接在编辑器里修改这份计划：删掉你不认可的步骤，加上约束条件，注明某个地方要特别小心。Claude Code 执行的时候会尊重你的修改。

第三步：分批执行

计划确认后，退出 Plan Mode，分批执行，不要一次性让它把所有改动都做完：

start with step 1 of the plan: create the base AuthStrategy interface
and the JWTStrategy class. don't touch any existing files yet.
run the tests after each new file is added to make sure nothing breaks.

每一批做完，跑测试，确认没问题，再继续下一批。

---

为什么要分批，不要一次性完成

一次性大重构的问题：

• 如果测试失败了，你不知道是哪一步引入的问题
• diff 太大，review 起来很痛苦
• 一旦出问题，回滚代价很高

分批执行的好处：

• 每批的 diff 小，出问题立刻能定位
• 每批都跑测试，问题在最小范围内暴露
• 任何时候都可以停下来，已完成的部分不受影响

---

测试先行：重构的安全网

在开始重构之前，先确认测试覆盖到位：

before we start refactoring, check the test coverage for src/auth/.
what scenarios are not covered by existing tests?
add the missing tests first, so we have a safety net during refactoring.

没有测试的重构就是在走钢丝。Claude Code 可以帮你补测试，但这件事要在重构之前做，不是之后。

---

现代化老代码的 prompt 模板

升级异步风格（callback → async/await）：

refactor src/utils/fileHelper.js to replace all callback-style
async code with async/await. maintain the same external API.
run the existing tests after each function is refactored
to confirm behavior is unchanged.

拆分过大的文件：

UserController.ts is 800 lines and handles too many concerns.
analyze it and propose how to split it into smaller,
more focused controllers. don't change any logic, just restructure.

消除重复代码：

find duplicated logic across the service files in src/services/.
identify the top 3 most duplicated patterns and propose
how to extract them into shared utilities. show me the plan first.

引入 TypeScript 严格模式：

I want to enable strict mode in TypeScript for this project.
first, run tsc --strict in dry-run mode and show me all the errors.
then fix them one file at a time, starting with the most critical ones.
don't use 'any' as a shortcut — fix the actual type issues.

---

一个容易踩的坑

你告诉 Claude Code "重构这个模块"，它可能会在重构的过程中顺便"改进"一些它觉得不好的地方——改一个算法、优化一个逻辑、重命名一个变量。

这些改动可能是好的，但它们不是你要求的，也没有被测试覆盖。

防止这个情况的 prompt 写法：

refactor the structure only. do not change any logic, algorithms,
or behavior. if you see something that could be improved separately,
note it in a comment but don't change it.

把边界说清楚，它就不会越界。