【python】一般python项目的目录结构

Python 项目标准目录结构（全场景完整版）

你想了解Python项目的通用目录结构，核心结论先说：Python项目没有「唯一绝对」的标准，但有「行业通用、约定俗成」的最佳实践结构，会根据「项目规模/用途」区分，从小型脚本项目 → 中大型工程化项目 → Web框架项目，结构逐步规范，所有规范都遵循 Python 社区的通用约定，兼顾可读性、可维护性、协作效率。

一、基础通用版（✅ 90%的中小项目首选，新手必学，最常用）

适用于：个人项目、工具类项目、业务逻辑不复杂的中小型项目、内部自用项目，结构简洁够用，无冗余，规范且易上手，是Python项目的「最小完美结构」。

your_project/ # 项目根目录（项目名，自定义，比如data_analysis/）
├── README.md # 【必选】项目说明文档，所有人都要写！
├── requirements.txt # 【必选】项目依赖包清单（版本锁定）
├── .gitignore # 【必选】git忽略文件，避免提交无用文件
├── src/ # 【必选】核心源码目录（重点！所有业务代码都放这里）
│ ├── __init__.py # 标识src是Python包（空文件即可，Python3.3+可省，但建议保留）
│ ├── main.py # 程序入口文件（项目启动/执行的主文件）
│ ├── core/ # 核心业务逻辑模块（比如算法、核心功能实现）
│ │ └── __init__.py
│ ├── utils/ # 工具类模块（通用函数、常量、装饰器等）
│ │ └── __init__.py
│ └── config/ # 配置模块（配置文件、环境变量、参数配置）
│ └── __init__.py
└── tests/ # 【推荐】测试用例目录（单元测试、集成测试）
├── __init__.py
└── test_core.py

✅ 基础版核心文件/目录说明（必记）

二、企业级规范版（✅ 生产级/大型项目必用，工业标准）

适用于：团队协作项目、开源项目、生产环境部署的项目、复杂业务项目（比如数据中台、机器学习工程、大型工具库），在基础版上扩展，完全遵循Python社区最佳实践，结构完整，可维护性拉满，也是开源Python项目的「标配结构」。

your_project/
├── README.md # 必选：项目说明文档
├── requirements.txt # 必选：基础依赖清单
├── requirements-dev.txt # 推荐：开发环境依赖（比如pytest、black、flake8等）
├── .gitignore # 必选：git忽略规则
├── LICENSE # 开源项目必选：开源协议（MIT/Apache2.0等）
├── pyproject.toml # 【核心】项目构建配置文件（Python官方推荐，PEP 621标准）
├── setup.py/setup.cfg # 可选：打包配置文件（如果项目要发布为pip包）
├── docs/ # 推荐：项目完整文档（API文档、使用手册、设计文档，可放md/html）
├── examples/ # 推荐：示例代码目录（新手入门用的demo、功能示例）
├── data/ # 可选：数据目录（存放项目用的数据集、缓存文件，只读）
├── logs/ # 可选：日志目录（项目运行产生的日志文件）
├── .env # 可选：环境变量文件（存放敏感配置：密钥、数据库密码，不上传git）
├── venv/ # 可选：虚拟环境目录（隔离项目依赖，避免污染全局Python）
├── src/ # 必选：核心源码目录（和基础版一致，内部模块按需扩展）
│ ├── your_package/ # ✅ 重点：把源码包名改成你的项目名（比如data_processor/）
│ │ ├── __init__.py
│ │ ├── main.py
│ │ ├── core/
│ │ ├── utils/
│ │ ├── config/
│ │ └── api/ # 可选：如果是接口服务，新增API模块
│ └── __init__.py
├── tests/ # 必选：测试用例目录
│ ├── __init__.py
│ ├── test_core.py
│ └── conftest.py # pytest的全局配置文件
├── build/ # 打包后生成的目录（自动生成）
└── dist/ # 打包后的发布包（自动生成）

✅ 企业版新增核心说明

三、Python Web框架专属目录结构（✅ 高频刚需，Flask/Django）

Python做Web开发是主流场景，Django/Flask这两个核心Web框架，有「框架约定的专属目录结构」（框架的设计哲学是「约定大于配置」），这是最常用的Web项目结构，必须单独记！

✅ 1. Flask 项目目录结构（分轻量版/标准版）

Flask是轻量级Web框架，结构灵活，分两种场景：

✔️ Flask 轻量版（小型接口/个人博客，单应用）

flask_project/
├── README.md
├── requirements.txt
├── .gitignore
├── app.py # 程序入口（核心文件，路由+配置+业务逻辑）
├── static/ # 静态文件：css、js、图片、字体
├── templates/ # 模板文件：html页面（Jinja2模板）
└── utils/ # 工具模块：通用函数、装饰器、数据库操作

✔️ Flask 标准版（中大型Web项目，团队协作，推荐）

