python-refactor

Python 重构

将复杂的 Python 代码转化为清晰、易维护的代码，同时确保正确性。采用分阶段工作流，通过安全设计和持续验证保障质量。关于深入参考资料（反模式、OOP 原则、认知复杂度、回归预防），请参阅 references/ 目录。

适用场景

• 明确提出“易懂”“可读”“易维护”“整洁”或“重构”需求
• 代码审查指出代码理解或可维护性方面的问题
• 现代化遗留代码
• 新人入职或教育场景
• 复杂度指标超过阈值
• 警示信号：文件超过 500 行，函数分散且存在全局状态；包含多个 global 语句；缺乏清晰的模块／类组织；配置与业务逻辑混杂

不适用场景

• 代码对性能要求极高，且性能分析表明应优先进行性能优化
• 代码计划删除或替换
• 应通过向上游贡献来解决外部依赖问题
• 用户明确要求优先优化性能，而非提高可读性

核心原则（按优先级排序）

1. 复杂代码优先采用结构化 OOP——共享状态、多种关注点、分散的全局变量，都意味着应重构为类或模块。（但是：包含纯函数的简单模块、click/argparse CLI 和函数式流水线，不必强行改成类。）
2. 清晰胜于巧妙——显式优于隐式
3. 保持正确性——所有测试均通过，行为保持一致
4. 单一职责——每个类／函数只做一件事（SOLID）
5. 结构自解释——代码说明“是什么”，注释说明“为什么”
6. 渐进式呈现——分层展现复杂性
7. 合理的性能——未经明确批准，性能绝不能降低超过 2 倍

硬性约束

• 安全设计——破坏性变更必须使用强制迁移清单。CREATE → SEARCH → MIGRATE → VERIFY → 然后才能 REMOVE。迁移未 100% 验证前，绝不能删除。
• 先进行静态分析——在测试前运行 flake8 --select=F821,E0602（或 ruff check --select=F821）。立即捕获 NameError。
• 保持行为不变——完成后，所有现有测试必须通过。
• 不得造成性能回退——未经明确批准，性能绝不能降低超过 2 倍。
• 不得更改 API——公共 API 保持不变，除非用户明确要求并有文档记录。
• 避免过度设计——简单的代码保持简单。
• 避免魔法——不使用框架魔法或元编程，除非绝对必要。
• 持续验证——每次逻辑变更后都进行静态分析和测试。

回归预防（强制要求）

重构绝不能引入回归。 每次开始前，请阅读 references/REGRESSION_PREVENTION.md。

每次开始前：

• 测试套件 100% 通过
• 目标代码覆盖率 ≥ 80%（未达到时，先编写测试）
• 为关键边界情况捕获黄金输出
• 保存静态分析基线

每次微小变更后（不是最后统一检查，而是每一次变更后）：

• flake8 --select=F821,E999 → 0 个错误
• pytest -x → 全部通过
• 抽查 1 个边界情况，确认行为未变

如果任一检查失败：停止 → 回滚 → 分析 → 修正方案 → 重试。

任何回归 = 彻底失败。

工作流（4 个阶段）

阶段 1：分析

1. 阅读整个代码库部分。
2. 使用 references/anti-patterns.md 识别可读性问题（脚本式结构／全局状态、上帝对象、嵌套条件、长函数、魔法数字、晦涩命名）。
3. 根据 references/oop_principles.md 评估架构（恰当的类／模块、封装状态、职责分离、SOLID、依赖注入与硬编码依赖）。
4. 使用 scripts/measure_complexity.py 或 scripts/analyze_multi_metrics.py 测量当前指标。
5. 运行 lint 分析（见下方“工具”）。
6. 检查测试覆盖率，找出需要在重构前补齐的缺口。
7. 使用 assets/templates/analysis_template.md 编写文档。

输出：按影响和风险排序的问题清单。

阶段 2：规划

1. 对每项变更进行分类：
   • 非破坏性（重命名、文档、类型提示）→ 低风险
   • 破坏性（移除全局变量、删除函数、替换 API）→ 高风险
