Python 架构优化器
本技能帮助优化 Python 项目的整体架构,使其更符合现代 Python 工程最佳实践。
核心能力
1. 目录结构优化
- 按功能/模块划分项目
- 分离配置、业务逻辑、测试
- 符合 PEP 8 和 Python 社区惯例
2. 依赖管理
requirements.txt/pyproject.toml/poetry配置- 依赖分类(生产/开发/可选)
- 版本锁定策略
3. 代码组织
- 包/模块设计
- 导入结构优化
- 关注点分离
4. 测试架构
- pytest 配置
- 测试目录结构
- 覆盖率配置
5. 工程化配置
- pre-commit 钩子
- linting 配置(ruff/black/mypy)
- CI/CD 模板
工作流程
步骤 1: 分析现有架构
# 使用分析脚本
python scripts/analyze_project.py <project-path>
读取项目结构,识别问题:
- 循环依赖
- 过深的嵌套
- 缺失的
__init__.py - 测试覆盖率低
- 配置硬编码
步骤 2: 生成优化建议
参考 references/best-practices.md 生成具体建议。
步骤 3: 执行重构(需用户确认)
⚠️ 安全警告: 重构操作会移动/创建文件,可能影响现有项目。
必须获得用户明确确认后才能执行迁移脚本:
# 用户确认后执行(支持:yes / y / 确认 / 是)
python scripts/migrate_project.py <project-path>
回滚策略:
- 迁移前自动备份到
<project-path>.backup.<timestamp>/ - 提供
--dry-run预览变更 - 失败时自动恢复备份
步骤 4: 验证
运行测试和 lint 检查确保重构后功能正常。
参考文档
- 最佳实践:
references/best-practices.md- Python 项目架构详细指南
脚本工具
scripts/analyze_project.py- 项目结构分析scripts/generate_structure.py- 生成推荐结构scripts/migrate_project.py- 执行迁移(支持 --dry-run 预览、自动备份、回滚)
迁移脚本安全机制
# 1. 预览模式(不会修改任何文件)
python scripts/migrate_project.py ./my-project --dry-run
# 2. 保存计划供审查
python scripts/migrate_project.py ./my-project --plan migration-plan.json
# 3. 用户确认后执行(自动备份)
python scripts/migrate_project.py ./my-project
# 4. 失败时自动回滚到备份
触发条件
当用户提到:
- "优化 Python 项目结构"
- "重构 Python 代码架构"
- "Python 项目目录怎么组织"
- "改进 Python 工程化"
- "Python 最佳实践"