Python项目结构设计与导入最佳实践

1. Python项目结构设计核心原则

一个合理的Python项目结构应该像精心规划的图书馆——每本书都有固定位置，检索路径清晰明确。我在处理过上百个Python项目后发现，混乱的导入问题80%源于不规范的目录结构。以下是经过实战验证的标准结构模板：

code复制my_project/
├── docs/                   # 项目文档
├── tests/                  # 测试代码
│   ├── __init__.py
│   └── test_module.py
├── my_package/             # 主包目录
│   ├── __init__.py         # 包标识文件
│   ├── core/               # 核心功能子包
│   │   ├── __init__.py
│   │   └── utils.py
│   ├── cli.py              # 命令行入口
│   └── config.py           # 配置文件
├── setup.py                # 安装配置
├── requirements.txt        # 依赖列表
└── README.md

关键经验：所有可导入目录必须包含__init__.py文件（即使是空文件），这是Python识别包目录的关键标志。在Python 3.3+中虽然可以省略，但显式声明能避免很多意外问题。

2. 包内导入的三种正确姿势

2.1 同级模块导入

假设在my_package/core/utils.py中需要导入同级的config.py：

python复制# 正确方式（相对导入）
from . import config

# 也可以使用绝对导入
from my_package import config

踩坑提醒：在脚本直接运行时（__name__ == "__main__"），相对导入会报错。这是Python的模块系统特性决定的——此时脚本不被视为包的一部分。

2.2 子模块向上导入

当子包中的模块需要访问上级内容时（如core/utils.py导入顶层的cli.py）：