luongnv89/code-refactor

代码重构 Skill

这是一个基于 Martin Fowler《Refactoring: Improving the Design of Existing Code》（第 2 版）的系统化代码重构方法。这个 skill 强调安全、渐进的修改，并由测试提供保障。

“重构是在不改变软件外部行为的前提下，改进其内部结构的过程。” — Martin Fowler

核心原则

1. 保持行为不变：外部行为必须保持一致
2. 小步前进：每次只做很小、可测试的改动
3. 测试驱动：测试是安全网
4. 持续进行：重构是长期过程，不是一次性任务
5. 协作确认：每个阶段都需要用户确认

工作流程总览

阶段 1：研究与分析
    ↓
阶段 2：测试覆盖评估
    ↓
阶段 3：识别代码异味
    ↓
阶段 4：创建重构计划
    ↓
阶段 5：增量实施
    ↓
阶段 6：评审与迭代

---

阶段 1：研究与分析

目标

• 理解代码库结构和用途
• 确定重构范围
• 收集业务需求背景

先向用户确认的问题

开始前先确认：

1. 范围：哪些文件 / 模块 / 函数需要重构？
2. 目标：你想解决什么问题？（可读性、性能、可维护性）
3. 约束：有哪些区域不能改？
4. 时间压力：这是否阻塞了其他工作？
5. 测试状态：是否已有测试？是否通过？

行动

• [ ] 阅读并理解目标代码
• [ ] 识别依赖和集成点
• [ ] 记录当前架构
• [ ] 标记已有技术债迹象（TODO、FIXME）

输出

向用户汇报：

• 代码结构总结
• 识别出的问题区域
• 初步建议
• 请求继续执行的批准

---

阶段 2：测试覆盖评估

为什么测试重要

“没有测试的重构，就像没有安全带就开车。” — Martin Fowler

测试是安全重构的关键前提。没有测试，很容易引入 bug。

评估步骤

1. 检查现有测试

   # 查找测试文件
   find . -name "*test*" -o -name "*spec*" | head -20
   

2. 运行现有测试

   # JavaScript / TypeScript
   npm test
   
   # Python
   pytest -v
   
   # Java
   mvn test
   

3. 检查覆盖率（如果可用）

   # JavaScript
   npm run test:coverage
   
   # Python
   pytest --cov=.
   

决策点：询问用户

如果测试存在且通过：

• 进入阶段 3

如果测试缺失或不完整： 给出选项：

1. 先写测试（推荐）
2. 在重构过程中逐步补测试
3. 不写测试直接继续（有风险，需要用户确认）

如果测试失败：

• 停止。先修复失败测试再重构
• 问用户：是否先修测试？

测试编写建议（如需要）

对每个要重构的函数，测试应覆盖：

• 正常路径
• 边界情况（空输入、null、边界值）
• 错误场景（非法输入、异常）

使用“红-绿-重构”循环：

1. 写失败测试（红）
2. 让它通过（绿）
3. 再重构

---

阶段 3：识别代码异味

什么是代码异味？

代码深层问题的表面症状。它们不一定是 bug，但说明代码设计可能有问题。

常见异味清单

完整目录见 references/code-smells.md。

快速参考

| 异味 | 迹象 | 影响 | |-------|------|------| | 长函数 | 函数超过 30-50 行 | 难以理解、测试和维护 | | 重复代码 | 多处出现相同逻辑 | 修复需要改多处 | | 大类 | 类承担了太多职责 | 违反单一职责原则 | | Feature Envy | 一个方法更多依赖别的类的数据 | 封装性差 | | 基础类型沉迷 | 过度使用基础类型而不是对象 | 缺少领域概念 | | 长参数列表 | 方法参数超过 4 个 | 调用困难 | | 数据泥团 | 一组数据总是一起出现 | 缺少抽象 | | switch 语句 | 复杂的 switch / if-else 链 | 难以扩展 | | 臆想泛化 | “以防未来需要”提前设计 | 不必要的复杂度 | | 死代码 | 未使用的代码 | 造成困惑和维护负担 |

分析步骤

1. 自动分析（如果有脚本）

   python scripts/detect-smells.py <file>
   

2. 人工审查

   • 系统地走读代码
   • 记录每个异味的位置和严重性
   • 按影响分类（Critical / High / Medium / Low）

3. 优先级排序 优先关注会：

   • 阻塞当前开发的异味
   • 导致 bug 或混淆的异味
   • 影响最常变更代码路径的异味

输出：异味报告

向用户呈现：

• 识别出的异味及位置
• 每项的严重性评估
• 建议的优先级顺序
• 请求用户确认优先级

---

阶段 4：创建重构计划

选择重构方式

针对每个异味，从目录中选择合适的重构手法。

完整列表见 references/refactoring-catalog.md。

异味到重构的映射

| 代码异味 | 推荐重构 | |----------|----------| | 长函数 | Extract Method、Replace Temp with Query | | 重复代码 | Extract Method、Pull Up Method、Form Template Method | | 大类 | Extract Class、Extract Subclass | | Feature Envy | Move Method、Move Field | | 基础类型沉迷 | Replace Primitive with Object、Replace Type Code with Class | | 长参数列表 | Introduce Parameter Object、Preserve Whole Object | | 数据泥团 | Extract Class、Introduce Parameter Object | | switch 语句 | Replace Conditional with Polymorphism | | 臆想泛化 | Collapse Hierarchy、Inline Class、Remove Dead Code | | 死代码 | Remove Dead Code |

