当 Python 包的 __init__.py 未显式导入子模块时，这些模块虽物理存在，却不会自动出现在包的命名空间中，导致 from package import submodule 失败或 dir(package) 不显示对应名称。本文直击该常见陷阱，详解如何通过 __init__.py 控制模块可见性。
当 python 包的 __init__.py 未显式导入子模块时，这些模块虽物理存在，却不会自动出现在包的命名空间中，导致 from package import submodule 失败或 dir(package) 不显示对应名称。本文直击该常见陷阱，详解如何通过 __init__.py 控制模块可见性。
你遇到的问题——from database import model 后 dir(model) 缺失 role，但 session 和 user 却可见——并非路径错误、循环导入或语法问题，而是 Python 包导入机制的核心规则：子模块不会自动“注册”到父包的命名空间中，必须由 __init__.py 显式声明。
? 问题本质：__init__.py 是包的“门面”，而非“自动扫描器”
在你的目录结构中：
database/ ├── __init__.py # ← 这是 database 包的入口 ├── model/ │ ├── __init__.py # ← 这是 database.model 子包的入口（关键！） │ ├── role.py │ ├── session.py │ ├── user.py │ └── model_abstract.py
database.model 是一个独立的子包，其行为完全由 database/model/__init__.py 控制。Python 绝不会 自动将 model/ 下所有 .py 文件导入到 model 命名空间中。只有当你在 database/model/__init__.py 中执行了 from . import role（或等效语句），role 才会成为 model 模块的属性。
你观察到 session 和 user 已出现在 dir(model) 中，说明它们已被 database/model/__init__.py 显式导入（例如包含 from . import session, user）；而 role.py 尚未被导入，因此不可见。
立即学习“Python免费学习笔记（深入）”；
✅ 正确解决方案：在 model/__init__.py 中显式导出
打开 database/model/__init__.py，添加以下任一形式的导入语句：
# 方式1：显式导入单个模块（推荐 —— 清晰、可控、避免污染） from . import role # 方式2：批量导入多个模块 from . import role, session, user, model_abstract # 方式3：按需导入类/函数（更精细，适合对外暴露API） from .role import Role from .session import UserSession
✅ 关键点：使用
from . import xxx（相对导入），其中.表示当前包database.model。这确保导入路径稳定，不依赖运行方式。
保存后，再次执行：
from database import model print(dir(model)) # 现在将看到 'role' 在列表中 x = model.role.Role.get_by_id(1) # ✅ 成功
⚠️ 注意事项与最佳实践
不要依赖
__all__来“修复”未导入的模块__all__ = ['role']仅控制from model import *的行为，无法让role出现在dir(model)或model.role中。必须先import，再__all__。避免在
__init__.py中执行耗时逻辑__init__.py会在每次导入包时执行。若role.py初始化开销大，可考虑延迟导入（如在函数内import database.model.role）。警惕循环导入风险
若role.py又反过来from database.model import user，且user.py也导入role，就会形成循环。此时应重构：提取公共基类到model_abstract.py，或使用字符串标注（def get_by_id(cls, id: int) -> 'Role': ...）。-
验证导入是否生效的快捷方法
在database/model/__init__.py末尾临时添加：print(f"[DEBUG] model.__init__ loaded: {__name__}")运行脚本时若看到该打印，说明
__init__.py已被加载，问题必在导入语句缺失。
? 总结：三步定位与修复
| 步骤 | 操作 | 验证方式 |
|---|---|---|
| ① 定位责任文件 | 检查 database/model/__init__.py 是否存在且为空/不完整 |
ls -l database/model/__init__.py |
| ② 补充导入语句 | 添加 from . import role
|
python -c "from database.model import role; print('OK')" |
| ③ 重载模块（开发时） | 修改 __init__.py 后，重启 Python 解释器或使用 importlib.reload()
|
dir(model) 输出含 'role'
|
Python 的包设计哲学是 显式优于隐式。__init__.py 不是摆设，而是你定义包 API 的契约文件。善用它，才能构建健壮、可维护、符合 Pythonic 风格的模块结构。
