Refactoring Surgeon

重构外科医生

Expert code refactoring specialist focused on improving code quality without changing behavior.

专注于在不改变代码行为的前提下提升代码质量的专业代码重构专家。

Quick Start

快速开始

Ensure tests exist - Never refactor without a safety net
Identify the smell - Name the specific code smell you're addressing
Make small changes - One refactoring at a time, commit frequently
Run tests after each change - Behavior must remain identical
Don't add features - Refactoring ≠ enhancement
Document significant changes - Explain the "why" for future maintainers

确保测试存在 - 永远不要在没有安全保障的情况下进行重构
识别代码异味 - 明确你要解决的具体代码异味类型
进行小幅修改 - 每次只做一项重构，频繁提交代码
每次修改后运行测试 - 代码行为必须保持完全一致
不要添加新功能 - 重构 ≠ 功能增强
记录重大修改 - 为未来的维护者说明修改的原因

Core Capabilities

核心能力

Category	Techniques
Extraction	Extract Method, Extract Class, Extract Interface
Movement	Move Method, Move Field, Inline Method
Simplification	Replace Conditional with Polymorphism, Decompose Conditional
Organization	Introduce Parameter Object, Replace Magic Numbers
Legacy Migration	Strangler Fig, Branch by Abstraction, Parallel Change

分类	技术手段
提取类重构	Extract Method, Extract Class, Extract Interface
移动类重构	Move Method, Move Field, Inline Method
简化类重构	Replace Conditional with Polymorphism, Decompose Conditional
组织类重构	Introduce Parameter Object, Replace Magic Numbers
遗留代码迁移	Strangler Fig, Branch by Abstraction, Parallel Change

Code Smells Reference

代码异味参考

Bloaters

臃肿型代码异味

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│    Long Method      │    │    Large Class      │    │   Long Parameter    │
│  > 20 lines?        │    │  > 200 lines?       │    │       List          │
│  → Extract Method   │    │  → Extract Class    │    │  → Parameter Object │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│    Long Method      │    │    Large Class      │    │   Long Parameter    │
│  > 20 lines?        │    │  > 200 lines?       │    │       List          │
│  → Extract Method   │    │  → Extract Class    │    │  → Parameter Object │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘

OO Abusers

面向对象滥用型代码异味

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│  Switch Statements  │    │   Refused Bequest   │    │   Parallel          │
│  Type-checking?     │    │  Unused inheritance?│    │   Hierarchies       │
│  → Polymorphism     │    │  → Delegation       │    │  → Move Method      │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│  Switch Statements  │    │   Refused Bequest   │    │   Parallel          │
│  Type-checking?     │    │  Unused inheritance?│    │   Hierarchies       │
│  → Polymorphism     │    │  → Delegation       │    │  → Move Method      │
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘

Change Preventers

变更阻碍型代码异味

┌─────────────────────┐    ┌─────────────────────┐
│  Divergent Change   │    │  Shotgun Surgery    │
│  One class, many    │    │  One change, many   │
│  reasons to change? │    │  classes affected?  │
│  → Extract Class    │    │  → Move/Inline      │
└─────────────────────┘    └─────────────────────┘

┌─────────────────────┐    ┌─────────────────────┐
│  Divergent Change   │    │  Shotgun Surgery    │
│  One class, many    │    │  One change, many   │
│  reasons to change? │    │  classes affected?  │
│  → Extract Class    │    │  → Move/Inline      │
└─────────────────────┘    └─────────────────────┘

Reference Examples

参考示例

Complete refactoring examples in

./references/

:

File	Pattern	Use Case
`extract-method.ts`	Extract Method	Long methods → focused functions
`replace-conditional-polymorphism.ts`	Replace Conditional	switch/if → polymorphic classes
`introduce-parameter-object.ts`	Parameter Object	Long params → structured objects
`strangler-fig-pattern.ts`	Strangler Fig	Legacy code → gradual migration

./references/

目录下包含完整的重构示例：

文件	模式	适用场景
`extract-method.ts`	Extract Method	冗长方法 → 单一职责函数
`replace-conditional-polymorphism.ts`	Replace Conditional	switch/if语句 → 多态类
`introduce-parameter-object.ts`	Parameter Object	冗长参数列表 → 结构化对象
`strangler-fig-pattern.ts`	Strangler Fig	遗留代码 → 渐进式迁移

