4.4 模块与包架构:__init__.py 作用、绝对/相对导入避坑及循环导入解决方案
本节目录
欢迎回到 HelloWorld 技术社区(www.helloworld.net) 《Python 现代开发实战》第 4 章(同时也是整个第一阶段基础篇)的收官之战!
当你的项目从单个 main.py 膨胀到几十个文件时,合理的目录拆分与模块化设计就成了决定项目生死的关键。
一、 现代 Python 包结构与 __init__.py 的真正使命
一个标准的现代工程通常采用 src 布局(防止测试时意外导入未安装的本地根目录代码):
helloworld-service/
├── pyproject.toml
└── src/
└── hw_service/
├── __init__.py # 标识普通包,并定义对外暴露的公共 API 门面
├── config.py
├── models/
│ ├── __init__.py
│ └── user.py
└── services/
├── __init__.py
└── auth.py
虽然 Python 3.3+ 支持没有 __init__.py 的隐式命名空间包,但在业务项目中强烈建议保留显式的 __init__.py。它的两大核心作用是:
1. 充当包的公共门面(Facade):在 models/__init__.py 中写入 from .user import User 并声明 __all__ = ["User"],外部调用者就可以直接 from hw_service.models import User,无需关心内部文件拆分细节;
2. 明确标识测试与静态分析边界:pytest、mypy 和 Ruff 均依赖 __init__.py 准确推断包层级。
二、 绝对导入 vs 相对导入:团队选型铁律
- 绝对导入(Absolute Import):从顶层包名写起,例如
from hw_service.models.user import User。清晰、无歧义,跨文件复制粘贴永远不会报错,是现代 Python 项目的首选规范。 - 相对导入(Relative Import):使用点号表示相对位置,例如在
services/auth.py中写from ..models.user import User。仅推荐在同一子包内部紧耦合文件之间使用,切忌超过两层..,且带相对导入的文件不能直接通过python auth.py运行(必须使用python -m hw_service.services.auth以模块方式启动)。
三、 终极痛点:循环导入(Circular Import)的三板斧解法
新手拆完模块后,最常遇到的报错就是 ImportError: cannot import name 'X' from partially initialized module 'Y' (most likely due to a circular import)——即 A.py 顶层导入了 B.py,而 B.py 顶层又反过来导入了 A.py。
遇到循环导入,按优先级使用以下三招根治:
1. 架构解耦(治本):把 A 和 B 共同依赖的常量、数据模型或工具函数抽离到一个独立的第三模块 common.py 中;
2. 仅用于类型标注的导入放入 if TYPE_CHECKING: 块中(零运行时开销,最优雅):
from typing import TYPE_CHECKING
if TYPE_CHECKING:
# 仅在静态类型检查(mypy/IDE)时生效,运行时完全跳过,彻底打破循环依赖
from hw_service.services.auth import AuthService
- 局部延迟导入(治标):将
import语句下沉到真正用到它的函数内部执行。
🏆 第一阶段结业综合挑战
恭喜你完成了《Python 现代开发实战》第一阶段(第 1–4 章,共 16 节)的全部基础与工程规范学习!
第一阶段结业任务:在本地创建一个 src 布局的小型工程,包含 models.py(定义自定义业务异常)和 storage.py(使用 pathlib 读写 JSON 数据),通过 uv run python -m ... 运行验证,并将目录树截图带 #Python专栏打卡 发到评论区,解锁 「Python 现代工程筑基者」 阶段认证徽章!