Python 文件过大、难以维护或 AI 编辑器读不全时…

当 Python 单文件超过 500 行、混杂多个关注点、测试难组织或被 AI 工具截断上下文时，用来判断是否该拆、拆到哪里、以及如何安全重构。

适用场景

解决思路

1. 按行数控制文件规模：150-500 行为最佳区间（AI 代码编辑器与人类理解都合适）。
2. 500-1000 行视为偏大，开始寻找自然拆分点。
3. 1000-2000 行视为过大，重构为职责聚焦的模块。
4. 2000 行以上视为危险，必须拆分——否则会导致工具链问题和认知过载。
5. 满足以下任一条件就拆分：文件超过 500 行；同一文件包含多个不相关的关注点；找函数时需要反复滚动；该文件的测试难以组织；AI 工具截断或漏掉上下文。
6. 按领域概念拆分：`auth.py` → `auth/login.py`、`auth/tokens.py`、`auth/permissions.py`。
7. 按抽象层次拆分：把接口与实现分离。
8. 按数据类型拆分：把针对相关数据结构的操作归到一起。
9. 按 I/O 边界拆分：隔离数据库、API、文件操作。
10. 采用包结构：`__init__.py` 保持最小（只做导出）、`core.py` 放主逻辑（500 行以内）、`models.py` 放数据结构、`handlers.py` 放 I/O 与副作用、`utils.py` 放纯辅助函数。
11. 使用有意义的模块名（`data_storage.py` 而不是 `utils2.py`）。
12. `__init__.py` 保持最小或留空。
13. 把相关函数分组放在一起。
14. 将纯函数与副作用隔离。
15. 模块名使用 snake_case。
16. 不要仅按行数任意拆分文件。
17. 不要创建只有一个函数的模块。
18. 不要过度模块化，形成“包地狱”。
19. 模块名中不要使用点号或特殊字符。
20. 不要用“魔法”导入隐藏依赖。
21. 重构已有大文件时先识别函数簇：找出成组的相关函数。
22. 增量抽取：一次只移动一个函数簇。
23. 更新导入：修正所有 import 语句。
24. 每次移动后运行测试，验证没有破坏任何东西。
25. 更新文档：同步修改所有指向旧位置的引用。

适用边界 · 注意事项

• 领域特定的数学/科学计算模块（scipy、mpmath、numpy 风格）即使超过 2000 行也可能本来就可接受，不必强行拆分。
• 文件尚未超过 500 行、也没有多关注点混杂时，不需要为了“模块化”而拆分。
• 不要只为了行数硬拆，或把一个函数拆成一个模块——那只会得到“包地狱”。