Python 项目完整结构示例

以下是一个典型的 Python 项目完整结构示例，适用于中等规模的应用程序或库。该结构遵循最佳实践，具有良好的模块化、可维护性和扩展性。

---

项目结构示例

my_project/
├── src/                        # 源代码目录
│   ├── __init__.py             # 标记为 Python 包
│   ├── main.py                 # 主程序入口（可选）
│   ├── core/                   # 核心功能模块
│   │   ├── __init__.py
│   │   ├── app.py
│   │   └── utils.py
│   ├── models/                 # 数据模型（如 ORM 或数据结构）
│   │   ├── __init__.py
│   │   └── user.py
│   └── services/               # 业务逻辑层
│       ├── __init__.py
│       └── auth.py
├── tests/                      # 测试代码
│   ├── __init__.py
│   ├── test_main.py            # 主程序测试
│   ├── test_core.py            # 核心模块测试
│   └── test_services.py        # 服务层测试
├── docs/                       # 文档
│   ├── README.md               # 项目说明
│   ├── CONTRIBUTING.md         # 贡献指南
│   └── api_spec.md             # API 文档（可选）
├── config/                     # 配置文件
│   ├── settings.py             # 全局配置
│   └── local.py                # 本地覆盖配置
├── dist/                       # 打包输出目录（自动生成）
├── venv/                       # 虚拟环境（自动生成）
├── .env                        # 环境变量文件
├── .gitignore                  # Git 忽略文件
├── requirements.txt            # 依赖包列表
├── setup.py                    # 打包配置（可选）
├── Dockerfile                 # Docker 镜像构建文件（可选）
└── Makefile                    # 自动化任务（可选）

---

关键部分说明

1. src/ 目录

• 作用：存放项目的核心源代码，避免与项目根目录的脚本混淆。
• 子模块：
  • core/：核心功能（如主应用逻辑）。
  • models/：数据模型（如数据库模型、数据处理类）。
  • services/：业务逻辑层（如 API 服务、后台任务）。
• __init__.py：将目录标记为 Python 包，支持模块导入。

2. tests/ 目录

• 作用：单元测试和集成测试代码。
• 命名规范：test_<模块名>.py 对应 src/ 中的模块。
• 工具：推荐使用 pytest，支持分层测试（如 test_core.py 测试核心模块）。

3. config/ 目录

• 作用：集中管理配置文件。
• 示例：
  • settings.py：默认配置（如数据库连接、日志路径）。
  • local.py：本地开发环境的配置覆盖（如调试模式）。

4. .env 文件

• 作用：存储环境变量（如密钥、API 密钥）。
• 示例：

  DB_HOST=localhost
  DB_USER=root
  SECRET_KEY=your_secret_key
  

5. requirements.txt

• 作用：记录项目依赖的第三方库。
• 示例：

  flask>=2.0.0
  requests>=2.25.0
  

6. setup.py（可选）

• 作用：用于打包和发布到 PyPI。
• 示例：

  from setuptools import setup, find_packages
  
  setup(
      name='my_project',
      version='0.1.0',
      packages=find_packages('src'),  # 从 src 目录加载包
      include_package_data=True,      # 包含非代码文件（如模板）
      install_requires=[line.strip() for line in open('requirements.txt')],
  )
  

7. Dockerfile（可选）

• 作用：定义 Docker 镜像构建流程。
• 示例：

  FROM python:3.9-slim
  
  WORKDIR /app
  COPY . .
  
  RUN pip install --no-cache-dir -r requirements.txt
  CMD ["python", "src/main.py"]
  

8. Makefile（可选）

• 作用：简化常用命令（如测试、格式化、打包）。
• 示例：

  .PHONY: test lint package
  
  test:
      pytest tests/
  
  lint:
      black src/ tests/
      mypy src/ tests/
  
  package:
      python setup.py sdist bdist_wheel
  

---

适用场景扩展

1. Web 应用：
   • 添加 templates/（HTML 模板）和 static/（CSS/JS）目录。
   • 使用 manage.py 代替 main.py（如 Django/Flask 项目）。
2. 数据科学项目：
   • 添加 data/ 目录存放数据集。
   • 使用 jupyter_notebooks/ 保存分析代码。
3. 微服务：
   • 每个服务单独一个 src/ 目录，使用 Docker Compose 管理多容器。

---

优点

1. 模块化：代码按功能分层，易于维护。
2. 可测试：测试代码与源代码分离，支持自动化测试。
3. 环境隔离：通过 .env 和 requirements.txt 管理依赖。
4. 扩展性：支持 Docker、CI/CD 和多环境部署。

根据项目规模，可以简化或扩展此结构。小型脚本项目可直接使用单文件，中大型项目推荐此结构。