flask_project/
├── README.md
├── requirements.txt
├── .gitignore
├── .env
├── venv/
├── run.py # 项目启动入口（只做启动，无业务逻辑）
├── app/ # 核心应用包（所有业务代码）
│ ├── __init__.py # 初始化Flask实例、注册蓝图、加载配置
│ ├── models/ # 数据模型：数据库ORM映射（SQLAlchemy）
│ ├── routes/ # 路由模块：接口/页面路由（蓝图Blueprint）
│ ├── services/ # 业务逻辑层：核心业务处理（解耦路由和逻辑）
│ ├── utils/ # 工具模块
│ ├── config.py # 配置文件：开发/生产环境配置
│ ├── static/
│ └── templates/
└── tests/ # 测试用例：接口测试、业务逻辑测试

✅ 2. Django 项目目录结构（✅ 固定规范，Django强制推荐）

Django是重量级Web框架，自带脚手架自动生成标准结构，「约定大于配置」的典范，所有Django项目几乎都遵循这个结构，无需自己手动创建，创建命令：django-admin startproject django_project，自动生成核心结构，扩展后如下：

django_project/
├── README.md
├── requirements.txt
├── .gitignore
├── manage.py # Django核心命令工具（启动、迁移、创建app等）
├── django_project/ # 项目核心配置包（自动生成，和项目名一致）
│ ├── __init__.py
│ ├── settings.py # 全局配置：数据库、中间件、静态文件、应用注册
│ ├── urls.py # 主路由：所有app的路由入口
│ ├── asgi.py # 异步部署入口（生产环境）
│ └── wsgi.py # 同步部署入口（生产环境）
├── apps/ # 业务应用目录（核心！所有业务模块放这里）
│ ├── user/ # 用户模块（注册、登录、个人中心）
│ ├── article/ # 文章模块（发布、查看、评论）
│ └── order/ # 订单模块（下单、支付、物流）
├── static/ # 全局静态文件
├── templates/ # 全局模板文件
├── media/ # 用户上传文件（图片、视频、附件）
└── tests/ # 测试用例

注意：Django的每个业务模块（比如user）都是一个「独立app」，通过 python manage.py startapp user 创建，每个app内部有自己的 models.py、views.py、urls.py，完全解耦，这是Django的核心优势。

四、Python项目的「黄金核心规范」（✅ 重中之重，所有场景通用）

这些是Python项目的「底层约定」，比目录结构本身更重要，不管项目大小，遵循这些规范，你的项目永远是「整洁、规范、易维护」的，也是Python开发者的「行业共识」，面试中也会被问到！

✅ 规范1：源码与非源码分离

核心原则：src/ 目录存放「所有可执行的核心源码」，其他所有内容（测试、文档、数据、日志、配置）都放在 src/ 外部。
✅ 为什么？避免源码和配置/测试/日志混在一起，结构清晰，打包发布时只需要处理 src/，不会包含无关文件。

✅ 规范2：必须使用虚拟环境

核心原则：每个Python项目都要创建独立的虚拟环境，绝对不要用「全局Python环境」。
✅ 为什么？不同项目的依赖包版本可能冲突（比如A项目需要 pandas==2.0，B项目需要 pandas==1.5），虚拟环境可以隔离依赖，互不影响。
✅ 常用命令：

• 创建虚拟环境：python -m venv venv
• 激活虚拟环境（Windows）：venv\\Scripts\\activate
• 激活虚拟环境（Mac/Linux）：source venv/bin/activate

✅ 规范3：禁止在项目根目录写业务代码

错误示范：项目根目录直接写 main.py、core.py、utils.py，根目录一堆 .py 文件，杂乱无章。
正确做法：所有业务代码都放进 src/ 目录，根目录只放「配置/文档/启动脚本」等非业务文件。

✅ 规范4：依赖版本必须锁定

核心原则：requirements.txt 中必须写「具体的版本号」（比如 requests==2.31.0），绝对不要只写包名（比如 requests）。
✅ 为什么？不锁定版本的话，不同环境安装的包版本可能不同，导致「本地运行正常，部署后报错」的兼容问题，这是Python项目的高频坑！
✅ 生成依赖清单的命令：pip freeze > requirements.txt（在虚拟环境激活后执行，只记录当前项目的依赖）。

✅ 规范5：__pycache__ 绝对不要提交

__pycache__/ 是Python的「字节码缓存目录」，自动生成，无用且跨平台不兼容，必须在 .gitignore 中忽略，永远不要提交到git仓库。

五、总结（✅ 按场景选择，一目了然）

✅ 怎么选择适合自己的目录结构？

✅ 核心记忆点

Python项目的目录结构，本质是「分层解耦」的思想：把「源码、测试、文档、配置、数据」分开存放，让每个部分各司其职，最终的目标是：

项目结构清晰 → 自己能看懂，别人也能看懂 → 易维护、易扩展、易协作。

希望这份完整的目录结构指南，能帮你规范所有Python项目！🚀