Python企业级项目开发的项目结构

一、项目结构规范（模块化分层架构）

project-root/                  # 项目根目录
├── src/                       # 源代码目录（包结构）
│   ├── core/                  # 核心业务逻辑层
│   │   ├── services/          # 业务服务实现
│   │   ├── models/            # 数据模型定义
│   │   ├── utils/             # 通用工具类
│   │   └── exceptions.py      # 自定义异常体系
│   ├── infrastructure/        # 基础设施层
│   │   ├── database/          # 数据库交互
│   │   ├── cache/             # 缓存实现
│   │   └── messaging/         # 消息队列处理
│   ├── api/                   # API接口层
│   │   ├── routers/           # FastAPI/Flask路由
│   │   └── schemas/           # Pydantic数据校验模型
│   └── config.py              # 配置加载入口
├── tests/                     # 测试代码目录
│   ├── unit/                  # 单元测试
│   ├── integration/           # 集成测试
│   └── conftest.py            # pytest全局fixture
├── scripts/                   # 运维脚本目录
│   ├── deploy/                # 部署脚本
│   └── db_migrations/         # 数据库迁移脚本
├── docs/                      # 项目文档
├── requirements/              # 依赖管理
│   ├── base.txt               # 基础依赖
│   ├── dev.txt                # 开发环境依赖
│   └── prod.txt               # 生产环境依赖
├── .env.example               # 环境变量模板
├── pyproject.toml             # 构建配置（PEP 621）
└── README.md                  # 项目总览文档

二、文件命名规范（遵循PEP8扩展）

模块文件：全小写+下划线，避免使用复数形式

✅ data_processor.py
❌ DataProcessor.py 或 dataProcess.py

测试文件：test_前缀+被测试模块名

test_user_service.py 对应 user_service.py

配置类文件：按作用域划分

全局配置：config.py
环境配置：.env.dev, .env.prod

特殊文件：

包初始化：__init__.py（新版可空但建议保留）
主程序入口：main.py 或 cli.py

三、自定义类结构规范（企业级实践）

from pydantic import BaseModel
from typing import Optional, List
from abc import ABC, abstractmethod

# 基础模型类
class BaseEntity(BaseModel):
    id: str
    created_at: datetime
    updated_at: Optional[datetime]

    class Config:
        orm_mode = True  # 支持ORM映射

# 抽象接口定义
class IRepository(ABC):
    @abstractmethod
    def get(self, entity_id: str) -> BaseEntity:
        """抽象查询方法"""
        pass

# 业务服务实现类
class UserService:
    def __init__(self, repo: IRepository):
        self._repo = repo  # 依赖注入

    @property
    def active_users(self) -> List[User]:
        """业务属性"""
        return [u for u in self._repo.list() if u.is_active]

    def register_user(self, user_data: UserCreateSchema) -> User:
        """带事务的业务方法"""
        with self._repo.transaction():
            if self._repo.exists(user_data.email):
                raise DuplicateUserError()
            return self._repo.create(user_data)

# 异常体系
class DomainError(Exception):
    """领域层基础异常"""
    def __init__(self, code: int, message: str):
        self.code = code
        self.message = message
        super().__init__(f"{code}: {message}")

class DuplicateUserError(DomainError):
    def __init__(self):
        super().__init__(1001, "User already exists")

四、进阶规范建议

类型标注：强制使用mypy进行静态类型检查
依赖管理：推荐使用Poetry管理项目依赖
日志规范：

import structlog
logger = structlog.get_logger(__name__)

class DatabaseClient:
    def connect(self):
        logger.info("db_connecting", host=config.DB_HOST)
        try:
            # 连接逻辑
            logger.debug("db_connection_success")
        except Exception as e:
            logger.error("db_connection_failed", exc_info=e)
            raise

异步支持：对IO密集型服务采用async/await模式

async def fetch_data(self) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(API_URL) as response:
            return await response.json()

五、配套工具链

代码质量：flake8 + black + isort
测试覆盖：pytest + coverage + factory_boy
文档生成：mkdocs + pdoc
CI/CD：GitHub Actions + Docker
监控：Sentry + Prometheus

企业级项目的关键在于建立清晰的领域边界和稳定的抽象层，建议采用领域驱动设计（DDD）思想组织代码结构。同时要注意控制模块的粒度，单个文件建议不超过500行，单个类不超过20个方法。在团队协作中，应通过pre-commit hooks和代码审查机制确保规范落地。