2. 对于破坏性变更——迁移计划为必需项：
   • 搜索所有待移除元素的用法
   • 记录每处用法（文件、行号、类型）
   • 没有完整的迁移计划 = 无法进行破坏性变更
3. 评估每项变更的风险（低／中／高）
4. 绘制依赖关系图——哪些内容依赖此代码？
5. 制定测试策略——需要哪些测试？可能会出什么问题？
6. 按风险从低到高排列变更顺序
7. 记录预期的指标改进

输出：重构计划、按顺序排列的变更、迁移计划、测试策略、回滚计划。

阶段 3：执行

非破坏性（随时可安全执行）

1. 重命名以提升清晰度
2. 将魔法数字／字符串提取为具名常量
3. 添加／改进文档和类型提示
4. 添加守卫子句以减少嵌套

破坏性（严格流程）

1. 创建新结构（不移除任何内容）——编写新类／函数及测试
2. 搜索待移除元素的所有用法
3. 创建迁移清单，记录找到的每一处用法
4. 迁移，每次处理一处用法，完成后勾选清单，并在每次迁移后运行静态分析和测试
5. 验证迁移是否完成——重新搜索，确认不再找到旧引用
6. 只有在 100% 确认迁移完成后，才能移除旧代码

执行规则

• 对于破坏性变更，绝不可跳过迁移清单
• 先运行静态分析，再运行测试
• 一次处理一种模式——绝不可在一次变更中混合多种重构模式
• 原子提交——每个迁移步骤单独提交
• 遇到任何错误（静态分析或测试失败）都立即停止 → 立即修复或回滚

建议顺序

1. 将脚本式代码转换为规范的架构（references/examples/script_to_oop_transformation.md）
2. 重命名以提升清晰度
3. 将魔法数字／字符串提取为常量／枚举
4. 改进文档和类型提示
5. 提取方法以缩短函数长度
6. 使用守卫子句简化条件语句
7. 减少嵌套深度
8. 最终审查：关注点分离

阶段 4：验证

1. 首先进行静态分析：

   flake8 <file> --select=F821,E0602          # undefined names/variables -- MUST be 0
   flake8 <file> --select=F401                # unused imports
   flake8 <file>                              # full quality check
   

2. 运行完整测试套件 → 必须全部通过。
3. 架构验证：消除／封装全局状态，使用恰当的模块／类，分离职责，符合 SOLID 原则。
4. 使用 scripts/measure_complexity.py 或 scripts/analyze_multi_metrics.py 对比变更前后的指标。
5. 对热点路径使用 scripts/benchmark_changes.py 检查性能回归。
6. 使用 assets/templates/summary_template.md 编写总结报告。
7. 在以下情况下标记为需要人工审查：性能下降 > 10%、公共 API 签名发生变化、测试覆盖率降低、架构发生重大变更。

重构模式（目录摘要）

完整目录及示例见 references/patterns.md。主要模式：

• 守卫子句——使用提前返回替代嵌套条件语句
• 提取方法——将大型函数拆分为职责明确的单元（重置嵌套计数器——对认知复杂度最有效）
• 字典分派——用查找表替代 if-elif 链
• Match 语句（Py 3.10+）——总计只计为 +1，不按分支计数
• 具名布尔条件——将复杂的布尔表达式提取到具名变量中
• 封装全局状态——将全局变量移入类中并进行适当封装
• 分组相关函数——按职责将分散的函数整理到类中
• 创建领域模型——用 dataclass 和枚举替代原始 dict
• 应用依赖注入——用注入的依赖替代硬编码的依赖

认知复杂度的计算规则和降低策略见 references/cognitive_complexity_guide.md。

命名约定

• 变量：使用描述性名称，布尔值采用 is_active / has_permission / can_edit，集合使用复数形式
• 函数：动词 + 对象（calculate_total、validate_email）；布尔查询采用 is_valid() / has_items()
• 常量：使用 UPPERCASE_WITH_UNDERSCORES；替换魔法数字/字符串
• 类：采用 PascalCase 名词（UserAccount、PaymentProcessor）

需要修复的反模式（按优先级排序）

完整目录：references/anti-patterns.md。

