一个 标准的 Python 项目结构通常遵循社区最佳实践（例如 Python Packaging Authority 推荐的结构），目的是让项目 易维护、可测试、可发布、可扩展。下面从 基础结构 → 各目录作用 → 实际示例 → 企业级结构进行系统解析。
一、最常见的标准 Python 项目结构
典型结构如下：
my_project/
│
├── README.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── .gitignore
│
├── src/
│ └── my_project/
│ ├── __init__.py
│ ├── main.py
│ ├── config.py
│ ├── utils.py
│ └── module/
│ ├── __init__.py
│ └── submodule.py
│
├── tests/
│ ├── __init__.py
│ └── test_main.py
│
├── scripts/
│ └── run_dev.py
│
└── docs/
└── index.md
这种结构称为：
src layout
是现代 Python 项目的推荐结构。
二、顶层目录说明
1 README.md
项目说明文档
通常包含：
- 项目介绍
- 安装方法
- 使用示例
- API说明
示例：
# My Project
A powerful Python tool for data processing.
2 LICENSE
开源协议，例如：
- MIT License
- Apache License 2.0
- GNU General Public License
3 pyproject.toml
现代 Python 构建配置文件
由 PEP 518 和 PEP 621 定义。
示例：
[project]
name = "my_project"
version = "0.1.0"
description = "Example project"
authors = [{name="Your Name"}]
dependencies = [
"requests",
"numpy"
]
它取代了旧的：
setup.py
setup.cfg
4 requirements.txt
项目依赖：
requests==2.31.0
numpy>=1.24
pandas
安装：
pip install -r requirements.txt
使用工具：
- pip
- pip-tools
- Poetry
5 .gitignore
忽略不需要提交到 Git 的文件：
__pycache__/
*.pyc
.env
.venv
dist/
build/
与 Git 配合使用。
三、src目录（核心代码）
推荐使用：
src/
结构：
src/my_project/
原因：
避免 import 混乱问题。
如果没有 src：
my_project/
main.py
可能导致：
import module
引用错误。
src结构：
src/my_project/module.py
导入更清晰：
from my_project.module import func
四、包结构设计
src/my_project/
示例：
my_project/
│
├── __init__.py
├── main.py
├── config.py
├── utils.py
└── services/
├── __init__.py
└── user_service.py
init.py
作用：
- 标记为 Python package
- 控制导出 API
例如：
from .utils import helper
五、tests 目录
tests/
示例：
tests/
├── test_main.py
└── test_utils.py
测试框架：
- pytest
- unittest
示例：
def test_add():
assert add(1,2) == 3
运行：
pytest
六、scripts 目录
存放 开发脚本：
scripts/
例如：
scripts/
run_dev.py
init_db.py
示例：
from my_project.main import run
run()
七、docs 文档
docs/
常配合：
- Sphinx
- MkDocs
结构：
docs/
index.md
api.md
usage.md
八、企业级 Python 项目结构
大型项目常见结构：
my_project/
│
├── pyproject.toml
├── README.md
├── Makefile
├── Dockerfile
├── .env
│
├── src/
│ └── my_project/
│ ├── api/
│ ├── core/
│ ├── models/
│ ├── services/
│ ├── repositories/
│ ├── utils/
│ └── main.py
│
├── tests/
│
├── migrations/
│
├── scripts/
│
└── docs/
常见分层：
| 层 | 作用 |
|---|---|
| api | 接口层 |
| services | 业务逻辑 |
| repositories | 数据访问 |
| models | 数据模型 |
| core | 配置/核心组件 |
九、Web项目示例
例如使用 FastAPI：
app/
│
├── main.py
├── api/
│ ├── routes.py
│
├── models/
│
├── schemas/
│
├── services/
│
└── core/
└── config.py
十、CLI工具结构
例如 CLI 工具：
cli_tool/
│
├── pyproject.toml
├── README.md
│
├── src/
│ └── cli_tool/
│ ├── __init__.py
│ ├── cli.py
│ └── commands/
│
└── tests/
使用：
- Typer
- Click
十一、最佳实践总结
推荐规则：
1 使用 src layout
src/package_name
2 单元测试独立
tests/
3 配置集中
pyproject.toml
4 分层结构
api
services
repositories
models
十二、一个完整示例
awesome_project/
│
├── pyproject.toml
├── README.md
├── LICENSE
├── requirements.txt
│
├── src/
│ └── awesome/
│ ├── __init__.py
│ ├── main.py
│ ├── utils.py
│ └── services/
│ └── service.py
│
├── tests/
│ └── test_service.py
│
└── scripts/
└── run.py
✅ 一句话总结
标准 Python 项目结构 =
src代码 + tests测试 + pyproject构建 + docs文档 + scripts工具
如果你愿意，我可以继续给你讲一个 很多高级 Python 工程师才知道的结构：
“大型 Python 项目的六层架构（Google / Uber 常用）”
包括：
Domain
Application
Infrastructure
Interface
Shared
Config
很多开源框架都在用这一套。
