refactoring

重构：代码异味与技术

检测代码异味并应用重构技术，以改善设计、清晰度和可维护性的综合指南。

---

按需阅读

阅读时机	文件
识别代码异味，或审查存在臃肿问题的 diff/PR	代码异味目录
决定使用哪种重构技术	重构技术
选择合适的模式、基于场景做决策，或确定审查工作流	决策指南
仅当用户询问某种模式适用于特定语言的哪些场景时	语言惯用法
测试很少的遗留代码重构（热点、微提交、子类与覆写、审批测试）	遗留代码急救

---

始终遵守的防护原则

• 绝不自动删除 TODO 注释。 TODO 需要人工决策——应指出它们，而不是删除。
• 及时整理。 在已知的行为变更之前或之后立即整理：变更之前，具体工作一目了然；变更之后，设计上的阻力仍历历在目。避免固定的技术债配额，因为这会诱使人在错误的时间和地点进行推测性清理。如果管理层预留了产能，应将其视为许可和余量，而非配额；解决阻碍及时整理的激励问题。仅在有意练习、弥补有意识采取的捷径，或梳理陌生且状况不佳的代码库时，才为单独的整理工作设定时间上限。
• 提取前遵循三次原则。 等到出现 第三处 重复后，再执行 Extract Method / Extract Class。两处重复不足以可靠地揭示合适的抽象。
• 没有测试，就不要重构。 不要盲目重构——先建立安全网。
• 提取无需新增测试。 重构期间提取的辅助函数，由现有的公共 API 行为测试覆盖；针对这些辅助函数编写单元测试，会让测试套件重新与代码结构耦合（参见测试中的模拟脆弱性指南）。
• 整理注释时成对进行。 删除多余注释时，也要检查是否缺少值得补充的 原因 注释。

代码异味 → 技巧（快速参考）

代码异味	检测信号	技巧
过长方法	超过 10 行，包含多个职责	提取方法 (三次原则)
过大的类	超过 10 个方法，涉及多个关注点，难以测试	提取类 (三次原则)
原始类型偏执	用 String/int 常量表示领域概念	创建类型/对象
过长参数列表	超过 3–4 个参数，且参数彼此相关	引入参数对象
数据泥团	多处出现相同变量	提取类
注释	代码需要注释才能理解（子类型请参见 smells.md）	提取方法/变量、重命名、引入断言、编写测试
名称含糊不清	名称需要注释、使用单字母、通用占位符或缺少单位	重命名 / 引入变量

完整的“技巧 → 适用场景”表格请参见 techniques.md。

---

按目标分类的技巧

• 提升可测试性： 提取方法 → 提取类 → 替换条件判断
• 减少重复： 提取方法 → 替换条件判断 → 引入变量
• 提升可读性： 重命名 → 引入变量 → 简化条件判断 → 提取方法
• 改进设计/耦合： 提取类 → 移动方法/字段 → 替换条件判断

---

何时不应重构

有时，代码的规模、复杂度或结构是合理的：

• 复杂算法确实需要较多代码行（并通过清晰的注释说明原因）
• 声明式结构，例如配置对象或测试数据（可接受较长的参数列表）
• 临时代码，很快就会被替换（重构成本大于收益）
• 一次性实用工具，提取代码产生的样板代码比节省的代码更多
• 尚不稳定的代码，仍在频繁变化——等需求稳定后再处理
• 性能关键路径，重构会降低速度（先进行性能分析）
• 没有测试的代码——只有在具备安全网时才重构（参见始终适用的防护措施）
• 相似代码仅出现两处——遵循三次原则（参见始终适用的防护措施）；过早遵循 DRY 往往会导致抽象错误

始终自问：“这种复杂度有助于实现代码的目的，还是会掩盖它？”

---

外部参考

• Refactoring Guru： 代码异味 - 臃肿类
• Martin Fowler： 重构目录 — 按操作分类的 72 种以上技巧
• 原则： SRP、OCP、DRY
• 鸣谢： Tim Ottinger（注释）；Fowler Refactoring；Martin Clean Code

---

基准测试

场景：.benchmarks/scenarios/refactoring-001-long-method.md · 运行时间：2026-06-14

模型	未使用	使用	差值
claude-opus-4-8	83%	100%	+17%
claude-sonnet-4-6	33%	100%	+67%
claude-haiku-4-5	0%	100%	+100%

通过（最强信号）。对弱模型效果显著（haiku 从 0→100%）：确保命名代码异味、优先提取方法、限定为原地修改、遵循三次原则。保持现状。根据 .agents/skills/skill-optimizer/rules/release-gates.md 进行门禁检查。