返回专栏
专栏 ·

4.4 模块与包架构:__init__.py 作用、绝对/相对导入避坑及循环导入解决方案

作者: 九路 共 12 章 · 48 小节

欢迎回到 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
  1. 局部延迟导入(治标):将 import 语句下沉到真正用到它的函数内部执行。

🏆 第一阶段结业综合挑战

恭喜你完成了《Python 现代开发实战》第一阶段(第 1–4 章,共 16 节)的全部基础与工程规范学习! 第一阶段结业任务:在本地创建一个 src 布局的小型工程,包含 models.py(定义自定义业务异常)和 storage.py(使用 pathlib 读写 JSON 数据),通过 uv run python -m ... 运行验证,并将目录树截图带 #Python专栏打卡 发到评论区,解锁 「Python 现代工程筑基者」 阶段认证徽章!