Smart Refactoring Advisor
技能描述
智能代码重构建议器 - 使用 AST 分析、设计模式识别和 SOLID 原则检测代码质量问题，生成可执行的重构建议和代码示例。
触发场景
当用户提到以下关键词时触发：
- "代码重构"、"重构建议"、"优化代码结构"
- "设计模式"、"SOLID原则"、"代码质量"
- "消除重复代码"、"简化复杂逻辑"
- "重构分析"、"代码改进建议"
适用范围
- 识别代码反模式（God Class、Spaghetti Code、Long Method 等）
- 检测 SOLID 原则违反
- 分析设计模式应用机会
- 生成重构前后对比示例
- 支持多种重构策略（提取方法、移动方法、重命名、多态替换条件等）
工作流程
阶段 1: 代码分析 (Analysis)
目标: 收集代码结构信息，识别问题点
执行步骤:
1. 使用 AST 解析目标代码文件或目录
2. 计算代码复杂度指标：
- 圈复杂度 (Cyclomatic Complexity)
- 方法长度 (Method Length)
- 类规模 (Class Size)
- 参数数量 (Parameter Count)
- 嵌套深度 (Nesting Depth)
3. 检测设计模式反模式：
- God Object/Class
- Long Method
- Large Class
- Long Parameter List
- Duplicated Code
- Dead Code
- Speculative Generality
4. 评估 SOLID 原则符合度：
- 单一职责原则 (SRP)
- 开闭原则 (OCP)
- 里氏替换原则 (LSP)
- 接口隔离原则 (ISP)
- 依赖倒置原则 (DIP)
输出: analysis_report.json
阶段 2: 问题优先级排序 (Prioritization)
目标: 根据影响范围和修复成本确定重构顺序
执行步骤:
1. 按以下维度评估每个问题：
- 影响范围（1-10分）
- 修复复杂度（1-10分）
- 风险等级（High/Medium/Low）
- 业务价值（1-10分）
2. 计算优先级分数：Priority = (影响范围 × 业务价值) / 修复复杂度
3. 将问题分为三个梯队：
- Quick Wins: 高影响、低复杂度（立即执行）
- Planned Efforts: 高影响、高复杂度（需要规划）
- Technical Debts: 低影响、低优先级（记录追踪）
输出: prioritized_issues.json
阶段 3: 重构方案生成 (Refactoring Plan)
目标: 为每个高优先级问题生成具体重构方案
执行步骤:
1. 针对每类问题选择重构策略：
- Long Method: 提取方法、内联临时变量、以查询替换临时变量
- Large Class: 提取类、提取子类、提取接口
- Long Parameter List: 引入参数对象、移除设值函数、保持对象完整
- Duplicated Code: 提取方法、上移方法、模板方法模式
- Conditional Logic: 以多态替换条件、以策略模式替换条件
- God Class: 提取类、观察者模式、委托模式
2. 生成重构步骤（每个步骤包含）：
- 步骤名称
- 操作类型（Extract Method/Move Method/Rename 等）
- 涉及的代码位置（文件名:行号）
- 重构前代码片段
- 重构后代码片段
- 测试验证要求
3. 应用自动化重构脚本（如支持）或提供手动执行指导
输出: refactoring_plan.md
阶段 4: 执行监控 (Execution Monitoring)
目标: 跟踪重构进度，验证重构结果
执行步骤:
1. 读取重构计划，标记当前执行步骤
2. 在每个步骤执行后：
- 运行单元测试验证功能正确性
- 检查代码风格和静态分析规则
- 确认无新增警告或错误
3. 更新执行状态：
- ✅ Completed: 测试通过，无问题
- ⚠️ Warning: 测试通过，但有新警告
- ❌ Failed: 测试失败或代码错误
4. 生成进度报告：execution_report.md
阶段 5: 结果验证 (Validation)
目标: 确认重构达到预期效果
执行步骤:
1. 对比重构前后指标：
- 复杂度降低百分比
- 代码行数变化
- 测试覆盖率变化
- SOLID 原则符合度提升
2. 验证业务功能：
- 所有测试用例通过
- 无回归缺陷
- 性能无劣化
3. 生成重构报告：
- 重构前后对比截图
- 指标改进数据
- 后续建议（如需要进一步重构）
输出: final_report.md
输入参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| target_path | string | 是 | - | 要分析的代码文件或目录路径 |
| language | string | 否 | auto | 代码语言（python/java/javascript/go/cpp） |
| output_dir | string | 否 | ./refactoring_reports | 报告输出目录 |
| max_complexity | integer | 否 | 10 | 方法圈复杂度阈值 |
| max_method_lines | integer | 否 | 30 | 方法最大行数阈值 |
| max_class_lines | integer | 否 | 500 | 类最大行数阈值 |
| max_parameters | integer | 否 | 4 | 方法最大参数数阈值 |
| focus_issues | array | 否 | [] | 指定关注的问题类型列表 |
| auto_fix | boolean | 否 | false | 是否自动执行低风险重构 |
| dry_run | boolean | 否 | true | 是否仅生成建议不执行 |
输出产物
1. 分析报告 (analysis_report.json)
{
"scan_info": {
"timestamp": "2026-08-17T10:00:00Z",
"language": "python",
"files_scanned": 42,
"total_lines": 8500
},
"metrics": {
"average_complexity": 5.2,
"max_complexity": 28,
"average_method_length": 18,
"max_method_length": 120
},
"issues": [
{
"type": "long_method",
"file": "src/services/order_processor.py",
"location": "OrderProcessor.process_order:45-180",
"severity": "high",
"complexity": 28,
"lines": 135,
"description": "方法 process_order 过长（135行），圈复杂度28，违反单一职责原则",
"suggested_refactorings": [
"extract_method: validate_order",
"extract_method: calculate_discounts",
"extract_method: apply_business_rules"
]
}
],
"solid_violations": {
"srp": [
{
"file": "src/services/user_service.py",
"class": "UserService",
"reason": "类包含用户认证、授权、通知三个职责",
"recommendation": "拆分为 AuthenticationService, AuthorizationService, NotificationService"
}
]
}
}
2. 重构计划 (refactoring_plan.md)
# 重构计划：订单处理服务
## 优先级排序
| 优先级 | 问题类型 | 文件 | 影响 | 复杂度 | 得分 |
|--------|---------|------|------|--------|------|
| P0 | Long Method | order_processor.py | 10 | 5 | 20.0 |
| P1 | God Class | user_service.py | 9 | 7 | 12.9 |
| P2 | Duplicated Code | payment_*.py | 7 | 3 | 21.0 |
## 详细重构方案
### 问题 #1: Long Method - process_order
**位置**: `src/services/order_processor.py:45-180`
**当前代码**:
```python
def process_order(self, order):
# 135行复杂逻辑...
重构策略: 提取方法 (Extract Method)
步骤:
1. 提取 validate_order(order) -> bool
- 重构后: 将订单验证逻辑（行 48-75）提取为独立方法
- 测试: 验证有效订单通过，无效订单抛出异常
-
提取
calculate_discounts(order) -> Decimal
- 重构后: 将折扣计算逻辑（行 78-105）提取为独立方法
- 测试: 验证不同折扣规则正确计算 -
提取
apply_business_rules(order) -> Order
- 重构后: 将业务规则应用逻辑（行 108-140）提取为独立方法
- 测试: 验证业务规则正确应用
重构后代码:
def process_order(self, order):
self.validate_order(order)
order.discounts = self.calculate_discounts(order)
self.apply_business_rules(order)
return self.save_order(order)
def validate_order(self, order):
# 28行清晰的验证逻辑
def calculate_discounts(self, order):
# 27行折扣计算逻辑
def apply_business_rules(self, order):
# 32行业务规则逻辑
预期效果:
- 圈复杂度: 28 → 5（降低82%）
- 方法长度: 135行 → 平均28行（降低79%）
- 可读性: 显著提升
- 可测试性: 单元测试覆盖率从45%提升至90%
### 3. 执行报告 (`execution_report.md`)
```markdown
# 重构执行报告
## 执行概况
- **开始时间**: 2026-08-17 10:00:00
- **结束时间**: 2026-08-17 10:45:23
- **总耗时**: 45分钟
- **成功率**: 95%（19/20步骤成功）
## 执行明细
### ✅ 提取方法: validate_order
- **状态**: 成功
- **耗时**: 5分钟
- **测试结果**: 全部通过（12个测试用例）
- **代码检查**: 无警告
### ✅ 提取方法: calculate_discounts
- **状态**: 成功
- **耗时**: 8分钟
- **测试结果**: 全部通过（15个测试用例）
- **代码检查**: 无警告
### ⚠️ 提取方法: apply_business_rules
- **状态**: 警告
- **耗时**: 12分钟
- **测试结果**: 全部通过，但新增2个代码风格警告
- **代码检查**: 建议: 缺少类型注解
- **处理**: 已自动添加类型注解
## 指标对比
| 指标 | 重构前 | 重构后 | 改进 |
|------|--------|--------|------|
| 平均圈复杂度 | 12.5 | 4.8 | ↓ 62% |
| 方法平均行数 | 45 | 18 | ↓ 60% |
| 类平均行数 | 850 | 420 | ↓ 51% |
| SOLID符合度 | 42% | 85% | ↑ 43% |
| 测试覆盖率 | 45% | 92% | ↑ 47% |
## 后续建议
1. **高优先级**: 继续重构 UserService（God Class问题）
2. **中优先级**: 处理 payment 模块的重复代码
3. **低优先级**: 优化日志记录逻辑
使用示例
示例 1: 分析单个文件
# 用户请求
"分析 src/services/order_processor.py 的重构建议"
# 智能体执行
1. 分析代码结构，检测到3个问题
2. 生成重构计划
3. 提供可执行的重构方案
示例 2: 分析整个模块
# 用户请求
"重构 src/services/ 模块，生成优化建议"
# 智能体执行
1. 扫描目录下所有Python文件
2. 生成问题优先级列表
3. 输出详细重构计划
4. 可选自动执行低风险重构
示例 3: 指定问题类型
# 用户请求
"检查代码中的重复代码和过长方法"
# 智能体执行
focus_issues: ["duplicated_code", "long_method"]
技术实现
AST 分析工具
支持多种语言的 AST 解析：
- Python:
ast+astroid+radon（复杂度计算） - Java:
javalang+PMD+Checkstyle - JavaScript/TypeScript:
@babel/parser+eslint - Go:
go/ast+golint - C/C++:
pycparser+clang
设计模式识别
内置常见设计模式检测器：
- 创建型: 工厂方法、抽象工厂、建造者、单例
- 结构型: 适配器、桥接、组合、装饰器、外观
- 行为型: 策略、观察者、命令、模板方法、状态
反模式检测规则
| 反模式 | 检测标准 | 推荐重构 |
|---|---|---|
| God Class | 方法数>20 或 行数>500 | 提取类、委托模式 |
| Long Method | 行数>30 或 复杂度>10 | 提取方法 |
| Large Class | 行数>500 或 职责>3 | 提取类、接口隔离 |
| Long Parameter List | 参数数>4 | 引入参数对象 |
| Duplicated Code | 相似度>70% | 提取方法、上移方法 |
| Dead Code | 无引用 | 删除 |
配置文件
可在项目根目录创建 .refactoring-rules.yaml 自定义规则：
version: 1.0
language: python
thresholds:
max_complexity: 15
max_method_lines: 40
max_class_lines: 800
max_parameters: 5
exclusions:
- "tests/**"
- "**/__init__.py"
- "**/migrations/**"
custom_rules:
- name: "avoid_nested_loops"
severity: "medium"
description: "避免嵌套循环超过2层"
- name: "enforce_type_hints"
severity: "high"
description: "强制使用类型注解"
priorities:
god_class: 100
long_method: 80
duplicated_code: 70
dead_code: 60
注意事项
- 测试先行: 重构前确保有足够的测试覆盖
- 小步前进: 每次只执行一个重构步骤
- 验证功能: 每步后运行测试确保行为不变
- 版本控制: 重构前提交代码，便于回滚
- 团队沟通: 大规模重构需团队评审和协调
相关技能
python-code-review: Python代码静态审查incremental-code-review: 增量代码审查code-quality-auditor: 代码质量审计
参考资料
- 《重构：改善既有代码的设计》- Martin Fowler
- 《代码整洁之道》- Robert C. Martin
- 《设计模式：可复用面向对象软件的基础》- GoF
- SOLID原则详解: https://en.wikipedia.org/wiki/SOLID
