Python大型项目的目录结构设计需要兼顾代码复用、模块解耦、部署便捷等多个维度，避免随着项目迭代出现文件杂乱、依赖混乱的问题。合理的目录划分能让新成员快速理解项目架构，也能降低后续功能扩展的复杂度。
通用基础目录结构
大部分Python大型项目可以基于以下基础结构进行扩展，核心模块划分清晰，适配多数业务场景：
my_project/ ├── config/ # 配置文件目录 │ ├── __init__.py │ ├── dev.yaml # 开发环境配置 │ └── prod.yaml # 生产环境配置 ├── src/ # 核心业务代码目录 │ ├── __init__.py │ ├── common/ # 公共工具模块 │ │ ├── __init__.py │ │ └── utils.py │ ├── modules/ # 业务功能模块 │ │ ├── __init__.py │ │ ├── user/ │ │ └── order/ │ └── main.py # 项目入口文件 ├── tests/ # 测试代码目录 │ ├── __init__.py │ ├── unit/ # 单元测试 │ └── integration/ # 集成测试 ├── docs/ # 项目文档目录 │ └── README.md ├── scripts/ # 部署、运维脚本目录 │ └── deploy.sh ├── requirements.txt # 项目依赖清单 └── setup.py # 项目打包配置
核心目录说明
- src目录：所有业务代码统一放在该目录下，避免根目录文件过多，同时通过
__init__.py将src标记为Python包，方便内部模块互相引用。 - config目录：将不同环境的配置分离存放，避免硬编码配置到代码中，后续切换环境只需要修改配置引用即可。
- tests目录：测试代码与业务代码分离，按照测试类型划分子目录，方便后续接入自动化测试流程。
不同场景的目录调整
Web项目场景
如果是基于Flask、Django等框架的Web项目，可以在src目录下增加Web相关的专属目录：
src/ ├── web/ # Web层相关代码 │ ├── __init__.py │ ├── routes/ # 路由定义 │ ├── middleware/ # 中间件 │ └── templates/ # 模板文件（如果使用服务端渲染） ├── service/ # 业务逻辑层 └── dao/ # 数据访问层
数据处理项目场景
如果是数据清洗、分析类的大型项目，可以将数据处理流程相关的模块单独拆分：
src/ ├── etl/ # 数据抽取转换加载模块 │ ├── extract.py │ ├── transform.py │ └── load.py ├── models/ # 数据分析模型 └── report/ # 报表生成模块
目录设计注意事项
- 避免过深的目录层级，一般目录深度不超过4层，否则会增加模块引用的复杂度。
- 同类型功能的模块尽量放在同一个目录下，比如所有工具类都放在common目录，不要分散在不同位置。
- 不要将临时文件、日志文件放在项目目录中，建议通过配置指定到项目外的固定路径，避免提交代码时混入无关文件。
模块引用示例
在src/main.py中引用common目录下的工具函数，代码示例如下：
# 导入src/common/utils.py中的时间格式化函数
from src.common.utils import format_time
def run():
current_time = format_time()
print(f"项目启动时间：{current_time}")
if __name__ == "__main__":
run()
如果觉得每次引用都写src前缀比较繁琐，可以在项目根目录的setup.py中配置包安装路径，将src目录安装到Python环境路径中，后续可以直接通过from common.utils import format_time的方式引用。
# setup.py配置示例
from setuptools import setup, find_packages
setup(
name="my_project",
version="1.0.0",
packages=find_packages(where="src"),
package_dir={"": "src"},
)
目录结构不是一成不变的，在项目迭代过程中可以根据业务变化适当调整，只要保证整体逻辑清晰、模块职责明确即可。