• 严重：类似脚本/过程式的代码，带有全局状态；上帝对象 / 上帝类
• 高：复杂的嵌套条件（> 3 层）、过长的函数（> 30 行）、魔法数字、晦涩的名称、缺少类型提示、缺少文档字符串
• 中：重复代码、基本类型偏执、过长的参数列表（> 5 个）
• 低：命名不一致、多余注释、未使用的导入

工具

首选技术栈：Ruff + Complexipy（新项目推荐）

uv tool install ruff complexipy radon wily

ruff check src/                                 # fast linting (Rust, replaces flake8+plugins)
complexipy src/ --max-complexity-allowed 15     # cognitive complexity (Rust)
radon mi src/ -s                                # maintainability index

完整配置（pyproject.toml、pre-commit、GitHub Actions）：references/cognitive_complexity_guide.md。

替代方案：flake8 + 精选插件

对于已采用 flake8 的项目，请参阅 references/flake8_plugins_guide.md（精选的 16 个插件列表）。

多指标分析

scripts/analyze_multi_metrics.py 将 complexipy + radon + 可维护性指数整合到一份报告中。

指标	工具	用途
认知复杂度	complexipy	人类理解难度
圈复杂度	ruff (C901)、radon	测试规划
可维护性指数	radon	整体代码健康状况

指标目标

• 圈复杂度：每个函数 < 10（警告值 15，错误值 20）
• 认知复杂度：每个函数 < 15（SonarQube 默认值；警告值 20）
• 函数长度：< 30 行（警告值 50）
• 嵌套深度：≤ 3 层
• 文档字符串覆盖率：公共函数 > 80%
• 类型提示覆盖率：公共 API > 90%

使用 Wily 进行历史跟踪

趋势很重要，不应只关注阈值。设置 + CI 集成：references/cognitive_complexity_guide.md。

常见重构错误

完整指南：references/REGRESSION_PREVENTION.md。需要注意的陷阱：

1. 迁移不完整——未迁移所有用法就移除旧代码（会导致 NameError）。
2. 模式应用不完整——只对部分函数应用重构，而非全部。
3. 破坏公共 API——更改外部代码正在使用的签名。
4. 假设测试覆盖一切——测试通过，但仍会出现运行时错误（请运行静态分析！）。

何时选择哪种工具

• clean-code（跨语言插件）——多语言的表面整理；重命名局部变量、改进注释、简化结构。回归风险最低。适用于“让代码更易读”“整理命名”等需求。
• python-refactor（本技能）——仅针对 Python 的深度重构。面向对象转换、SOLID、复杂度指标、迁移检查清单、基准验证。适用于“重构此模块”“降低复杂度”“转换为面向对象”等需求。

升级路径：clean-code → python-refactor（从最稳妥到最全面）。

集成

• python-tdd——在重构前设置测试，之后验证覆盖率
• python-performance-optimization——重构前后进行深度性能分析
• python-packaging——若重构库，则处理 pyproject.toml + 分发
• uv-package-manager——使用 uv run ruff、uv run complexipy 执行工具
• async-python-patterns——重构异步代码时参考异步模式

何时不应重构

对性能至关重要且经过优化的代码（先进行性能分析）、计划删除的代码、外部依赖（向上游贡献）、稳定且无人需要修改的遗留代码。

局限性

无法降低算法复杂度（这需要修改算法）。无法添加代码/注释中未包含的领域知识。没有测试就无法保证正确性。风格偏好因团队而异——请根据团队约定调整。

示例

references/examples/：

• script_to_oop_transformation.md -- 脚本 → 简洁的面向对象架构（旗舰案例研究）
• python_complexity_reduction.md -- 嵌套条件语句和长函数
• typescript_naming_improvements.md -- 命名模式（跨语言参考）

成功标准

1. 零回归 -- 所有测试通过，行为保持不变
2. 文档所述关键案例与黄金基准匹配
3. 复杂度指标有所改善（在摘要中记录）
4. 性能回归不超过 10%（或获得明确批准）
5. 文档覆盖率提高
6. 代码更易于人类理解
7. 没有新增安全漏洞
8. Git 历史记录原子化且文档完善
9. Wily 趋势 -- 复杂度较上一提交没有增加
10. 静态分析显示有所改进