Python项目文件结构实例详解

顾星河

发布时间：2026-10-10| 5人浏览过

原创

详解Python项目文件结构的设计原则与实践，包括模块划分规则、包结构类型及__init__.py的核心用法。

模块划分与设计原则

合理的模块划分是Python项目可维护的基础。遵循单一职责原则，确保每个子包仅负责一个核心功能，如将用户认证逻辑集中在auth/模块中。同时实现高内聚低耦合：内部代码紧密关联，模块间通过接口通信而非直接依赖具体实现。结构设计需支持扩展性，例如预留插件目录或使用抽象基类定义服务接口。

常用包结构设计方式

项目可采用不同组织结构以适应场景：

分层式结构：典型目录为core/（业务逻辑）、models/（数据模型）、services/（外部调用）、utils/（工具函数），适用于Web应用和企业系统。
功能式结构：按业务功能划分子目录，如auth/、payment/、reporting/，适合微服务或复杂业务。
混合式结构：结合分层与功能，如features/auth/下含controllers/和models/子目录，共享工具放shared/utils/。
插件化结构：核心框架在core/，可插拔模块存于plugins/plugin_a/等，通过动态导入和接口注册实现。

推荐目录结构与配置

以下是一个标准化的Python项目目录树，便于日常开发与协作：

my_project/
├── src/my_project/
│   ├── __init__.py
│   ├── core/algorithms.py
│   └── utils/logger.py
├── tests/test_core/test_algorithms.py
├── docs/api.md
├── scripts/run_pipeline.py
├── requirements.txt
├── pyproject.toml
└── README.md

其中src/隔离源码，tests/镜像测试结构，docs/存放文档，scripts/放置运行脚本。配置文件pyproject.toml用于元数据管理。

init.py的多层级作用

在不同目录下，__init__.py承担特定职责：

总包层级（src/my_project/__init__.py）：声明包标识、定义公共接口、控制导出。例如：
```
from .core.algorithms import main_algorithm
__version__ = "1.0.0"
```
可通过import my_project直接访问暴露的接口。
子包层级（如core/__init__.py）：聚合子模块功能、隐藏实现细节。示例：
```
from .data_loader import DataLoader
__all__ = ["DataLoader"]
```
简化外部调用。
测试目录（tests/__init__.py）：标识测试包、共享测试夹具（Fixture）。如使用pytest，可在此定义@pytest.fixture供多测试复用。