code-refactor

# 代码重构方法论 从软件设计本质层面提炼可复用的重构方法论，指导代码质量改进。 ## 一、设计哲学与原理 ### 1.1 代码退化根源 **退化机制**：复制粘贴→知识分裂，快速修复→破坏设计意图，需求变更→补丁叠加，知识遗忘→意图模糊 **退化规律**：所有代码都会退化，重构是必然的维护行为 ### 1.2 类型系统本质 ```text 类型 = 值集合 + 操作集合 + 不变量 ``` **类型退化链条**：强类型→弱类型，枚举→字符串常量→魔法字符串→硬编码，编译检查→运行时判断→运行时错误 **退化信号**：值被用来判断行为、编译期错误变成运行时错误、枚举退化成字符串常量 ### 1.3 多态本质 ```text 多态 = 同一接口 + 不同行为 ``` | 分发方式 | 时机 | 安全性 | | ----------- | ------ | ------------ | | if-else | 运行时 | 低（易遗漏） | | switch | 运行时 | 中 | | 虚方法 | 运行时 | 高 | | 模板/泛型 | 编译期 | 最高 | **本质**：用类型系统分发行为，而非运行时判断 ### 1.4 数据结构本质 ```text 数据结构 = 数据组织方式 + 访问操作 + 复杂度保证 ``` | 访问模式 | 推荐 | 不推荐 | 原因 | | -------- | ----------- | ---------- | -------------| | 顺序遍历 | List/Array | Map | 简单高效 | | Key查找 | Map/HashMap | List | O(1) vs O(n) | | 范围查询 | TreeMap | HashMap | 有序性 | | 去重 | Set | List | 自动去重 | ## 二、方法论体系 ### 2.1 问题识别 ```text 代码异味 → 症状(What) → 根因(Why) → 设计退化(本质) ``` | 退化类型 | 信号 | 根因 | | -------- | ---------- | ------------ | | 类型退化 | 值判断行为 | 类型信息丢失 | | 数据退化 | 嵌套查找 | 结构不匹配 | | 行为退化 | 重复代码 | 缺少抽象 | | 关系退化 | 紧耦合 | 依赖方向错误 | ### 2.2 三问分析法 - Q1: 为什么出现？→ 根因 - Q2: 本质是什么？→ 抽象 - Q3: 正确设计应该是什么？→ 目标 ### 2.3 决策框架 | 问题本质 | 推荐方案 | 收益 | | -------- | --------------- | ---------------- | | 类型退化 | 多态/策略模式 | 类型安全、易扩展 | | 数据退化 | 重建索引/换容器 | 性能提升 | | 行为退化 | 提取抽象 | 减少重复 | | 关系退化 | 解耦/依赖注入 | 降低耦合 | **决策原则**：优先解决根本原因；选择收益/成本比最高方案；小步快跑，持续验证 ### 2.4 执行框架 ```text 识别 → 分析 → 方案 → 小步 → 验证 → 提交 ``` **小步原则**：每次只改一个问题，每次改完可编译，每次提交可回退 ### 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](templates/strategy-pattern.md) 核心五步：识别变体 → 定义接口 → 实现策略 → 注入策略 → 替换判断 ## 六、性能优化 ### 6.1 算法优化 | 问题 | 原方案 | 优化方案 | 复杂度变化 | | ---------- | ------------- | ----------- | ---------- | | 嵌套filter | O(n²)~O(n³) | 预建Map索引 | → O(n) | | 不必要排序 | O(n log n) | 删除 | → O(0) | | 频繁查找 | List遍历O(n) | Map查找 | → O(1) | ### 6.2 容器选择 | 场景 | 推荐 | 原因 | | -------- | ------------------------ | -------- | | 去重 | Set | 自动去重 | | 查找 | Map | O(1)查找 | | 顺序遍历 | List | 简单高效 | | 不变集合 | Collections.emptyList() | 零内存 | ## 七、避坑指南 | 错误 | 表现 | 解决 | | ------------ | ------------------ | ---------------------- | | 策略遗漏 | 某分支无匹配策略 | 添加DefaultStrategy兜底 | | supports错误 | 策略匹配失败 | 单元测试验证 | | 策略冲突 | 多个策略匹配 | 用@Order控制优先级 | | 忘记注入 | NullPointerException | 添加@Autowired | **继承vs组合**：优先组合，继承易导致语义错误和内存浪费 **过度设计**：只出现1-2次的if-else保持简单；行为无差异不需要策略；稳定不变直接用枚举switch ## 模板引用 | 模板 | 路径 | | ------------ | -------------------------------------------------------------- | | 问题分析报告 | [templates/analysis-report.md](templates/analysis-report.md) | | 效果评估 | [templates/evaluation.md](templates/evaluation.md) | | 策略模式重构 | [templates/strategy-pattern.md](templates/strategy-pattern.md) | | 应用案例 | [templates/case-studies.md](templates/case-studies.md) |