计划结构

使用 templates/refactoring-plan.md 里的模板。

每项重构都要写明：

1. Target：将修改哪些代码
2. Smell：解决什么问题
3. Refactoring：采用哪种手法
4. Steps：详细微步骤
5. Risks：可能出什么问题
6. Rollback：如何回退

分阶段方法

关键：重构必须分阶段推进。

阶段 A：快速收益（低风险，高价值）

• 重命名变量以提升清晰度
• 提取明显重复的代码
• 删除死代码

阶段 B：结构改进（中风险）

• 从长函数中提取方法
• 引入参数对象
• 把方法移动到更合适的类

阶段 C：架构改动（高风险）

• 用多态替代条件分支
• 提取类
• 引入设计模式

决策点：把计划展示给用户

在开始实施前：

• 展示完整重构计划
• 解释每个阶段及其风险
• 获得每个阶段的明确批准
• 询问：“是否继续执行阶段 A？”

---

阶段 5：增量实施

黄金法则

“修改 → 测试 → 通过？→ 提交 → 下一步”

实施节奏

对每一步重构：

1. 预检查

   • 测试通过（绿色）
   • 代码能编译

2. 只做一个小改动

   • 按目录中的具体操作进行
   • 保持改动最小化

3. 验证

   • 立刻运行测试
   • 检查编译错误

4. 如果测试通过（绿色）

   • 用描述清晰的提交信息提交
   • 继续下一步

5. 如果测试失败（红色）

   • 立刻停止
   • 撤销改动
   • 分析原因
   • 如有疑问，询问用户

提交策略

每次提交都应当：

• 原子性：只包含一个逻辑改动
• 可回滚：容易撤销
• 描述清楚：提交信息明确

示例提交信息：

refactor: 从 processOrder() 中提取 calculateTotal()
refactor: 将 'x' 重命名为 'customerCount' 以提升清晰度
refactor: 删除未使用的 validateOldFormat() 方法

进度汇报

每个子阶段完成后，向用户汇报：

• 做了哪些改动
• 测试是否仍通过
• 遇到了什么问题
• 询问：“继续下一批吗？”

---

阶段 6：评审与迭代

重构后检查清单

• [ ] 所有测试通过
• [ ] 没有新的警告 / 错误
• [ ] 代码编译成功
• [ ] 行为没有变化（手动验证）
• [ ] 必要时已更新文档
• [ ] 提交历史干净

指标对比

重构前后运行复杂度分析：

python scripts/analyze-complexity.py <file>

展示改进：

• 代码行数变化
• 圈复杂度变化
• 可维护性指标变化

用户评审

向用户展示最终结果：

• 所有变更摘要
• 重构前后代码对比
• 指标改善情况
• 剩余技术债
• 询问：“你对这些改动满意吗？”

下一步

和用户讨论：

• 还要处理哪些异味？
• 是否安排下一次重构？
• 是否把类似修改应用到其他地方？

---

重要指南

何时暂停并询问

遇到以下情况时，务必暂停并和用户确认：

• 不确定业务逻辑
• 改动可能影响外部 API
• 测试覆盖不足
• 需要做重大的架构决策
• 风险上升
• 遇到意外复杂性

安全规则

1. 没有测试不要重构（除非用户明确确认风险）
2. 不要做大改动，拆成小步
3. 每次改动后都不要跳过测试
4. 测试失败就不要继续，先修复或回滚
5. 不要臆测，不确定就问

不要做什么

• 不要把重构和新功能混在一起
• 不要在生产事故期间做重构
• 不要重构你看不懂的代码
• 不要过度设计，保持简单
• 不要一次性重构所有内容

---

快速上手示例

场景：长函数 + 重复逻辑

重构前：

function processOrder(order) {
  // 150 行代码，包含：
  // - 重复验证逻辑
  // - 内联计算
  // - 多种职责混杂
}

重构步骤：

1. 确认测试存在，覆盖 processOrder()
2. 提取 验证逻辑为 validateOrder()
3. 测试 - 应该通过
4. 提取 计算逻辑为 calculateOrderTotal()
5. 测试 - 应该通过
6. 提取 通知逻辑为 notifyCustomer()
7. 测试 - 应该通过
8. 评审 - processOrder() 现在只负责串联 3 个清晰函数

重构后：

function processOrder(order) {
  validateOrder(order);
  const total = calculateOrderTotal(order);
  notifyCustomer(order, total);
  return { order, total };
}

---

参考资料

• 代码异味目录 - 代码异味完整清单
• 重构目录 - 重构手法
• 重构计划模板 - 计划模板

脚本

• scripts/analyze-complexity.py - 分析代码复杂度指标
• scripts/detect-smells.py - 自动检测 code smell

版本历史

• v1.0.0 (2025-01-15)：首次发布，包含 Fowler 方法论、分阶段流程和用户确认点