ascend Python 代码重构
对 Python 代码进行系统性重构，在不改变外部行为的前提下改善内部结构，提升可读性、可维护性和可扩展性。
Overview
- 适用场景：代码重构、代码审查、代码质量改善、技术债务清理
- 核心原则：重构 ≠ 重写；保持接口兼容；有测试才重构；最小改动
- 参考文档：基于 vllm-ascend 仓库 20+ 个真实重构 PR 提炼
- 约束配置：所有数值阈值（函数行数、参数个数等）集中在
refactoring-config.json，用户可自定义或禁用
Quick Reference
| 任务 | 参考文档 |
|---|---|
| 自定义约束阈值 | refactoring-config.json |
| 识别代码问题 | references/code-smells.md |
| 选择设计模式 | references/design-patterns.md |
| 改善可读性 | references/readability.md |
| 实战模式与案例 | references/refactoring-in-practice.md |
| 生成重构文档 | references/refactoring-report.md |
坏味道 → 重构模式 速查表
发现问题后，用此表快速定位解决方案：
| 坏味道 | 推荐模式 | 详细参考 |
|---|---|---|
| 过长函数 | Extract Method、Guard Clause | code-smells.md §1.1 |
| 过长参数列表 | dataclass 参数对象、Builder | design-patterns.md §1.3 |
| 重复代码（横切关注点） | 装饰器模式 | design-patterns.md §2.1 |
| 重复代码（流程骨架相同） | 模板方法 / 策略模式 | practice §模式三 |
| 上帝类 | 按职责拆分、组合替代继承 | practice §模式二、五 |
| 过度继承 | 组合 + Protocol | design-patterns.md §3.1 |
| if-elif 创建实例 | 工厂模式（注册表） | practice §模式一 |
| if-elif 类型分发 | 多态 / singledispatch | design-patterns.md §3.4 |
多个 xxx_with_yyy 函数变体 |
策略模式（Protocol） | practice §模式三 |
| dict/tuple 传递复合数据 | dataclass 类型形式化 | practice §模式七 |
| 魔法数字/字符串 | 枚举（Enum / IntEnum） | code-smells.md §3.3 |
| 自定义实现与上游重复 | 对齐上游 / 继承基类 | practice §模式四 |
| 过大模块（>500 行） | 分离关注点、包化 | practice §模式二 |
| 基准测试证明的劣势路径 | 删除死路径 | practice §模式六 |
重构执行流程
┌─────────────────────────────────────────────────────────┐
│ 0. 前置检查 │
│ - 确认有测试覆盖（无则先补关键路径测试） │
│ - 确认代码可正常运行 │
│ - 评估重构规模 → refactoring-in-practice.md 规模矩阵 │
├─────────────────────────────────────────────────────────┤
│ 1. 识别问题 → references/code-smells.md │
│ - 通读代码，按分类逐项检查 │
│ - 输出问题清单，按严重程度排序 │
├─────────────────────────────────────────────────────────┤
│ 2. 选择策略 → references/refactoring-in-practice.md │
│ - 匹配七大实战模式，选择最合适的重构路径 │
│ - 大型重构制定分阶段计划（参考 Quantization/MoE 案例） │
├─────────────────────────────────────────────────────────┤
│ 3. 结构重构 → references/design-patterns.md │
│ - 对结构性问题选择合适的模式 │
│ - 实施重构，确保接口兼容 │
├─────────────────────────────────────────────────────────┤
│ 4. 打磨优化 → references/readability.md │
│ - 改善命名、结构、类型标注 │
│ - 补充必要注释和文档 │
├─────────────────────────────────────────────────────────┤
│ 5. 验证 │
│ - 运行全部已有测试，确认无回归 │
│ - 运行 linter / type checker │
│ - 对比重构前后，确认行为一致 │
├─────────────────────────────────────────────────────────┤
│ 6. 输出重构文档（可选，用户请求时生成） │
│ - 汇总本次重构的完整记录 │
│ - 生成结构化文档，可用于 PR 描述 / 团队分享 / 项目归档 │
│ - 参见 references/refactoring-report.md │
└─────────────────────────────────────────────────────────┘
重构决策指南
何时重构
- 添加新功能前，先重构相关代码使其易于扩展
- 修复 Bug 时，顺便改善周边代码结构
- Code Review 中发现的问题
- 代码难以理解或修改时
何时不重构
- 即将废弃的代码
- 没有测试覆盖且无法快速补充测试的核心代码
- 时间紧迫的紧急修复（先修复，后重构）
- 代码虽不完美但足够清晰且稳定运行
重构粒度控制
| 规模 | 范围 | 建议 | 参考案例 |
|---|---|---|---|
| 小型 | 单个函数/方法 | 直接修改，单次提交 | MoE #5189 复用上游 all_reduce（-38 行） |
| 中型 | 单个类或模块 | 拆分为 2-3 次提交 | MoE #5481 dict/tuple → dataclass（6 文件） |
| 大型 | 跨模块/包 | 制定计划，分阶段执行 | Quantization 4 阶段重构（36 文件） |
重构文档模板
当用户请求生成重构文档（如 "输出重构文档"、"生成重构报告"、"写重构总结"）时，在重构完成并验证后，按 references/refactoring-report.md 中的模板生成文档。
文档支持按用途裁剪（PR 描述 / 团队分享 / 项目归档），小型重构可使用精简格式。详见参考文档。
输出格式
对每个重构建议，按以下格式输出：
### [问题类型] 问题简述
**位置：** `file_path:line_number`
**问题：** 描述当前代码的问题
**方案：** 描述修复方案
**实战参考：** 匹配的实战模式（如适用）
**修复前：**
（代码片段）
**修复后：**
（代码片段）
**依据：** 引用的参考文档和具体规则
References
详细参考文档：
- code-smells.md — 代码坏味道识别与修复（函数/类/逻辑/模块四个层级，含 isinstance 链分发）
- design-patterns.md — Pythonic 设计模式应用（创建型/结构型/行为型 + singledispatch + 反模式警示）
- readability.md — 可读性与可维护性改进（命名/结构/类型标注/注释/模块组织/Pythonic 惯用法）
- refactoring-in-practice.md — 基于 vllm-ascend 真实 PR 的重构实战经验（七大模式 + 安全守则 + 规模评估矩阵）
- refactoring-report.md — 重构文档生成（模板 + 各节填写指南 + 场景适配 + 小型重构精简格式）