Code Refactoring

代码重构技能

本技能提供系统化、安全的代码重构指导，帮助改善既有代码的内部结构而不改变其外部行为。

核心原则

1. 先测试，后重构：确保有足够的测试覆盖再开始重构
2. 小步前进：每次只做一个小的重构动作，立即验证
3. 保持行为不变：重构不应改变代码的外部行为
4. 持续验证：每一步重构后都要运行测试验证
5. 风格符合：重构的代码应符合项目规范

重构计划输出格式

在执行任何重构前，必须先输出详细的重构计划，格式如下：

## 重构计划

### 重构项 1
- **位置**：[文件路径]:[行号范围]，[函数/类/模块名称]
- **问题**：[描述当前存在的问题，标注坏味道类型]
- **方案**：[推荐的重构手法名称]
- **重构前**：
  [重构前的关键代码片段]
- **重构后**：
  [重构后的关键代码片段]
- **参考**：[参考资源]中的相关规则（如果涉及）

### 重构项 2
...

标准重构流程

步骤 1：确保测试覆盖

目的：建立安全网，确保重构不会破坏现有功能。

执行动作：

1. 检查现有测试覆盖率
2. 如果覆盖率不足（建议 >70%），优先为核心逻辑补充测试
3. 运行全部测试，确保基线状态为绿色

验证标准：所有现有测试通过，关键路径有测试覆盖。

无测试环境时的处理

当无法执行测试（如缺少依赖、环境未配置）时，可暂时跳过测试执行，但必须：

风险告知：

• ⚠️ 重构可能引入隐藏的回归问题
• ⚠️ 无法验证行为一致性
• ⚠️ 可能破坏现有功能

替代验证方式：

1. 静态检查：运行 linter、类型检查器（如 mypy、eslint、staticcheck）
2. 代码审查：人工对比重构前后代码逻辑
3. 编译验证：确保代码可编译/解析无误

后续验证建议：

1. 在重构报告中明确标注"未执行测试验证"
2. 列出需要在真实环境中验证的测试用例
3. 建议用户在有测试环境后优先执行验证
4. 提供回滚方案（如 git revert 命令）

步骤 2：识别代码坏味道

目的：系统性地发现代码中的问题点。

执行动作：

1. 阅读代码，识别存在的坏味道
2. 记录每个坏味道的位置、类型和严重程度
3. 按优先级排序：先处理影响最大的问题

常见坏味道快速参考：

步骤 3：选择重构手法

目的：为每个坏味道匹配合适的重构手法。

执行动作：

1. 根据坏味道类型选择对应重构手法
2. 评估重构手法的风险和收益
3. 选择最适合当前上下文的手法

常见映射关系：

步骤 4：小步执行重构

目的：安全地执行重构，每一步都可验证。

执行动作：

1. 按优先级选择一个重构项
2. 执行单个重构手法，遵循原则：
   • 一次只做一个改动
   • 保持代码可编译/可运行状态
   • 每步改动后立即运行测试

验证标准：每一步后测试通过，代码可正常运行。

步骤 5：审视与进一步优化

目的：检查重构效果，发现新的优化机会。

执行动作：

1. 审视重构后的代码结构
2. 检查是否有新的坏味道产生
3. 如发现新问题，返回步骤2继续迭代

步骤 6：验证行为一致性

目的：确保重构未改变代码的外部行为。

执行动作：

1. 运行完整的测试套件，确保全部通过
2. 对于关键功能，进行手动验证
3. 如有性能敏感代码，进行性能对比测试

验证标准：所有测试通过，功能行为与重构前一致，无新增的警告或错误。

参考资源

项目代码风格规范

重构后的代码必须符合项目代码风格规范：

重构知识参考

检查清单

重构前

• 是否有足够的测试覆盖？
• 是否理解要重构的代码？
• 是否有清晰的重构目标？

重构中

• 是否每次只做一个改动？
• 是否每步都运行测试？
• 是否保持代码可编译/可运行？

重构后

• 所有测试是否通过？
• 功能行为是否保持不变？
• 是否符合项目的代码规范？

输出报告

重构完成后，输出重构报告，报告内容包括：

1. 重构摘要：重构项数量、涉及文件、代码行变化
2. 重构详情：每个重构项的问题、方案、前后对比
3. 验证结果：测试执行情况、静态检查结果
4. 重构效果：重构前后的效果对比
5. 后续建议：发现的潜在优化点、技术债清单