Anti-Patterns (10 Critical Mistakes)

反模式（10个关键错误）

1. Big Bang Refactoring

1. 大爆炸式重构

Symptom: Rewriting entire modules in one massive change Fix: Strangler fig pattern, small incremental changes with tests

症状：一次性重写整个模块 修复方案：采用Strangler Fig模式，结合测试进行小幅增量修改

2. Refactoring Without Tests

2. 无测试重构

Symptom: Changing structure without test coverage Fix: Write characterization tests first, add coverage for affected areas

症状：在没有测试覆盖的情况下修改代码结构 修复方案：先编写特征测试，为受影响的代码添加测试覆盖

3. Premature Abstraction

3. 过早抽象

Symptom: Creating generic frameworks "for future flexibility" Fix: Wait for three concrete examples before abstracting (Rule of Three)

症状：为了“未来灵活性”创建通用框架 修复方案：遵循三次法则，等到出现三个具体示例后再进行抽象

4. Renaming Without IDE Support

4. 无IDE支持的重命名

Symptom: Find-and-replace that misses occurrences Fix: Use IDE refactoring tools, search for usages first

症状：使用查找替换导致遗漏部分引用 修复方案：使用IDE重构工具，先搜索所有引用

5. Mixing Refactoring and Features

5. 重构与功能混合

Symptom: Adding new functionality while restructuring Fix: Separate commits - refactor first, then add features

症状：在重构代码结构的同时添加新功能 修复方案：拆分提交 - 先完成重构，再添加新功能

6. Ignoring Code Reviews

6. 忽略代码评审

Symptom: Large refactoring PRs that are hard to review Fix: Small, focused PRs with clear commit messages

症状：提交难以评审的大型重构PR 修复方案：提交小型、聚焦的PR，并附带清晰的提交信息

7. Over-Abstracting

7. 过度抽象

Symptom: Three layers of abstraction for a simple operation Fix: YAGNI - start concrete, abstract when patterns emerge

症状：为简单操作添加三层抽象 修复方案：遵循YAGNI原则 - 先实现具体逻辑，等模式出现后再抽象

8. Incomplete Refactoring

8. 不完整重构

Symptom: Starting Extract Method but leaving partial duplication Fix: Complete the refactoring or revert - no half-measures

症状：开始Extract Method但仍存在部分代码重复 修复方案：完成重构或回滚 - 绝不半途而废

9. Refactoring Production During Incidents

9. 事故期间重构生产代码

Symptom: "I'll just clean this up while I'm here..." Fix: Never refactor during incidents - fix the bug, create a ticket

症状：“我顺便把这里清理一下...” 修复方案：事故期间绝不重构 - 先修复Bug，再创建工单后续处理

10. Not Measuring Improvement

10. 不衡量改进效果

Symptom: Refactoring without knowing if it helped Fix: Track metrics: complexity, test coverage, build time

症状：进行重构但不确定是否有帮助 修复方案：跟踪指标：复杂度、测试覆盖率、构建时间

Safety Checklist

安全检查清单

Quality Checklist

质量检查清单

No behavior changes (tests prove this)
Improved readability
Reduced complexity (cyclomatic, cognitive)
Better adherence to SOLID principles
Removed duplication (DRY)
More testable code
Clear naming
Appropriate abstractions (not over-engineered)

代码行为无变化（由测试验证）
可读性提升
复杂度降低（圈复杂度、认知复杂度）
更符合SOLID原则
消除代码重复（DRY）
代码更易于测试
命名清晰
抽象程度适当（不过度设计）

Validation Script

验证脚本

Run

./scripts/validate-refactoring.sh

to check:

Test coverage presence
Code smell indicators
Duplication patterns
Complexity metrics
SOLID violations
Refactoring safety (git, uncommitted changes)

运行

./scripts/validate-refactoring.sh

以检查：

测试覆盖率是否存在
代码异味指标
代码重复模式
复杂度指标
SOLID原则违反情况
重构安全性（Git状态、未提交变更）

refactoring-surgeon

Original

Translation