4、模块化拆分：Python包管理、模块化设计原则，从混乱到有序
说实话，我见过太多Python项目从一个小脚本，慢慢膨胀成一团乱麻。我自己早期也踩过这个坑——一个文件写了三千行，函数之间互相调用，改一个地方崩三个功能。后来我才明白，模块化不是「把代码拆开」那么简单，它背后是一套设计哲学。
今天我们就聊聊，怎么从混乱走向有序。
4.1 为什么你的项目会变乱？
先想想看，一个典型的「混乱项目」长什么样？
- 所有代码堆在
main.py或app.py里 - 工具函数散落在各个文件，重复定义
- 导入路径乱七八糟，循环依赖频繁出现
- 测试代码和生产代码混在一起
我接手过一个遗留项目，光 utils.py 就有两千行，里面既有数据库连接、又有日期格式化、还有图片处理。你想想看，这种代码谁敢动？
4.2 Python包管理：从文件到包
Python的模块化，核心就两个概念：模块（Module） 和 包（Package）。
- 模块：一个
.py文件就是一个模块 - 包：一个包含
__init__.py的目录就是一个包
我个人的习惯是，一个模块不超过300行。超过这个数，就该考虑拆分了。
4.2.1 标准包结构
my_project/
├── my_package/
│ ├── __init__.py
│ ├── models/
│ │ ├── __init__.py
│ │ ├── user.py
│ │ └── order.py
│ ├── services/
│ │ ├── __init__.py
│ │ ├── auth_service.py
│ │ └── payment_service.py
│ └── utils/
│ ├── __init__.py
│ ├── validators.py
│ └── helpers.py
├── tests/
├── config.py
├── requirements.txt
└── setup.py嗯，这里要注意：__init__.py 可以留空，也可以用来做包的初始化逻辑。但我建议尽量保持简单，别在里面写太多东西。
4.2.2 相对导入 vs 绝对导入
这个问题，我当年纠结了很久。直接说结论：
| 导入方式 | 示例 | 推荐场景 |
|---|---|---|
| 绝对导入 | from my_package.models.user import User |
大多数情况，清晰明了 |
| 相对导入 | from ..models.user import User |
包内部模块间引用，避免硬编码 |
4.3 模块化设计三大原则
光会拆文件还不够，你得知道「怎么拆才合理」。我总结了三句话：
4.3.1 单一职责原则（SRP）
一个模块只做一件事。比如 user.py 只处理用户相关的数据模型，别把用户登录逻辑也塞进去。
我在项目中遇到过这样的情况：一个 order.py 里既有订单模型、又有支付逻辑、还有物流查询。后来改需求时，改一个地方要测三个功能，太痛苦了。
4.3.2 接口隔离原则
模块对外暴露的接口要精简。说白了，就是「别把内部实现细节暴露出去」。
# ❌ 不好的做法
from my_package.utils.helpers import _internal_parse_date
# ✅ 好的做法
from my_package.utils import parse_date # 通过 __init__.py 暴露4.3.3 依赖倒置原则
高层模块不应该依赖低层模块，两者都应该依赖抽象。在Python里，这通常意味着用接口或抽象基类。
4.4 实战：从混乱到有序的拆分步骤
假设你有一个 app.py，里面混着数据库操作、业务逻辑、路由定义。怎么拆？
- 识别职责：把代码按功能分类（数据层、业务层、表现层）
- 提取工具函数：把通用的日期处理、字符串处理放到
utils/ - 分离数据模型：把数据库相关的代码放到
models/ - 封装业务逻辑：把核心业务放到
services/ - 整理路由：把API路由单独放到
routes/
我一般会先画一个依赖关系图，看看哪些模块之间耦合太紧。然后从最底层的工具函数开始拆，一层层往上。
4.5 包管理工具的选择
说到包管理，Python生态里工具不少。我个人的经验是：
| 工具 | 适用场景 | 我的评价 |
|---|---|---|
| pip + requirements.txt | 小项目、快速原型 | 简单直接，但依赖锁定不够严格 |
| Poetry | 中型项目、团队协作 | 依赖解析强，支持版本锁定，我最近一直在用 |
| PDM | 追求性能、PEP 582 | 新锐工具，适合有探索精神的团队 |
我个人推荐 Poetry。它把依赖管理和打包发布整合在一起，用起来很顺手。而且它的 pyproject.toml 比 setup.py 清晰多了。
4.6 避坑指南
最后，分享几个我踩过的坑：
- 别过度拆分：一个模块只有几十行代码，反而增加了导航成本。我一般以「一个模块能独立完成一个功能」为标准。
- 注意导入性能：在
__init__.py里大量导入会导致启动变慢。可以用懒加载。 - 测试先行：拆分前先写测试，确保重构后功能不变。没有测试的拆分，就是盲人摸象。
python -m my_package 来运行包，而不是直接 python app.py。这样能保证导入路径正确，也符合包的标准用法。
模块化拆分，说白了就是「把大问题拆成小问题，再把小问题组织好」。它不只是一个技术动作，更是一种思维方式。当你习惯了模块化思考，你会发现代码的可维护性、可测试性都会大幅提升。
下一章，我们会聊聊更进阶的话题——如何用依赖注入来解耦模块。到时候见。