【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 

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

1. README.md：项目的「说明书」，必须写！至少包含：项目简介、运行环境、安装依赖命令、启动方式、功能说明、作者信息。（别人接手/你自己半年后看，靠这个）
2. .gitignore：git提交时的「忽略规则」，避免提交无用文件，Python项目必忽略的内容：__pycache__/、.pyc、.pyd、venv/、.env、*.log、build/、dist/ 等。
3. src/：核心源码目录，所有业务代码、模块都放在这里，这是Python项目的核心规范——源码与配置/测试/文档分离，让项目结构清晰。
4. tests/：测试目录，遵循「测试与源码分离」，所有测试代码放这里，推荐用 pytest 框架编写测试用例。

requirements.txt：Python项目的「依赖清单」，记录项目所有用到的第三方包+版本号，格式示例：

requests==2.31.0 pandas==2.1.4 numpy==1.26.2 

安装命令：pip install -r requirements.txt，协作/部署必备，统一环境无冲突。

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

适用于：团队协作项目、开源项目、生产环境部署的项目、复杂业务项目（比如数据中台、机器学习工程、大型工具库），在基础版上扩展，完全遵循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/ # 打包后的发布包（自动生成） 

✅ 企业版新增核心说明

1. pyproject.toml：Python官方推荐的「项目配置总入口」，替代传统的setup.cfg，用来配置打包、代码格式化、测试框架的参数，是现代Python项目的标配。
2. src/your_package/：把源码包「命名规范化」，这是Python项目的重要规范——所有可导入的核心代码，都放在一个「专属包」下，避免模块名冲突，也方便打包发布。
3. venv/：Python虚拟环境目录，每个项目都应该独立创建虚拟环境，隔离不同项目的依赖包版本，避免全局环境污染，创建命令：python -m venv venv。
4. .env：存放敏感配置（比如数据库连接字符串、API密钥、TOKEN），绝对不要上传到git，通过 python-dotenv 包读取，安全合规。

requirements-dev.txt：分离「生产依赖」和「开发依赖」，生产环境只装运行必需的包，开发环境装测试、格式化、调试的包，示例：

# 开发依赖 pytest==7.4.3 black==23.11.0 # 代码格式化 flake8==6.1.0 # 代码语法检查 

三、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仓库。

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

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

1. 写单个脚本/练手小项目：不用复杂结构，一个 .py 文件即可，写完后慢慢重构为基础版。
2. 个人项目/中小型工具/数据分析项目：直接用「基础通用版」，足够用，无冗余。
3. 团队协作/生产部署/开源项目/复杂业务：直接用「企业级规范版」，一步到位，符合行业标准。
4. Web开发：Flask用「Flask标准版」，Django用「Django自带规范结构」，框架的约定就是最好的规范。

✅ 核心记忆点

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

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

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