Python 大型应用目录结构规划（企业级最佳实践）

核心原则

• 模块化：按业务功能拆分，高内聚低耦合
• 可扩展性：支持插件机制和动态加载
• 环境隔离：清晰区分开发/测试/生产环境
• 自动化：内置标准化的构建测试部署流程
• 可维护性：结构自说明，新成员能快速理解

完整目录结构

project-root/                  # 项目根目录（Git仓库根目录）
├── .github/                   # CI/CD工作流配置
│   └── workflows/
│       ├── ci.yml             # 持续集成流程
│       └── cd.yml             # 持续部署流程
│
├── .vscode/                   # IDE配置（可选）
│   ├── settings.json
│   └── extensions.json
│
├── config/                    # 配置中心
│   ├── base/                  # 基础配置
│   │   ├── logging.yaml       # 日志配置
│   │   ├── database.py        # 数据库连接池
│   │   └── constants.py       # 全局常量
│   │
│   ├── dev/                   # 开发环境
│   │   ├── __init__.py
│   │   └── settings.toml
│   │
│   ├── test/                  # 测试环境
│   └── prod/                  # 生产环境（敏感配置通过Vault注入）
│
├── src/                       # 主代码库
│   └── your_project/         # 项目主包
│       ├── __init__.py        # 包初始化
│       ├── application/       # 业务逻辑层
│       │   ├── services/      # 业务服务
│       │   │   ├── user_service.py
│       │   │   └── payment_service.py
│       │   │
│       │   ├── models/        # 业务模型（DTO/BO）
│       │   │   ├── user.py
│       │   │   └── order.py
│       │   │
│       │   └── use_cases/     # 业务用例
│       │       ├── checkout_use_case.py
│       │       └── report_generation.py
│       │
│       ├── domain/            # 领域层（DDD）
│       │   ├── entities/      # 聚合根/实体
│       │   ├── value_objects/ # 值对象
│       │   ├── events/        # 领域事件
│       │   └── repositories/  # 仓储接口
│       │
│       ├── infrastructure/    # 基础设施层
│       │   ├── database/      # 数据访问
│       │   │   ├── migrations/  # 数据库迁移脚本
│       │   │   ├── models.py     # ORM映射
│       │   │   └── repositories_impl/  # 仓储实现
│       │   │
│       │   ├── cache/         # 缓存实现（Redis/Memcached）
│       │   ├── message_broker/ # 消息队列实现
│       │   └── third_party/   # 第三方服务集成
│       │
│       ├── interfaces/        # 接口层
│       │   ├── web/           # Web接口
│       │   │   ├── api/         # REST API
│       │   │   │   ├── v1/         # 版本控制
│       │   │   │   │   ├── routers/
│       │   │   │   │   ├── schemas/  # Pydantic模型
│       │   │   │   │   └── dependencies.py
│       │   │   │   ├── v2/
│       │   │   │   └── middleware/  # 中间件
│       │   │   │
│       │   │   ├── templates/    # HTML模板（如需要）
│       │   │   └── static/       # 静态资源
│       │   │
│       │   ├── rpc/            # gRPC接口
│       │   ├── cli/            # 命令行接口
│       │   └── event_handlers/  # 事件处理器
│       │
│       ├── utils/             # 公共工具
│       │   ├── security/      # 安全相关
│       │   ├── logging/       # 日志扩展
│       │   ├── error_handling/ # 异常处理
│       │   └── helpers.py     # 通用辅助函数
│       │
│       └── main.py            # 应用入口
│
├── tests/                     # 测试套件
│   ├── unit/                  # 单元测试
│   │   ├── application/
│   │   ├── domain/
│   │   └── utils/
│   │
│   ├── integration/           # 集成测试
│   │   ├── database/
│   │   └── api/
│   │
│   ├── e2e/                   # 端到端测试
│   │   └── workflows/         # 核心业务流程测试
│   │
│   ├── benchmark/             # 性能测试
│   └── conftest.py            # pytest全局fixture
│
├── scripts/                   # 运维脚本
│   ├── deployment/            # 部署相关
│   │   ├── docker/
│   │   │   ├── Dockerfile
│   │   │   └── docker-compose.yml
│   │   ├── k8s/               # Kubernetes配置
│   │   └── ansible/           # Ansible脚本
│   │
│   ├── data/                  # 数据处理
│   │   ├── migration/         # 数据迁移
│   │   └── seeding/           # 数据初始化
│   │
│   ├── monitoring/            # 监控脚本
│   └── maintenance.py         # 系统维护任务
│
├── docs/                      # 项目文档
│   ├── architecture/          # 架构设计
│   ├── api-reference/         # API文档
│   ├── decisions/             # 技术决策记录
│   └── onboarding.md          # 新成员指南
│
├── requirements/              # 依赖管理
│   ├── base.in                # 核心依赖
│   ├── dev.in                 # 开发环境
│   ├── test.in                # 测试环境
│   └── prod.in                # 生产环境
│
├── .env.example               # 环境变量示例
├── .pre-commit-config.yaml    # 代码提交前检查
├── pyproject.toml             # 项目元数据（PEP518）
├── Makefile                   # 项目自动化命令
└── README.md                  # 项目入口文档

关键目录解析

分层（src/your_project）

接口层 interfaces ：HTTP/RPC/CLI入口，只做参数校验和格式转换

应用层 application ：业务流程编排，事务边界控制

领域层 domain ：核心业务逻辑，与技术实现解耦

基础设施层 infrastructure ：数据库/缓存等具体实现

配置（config/）

# config/__init__.py
import os

ENV = os.getenv("APP_ENV", "dev")

def load_config():
    if ENV == "prod":
        from .prod import settings
    elif ENV == "test":
        from .test import settings
    else:
        from .dev import settings
    return settings

current_config = load_config()

测试（tests/）

部署（scripts/deployment）

容器化部署

# Dockerfile 多阶段构建
FROM python:3.11-slim AS builder
COPY requirements/prod.txt .
RUN pip install --no-cache-dir -r prod.txt

FROM python:3.11-slim AS runtime
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY ./src /app
ENV PYTHONPATH=/app
CMD ["python", "/app/your_project/main.py"]

依赖（requirements/）

# requirements/base.in
fastapi==0.95.0
sqlalchemy[asyncio]==2.0.10
pydantic-settings==2.0.2

# requirements/dev.in
-r base.in
pytest==7.3.1
ipdb==0.13.9
jupyterlab==3.6.3

# 使用pip-tools管理：
pip-compile --output-file=requirements.txt requirements/prod.in

大型项目

project-root/
└── services/                  # 微服务拆分子目录
    ├── user-service/          # 独立服务
    │   ├── src/               # 服务专用代码
    │   └── tests/
    │
    ├── order-service/
    ├── payment-service/
    └── shared-lib/            # 公共库
        ├── common-utils/
        ├── database-client/
        └── messaging-sdk/

实践清单

环境一致性：所有环境使用相同Python版本（pyenv + .python-version）

启动优化：冷启动时间超过5秒需拆分懒加载

依赖安全：定期扫描漏洞（safety/dependabot）

文档自动化：API文档随代码更新（FastAPI/Sphinx）

监控埋点：关键路径添加性能探针（OpenTelemetry）

资源限制：数据库连接池/线程池上限配置

异常处理：全局异常处理器记录堆栈

配置分离：敏感信息使用环境变量或配置中心