代码重构方法论

从软件设计本质层面提炼可复用的重构方法论，指导代码质量改进。

适用场景

• 代码出现明确坏味道，需要改善结构
• 技术债累积影响迭代效率
• 重构前需要评估风险与收益

前置条件

1. 已有可执行的测试或可复现的验证手段；没有测试时先补测试再重构。
2. 明确本次重构的目标与边界，不与其他需求混做。
3. 通过 skill code-review 或 code-detect-problem 获得问题清单。

执行步骤

1. 识别退化信号，确认根因属于类型、数据、行为还是关系退化。
2. 按三问分析法确定目标设计。
3. 选择重构策略，评估影响范围与回滚方式。
4. 小步实施，每一步保持可编译、可测试。
5. 用测试与指标验证效果，记录前后对比。
6. 分步提交，每次提交只包含一个可回退的改动。

一、设计哲学与原理

1.1 代码退化根源

退化机制：复制粘贴→知识分裂，快速修复→破坏设计意图，需求变更→补丁叠加，知识遗忘→意图模糊

退化规律：所有代码都会退化，重构是必然的维护行为

1.2 类型系统本质

类型 = 值集合 + 操作集合 + 不变量

类型退化链条：强类型→弱类型，枚举→字符串常量→魔法字符串→硬编码，编译检查→运行时判断→运行时错误

退化信号：值被用来判断行为、编译期错误变成运行时错误、枚举退化成字符串常量

1.3 多态本质

多态 = 同一接口 + 不同行为

本质：用类型系统分发行为，而非运行时判断

1.4 数据结构本质

数据结构 = 数据组织方式 + 访问操作 + 复杂度保证

二、方法论体系

2.1 问题识别

代码异味 → 症状(What) → 根因(Why) → 设计退化(本质)

2.2 三问分析法

• Q1: 为什么出现？→ 根因
• Q2: 本质是什么？→ 抽象
• Q3: 正确设计应该是什么？→ 目标

2.3 决策框架

决策原则：优先解决根本原因；选择收益/成本比最高方案；小步快跑，持续验证

2.4 执行框架

识别 → 分析 → 方案 → 小步 → 验证 → 提交

小步原则：每次只改一个问题，每次改完可编译，每次提交可回退

2.5 验证框架

三、信号识别清单

类型退化：if (xxx.equals(value)) 多次、枚举只定义字符串常量、实体字段String而非枚举、switch-case on String

数据退化：三层以上嵌套循环、List遍历查找、循环内.filter()、重复数据转换

行为退化：相似代码块>5行、类>500行、方法>50行、参数>5个

关系退化：循环依赖、高耦合、依赖具体实现而非接口

AST 自动信号识别（ast-grep-mcp）

当 ast-grep-mcp 可用时，优先使用 find_code_by_rule 自动扫描退化信号，替代人工 grep。

类型退化 — 字符串常量比较：

find_code_by_rule(
  project_folder: "<project_root>",
  yaml: '''
    id: type-degradation-string-compare
    language: java
    rule:
      pattern: '$VAR.equals("$VAL")'
    constraints:
      VAL:
        regex: '(?i)(ACTIVE|INACTIVE|PENDING|APPROVED|REJECTED|ENABLED|DISABLED|SUCCESS|FAILED|RUNNING|COMPLETED)'
  '''
)

类型退化 — if-else 链：

find_code_by_rule(
  project_folder: "<project_root>",
  yaml: '''
    id: if-else-chain
    language: java
    rule:
      pattern: |
        if ($COND) {
          $$$BODY
        } else if ($COND2) {
          $$$BODY2
        }
  '''
)

关系退化 — @Autowired 过多：

find_code_by_rule(
  project_folder: "<project_root>",
  yaml: '''
    id: too-many-autowired
    language: java
    rule:
      pattern: '@Autowired'
  '''
)

单个类 @Autowired 数量 > 5 提示耦合过高，需人工统计。

行为退化 — 方法过长（辅助定位）：

find_code(pattern: 'public void $METHOD($$$ARGS) { $$$BODY }', language: java, project_folder: "<dir>")

使用方式：

1. 在"问题识别"阶段，先调用上述 rule 自动扫描
2. 命中结果作为退化信号候选，人工确认后进入三问分析法
3. MCP 不可用时回退到 grep/rg 人工扫描

四、决策树

类型退化：大量if-else → 行为差异明显？→ 是：多态(变体稳定？→ 是：继承 / 否：策略模式) / 否：配置表

数据退化：嵌套循环查找 → 访问模式明确？→ 是：重建索引(查找频繁？→ 是：Map索引 / 否：保持原状) / 否：重构数据流

五、策略模式重构

详见 templates/strategy-pattern.md

核心五步：识别变体 → 定义接口 → 实现策略 → 注入策略 → 替换判断

六、性能优化

6.1 算法优化

6.2 容器选择

七、避坑指南

继承vs组合：优先组合，继承易导致语义错误和内存浪费

过度设计：只出现1-2次的if-else保持简单；行为无差异不需要策略；稳定不变直接用枚举switch

完成标准

• 每个改动可独立编译、测试通过
• 行为等价性已由测试或对比验证
• 圈复杂度、重复率等指标有前后数据
• 未引入新的抽象过度或未使用代码
• 改动已分步提交，可逐条回退

模板引用

本文件中的 templates/... 均指本技能目录下的 templates/ 子目录。