Python 项目架构深度解析：从混乱到清晰

Python 项目架构深度解析：从混乱到清晰

优秀的 Python 项目架构并非一蹴而就，而是在不断迭代与反思中演进。许多初学者甚至中级开发者往往从"把代码塞进几个 .py 文件"开始，随着业务增长，项目逐渐陷入依赖混乱、难以测试、无法扩展的泥潭。本文将深入探讨 Python 项目的架构原则、分层设计、依赖管理及配置策略，并通过一个实际的任务管理后端案例，展示如何构建可维护、可测试、可扩展的系统。

为什么架构比代码本身更重要？

架构定义了系统的骨架与边界。它决定了：

• 变更成本：修改一个功能需要改动多少处？是否牵一发而动全身？
• 测试可行性：能否隔离业务逻辑进行单元测试，还是必须启动数据库、网络才能验证？
• 团队协作效率：多人能否在不频繁合并冲突的情况下并行开发？
• 技术债务积累速度：临时方案是否会固化，导致未来重构举步维艰？

Python 的动态特性赋予了开发者极大的自由度，但自由也意味着责任。如果没有清晰的架构约束，项目会很快陷入"大泥球"反模式。

核心架构原则

无论采用何种具体模式，以下原则是项目长期健康的基石。

1. 关注点分离 (Separation of Concerns)

每个模块、每个类、每个函数只应有一个变更的理由。将业务逻辑、数据访问、接口表示（HTTP、CLI、消息队列）严格分离。

2. 依赖倒置 (Dependency Inversion)

高层模块不应依赖低层模块，两者都应依赖抽象。在 Python 中，抽象可以是协议（typing.Protocol）、抽象基类或简单的心脏接口。依赖倒置让你能替换数据库、外部 API 而不影响核心业务代码。

3. 配置与代码分离

环境相关的信息（数据库连接、API 密钥、调试标志）不应硬编码在源码中。使用环境变量、配置文件（并支持覆盖）或专门配置对象。

4. 显式优于隐式

减少"魔法"。依赖注入容器、全局单例、隐式的上下文传递（如 threading.local）应谨慎使用，并确保其行为对调用者可预测。

常见架构模式在 Python 中的应用

分层架构 (Layered Architecture)

这是最直接也最实用的模式，尤其适合 Web 后端、ETL 管道等。典型三层：

• 表示层 (Presentation)：处理用户输入/输出，如 FastAPI 路由、Django 视图、CLI 解析器。不包含业务逻辑。
• 业务层 (Business / Service)：包含领域逻辑、规则、工作流编排。独立于传输协议和存储细节。
• 数据层 (Data Access)：封装数据库、外部 API、文件系统的读写。为业务层提供持久化服务。

关键规则 ：表示层可调用业务层，业务层可调用数据层，但反向不允许。业务层绝不应导入 fastapi.Request 或 django.db 特定类。

端口与适配器 (Hexagonal Architecture)

更精细的分层，强调通过"端口"（接口）定义边界，每个端口有多个"适配器"（实现）。例如业务层需要持久化，则定义一个 Repository 端口（抽象类），然后为 PostgreSQL、内存、测试提供不同适配器。Python 的动态类型让这一模式非常自然。

函数式核心 + 命令式壳

将纯函数式逻辑（无副作用、易测）推到核心，而将 I/O、异常处理、并发等放到外围壳中。这种风格在数据处理和财务系统中尤其受欢迎。

实战案例：任务管理后端

我们构建一个简单的任务管理 API，支持：

• 创建任务（标题、描述、截止日期）
• 列出任务（可按状态过滤）
• 更新任务状态（待办、进行中、已完成）

使用技术栈：FastAPI (表示层)、SQLAlchemy (数据层)、Pydantic (数据校验与序列化)。但重点展示架构而非框架细节。

项目结构

taskmanager/
├── src/
│   └── taskmanager/
│       ├── domain/              # 核心业务实体与接口（端口）
│       │   ├── models.py        # 纯 Python 数据类（Task 聚合根）
│       │   ├── repositories.py  # Repository 抽象基类
│       │   └── services.py      # 业务用例（如 TaskService）
│       ├── infrastructure/      # 适配器实现
│       │   ├── db/
│       │   │   ├── database.py  # SQLAlchemy 引擎、会话工厂
│       │   │   ├── models.py    # ORM 表映射
│       │   │   └── repositories.py # 具体 Repository 实现
│       │   └── config.py        # 配置加载
│       ├── api/                 # 表示层：FastAPI 路由
│       │   ├── dependencies.py  # 依赖项（如获取当前用户、数据库会话）
│       │   ├── schemas.py       # 请求/响应 Pydantic 模型
│       │   └── tasks.py         # 任务相关端点
│       └── main.py              # 应用入口
├── tests/                       # 单元测试与集成测试
├── pyproject.toml
└── .env.example

第一步：领域层（业务核心）

定义纯业务对象，不依赖任何框架。

# src/taskmanager/domain/models.py
from dataclasses import dataclass
from datetime import datetime
from enum import Enum
from typing import Optional


class TaskStatus(str, Enum):
    TODO = "todo"
    IN_PROGRESS = "in_progress"
    DONE = "done"


@dataclass
class Task:
    id: Optional[int]
    title: str
    description: str
    deadline: datetime
    status: TaskStatus
    created_at: datetime
    updated_at: datetime

    def change_status(self, new_status: TaskStatus) -> None:
        # 业务规则：已完成的任务不可回到待办
        if self.status == TaskStatus.DONE and new_status != TaskStatus.DONE:
            raise ValueError("Cannot reopen a done task")
        self.status = new_status
        self.updated_at = datetime.utcnow()

# src/taskmanager/domain/repositories.py
from abc import ABC, abstractmethod
from typing import List, Optional
from .models import Task, TaskStatus


class TaskRepository(ABC):
    @abstractmethod
    async def add(self, task: Task) -> Task:
        """保存新任务，返回包含生成的 ID 的任务"""
        pass

    @abstractmethod
    async def get(self, task_id: int) -> Optional[Task]:
        pass

    @abstractmethod
    async def list_by_status(self, status: Optional[TaskStatus] = None) -> List[Task]:
        pass

    @abstractmethod
    async def update(self, task: Task) -> None:
        pass

# src/taskmanager/domain/services.py
from .models import Task, TaskStatus
from .repositories import TaskRepository


class TaskService:
    def __init__(self, repo: TaskRepository):
        self._repo = repo

    async def create_task(self, title: str, description: str, deadline: datetime) -> Task:
        # 业务验证：截止日期不能早于当前时间
        if deadline < datetime.utcnow():
            raise ValueError("Deadline must be in the future")
        task = Task(
            id=None,
            title=title,
            description=description,
            deadline=deadline,
            status=TaskStatus.TODO,
            created_at=datetime.utcnow(),
            updated_at=datetime.utcnow(),
        )
        return await self._repo.add(task)

    async def change_task_status(self, task_id: int, new_status: TaskStatus) -> Task:
        task = await self._repo.get(task_id)
        if not task:
            raise ValueError("Task not found")
        task.change_status(new_status)
        await self._repo.update(task)
        return task

    async def list_tasks(self, status: Optional[TaskStatus] = None) -> list[Task]:
        return await self._repo.list_by_status(status)

亮点 ：TaskService 不知道任何关于数据库、HTTP 的内容，它只依赖 TaskRepository 抽象。单元测试时，可轻松传入内存实现的假 repository。

第二步：基础设施层（适配器）

实现具体的数据库访问。我们使用 SQLAlchemy 2.0 + async。

# src/taskmanager/infrastructure/db/models.py
from sqlalchemy import Column, Integer, String, DateTime, Enum
from sqlalchemy.ext.declarative import declarative_base
import enum

Base = declarative_base()

class TaskORM(Base):
    __tablename__ = "tasks"
    id = Column(Integer, primary_key=True, autoincrement=True)
    title = Column(String(255), nullable=False)
    description = Column(String, nullable=False)
    deadline = Column(DateTime, nullable=False)
    status = Column(Enum(enum.Enum("TaskStatus", ["todo", "in_progress", "done"])))
    created_at = Column(DateTime, nullable=False)
    updated_at = Column(DateTime, nullable=False)

# src/taskmanager/infrastructure/db/repositories.py
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import select
from typing import Optional, List
from ...domain.models import Task, TaskStatus
from ...domain.repositories import TaskRepository
from .models import TaskORM


class SQLAlchemyTaskRepository(TaskRepository):
    def __init__(self, session: AsyncSession):
        self._session = session

    async def add(self, task: Task) -> Task:
        orm_task = TaskORM(
            title=task.title,
            description=task.description,
            deadline=task.deadline,
            status=task.status.value,
            created_at=task.created_at,
            updated_at=task.updated_at,
        )
        self._session.add(orm_task)
        await self._session.flush()
        task.id = orm_task.id
        return task

    async def get(self, task_id: int) -> Optional[Task]:
        result = await self._session.execute(
            select(TaskORM).where(TaskORM.id == task_id)
        )
        orm_task = result.scalar_one_or_none()
        if not orm_task:
            return None
        return self._to_domain(orm_task)

    async def list_by_status(self, status: Optional[TaskStatus] = None) -> List[Task]:
        query = select(TaskORM)
        if status:
            query = query.where(TaskORM.status == status.value)
        result = await self._session.execute(query)
        orm_tasks = result.scalars().all()
        return [self._to_domain(orm) for orm in orm_tasks]

    async def update(self, task: Task) -> None:
        result = await self._session.execute(
            select(TaskORM).where(TaskORM.id == task.id)
        )
        orm_task = result.scalar_one()
        orm_task.title = task.title
        orm_task.description = task.description
        orm_task.deadline = task.deadline
        orm_task.status = task.status.value
        orm_task.updated_at = task.updated_at
        await self._session.flush()

    @staticmethod
    def _to_domain(orm: TaskORM) -> Task:
        return Task(
            id=orm.id,
            title=orm.title,
            description=orm.description,
            deadline=orm.deadline,
            status=TaskStatus(orm.status),
            created_at=orm.created_at,
            updated_at=orm.updated_at,
        )

第三步：表示层（FastAPI 路由与依赖注入）

使用 FastAPI 的依赖注入系统将 TaskService 与 SQLAlchemyTaskRepository 组装起来。我们显式创建依赖项，避免全局状态。

# src/taskmanager/api/dependencies.py
from fastapi import Depends, Request
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from ..infrastructure.db.repositories import SQLAlchemyTaskRepository
from ..domain.services import TaskService


async def get_db_session(request: Request) -> AsyncSession:
    session_factory: async_sessionmaker = request.app.state.session_factory
    async with session_factory() as session:
        yield session


async def get_task_service(session: AsyncSession = Depends(get_db_session)) -> TaskService:
    repo = SQLAlchemyTaskRepository(session)
    return TaskService(repo)

# src/taskmanager/api/schemas.py
from pydantic import BaseModel, Field
from datetime import datetime
from ..domain.models import TaskStatus


class TaskCreateRequest(BaseModel):
    title: str = Field(..., max_length=255)
    description: str
    deadline: datetime


class TaskResponse(BaseModel):
    id: int
    title: str
    description: str
    deadline: datetime
    status: TaskStatus
    created_at: datetime
    updated_at: datetime

    class Config:
        from_attributes = True  # 允许从 ORM/dataclass 转换

# src/taskmanager/api/tasks.py
from fastapi import APIRouter, Depends, HTTPException
from . import schemas
from ..domain.services import TaskService
from ..domain.models import TaskStatus
from datetime import datetime

router = APIRouter(prefix="/tasks", tags=["tasks"])


@router.post("/", response_model=schemas.TaskResponse)
async def create_task(
    req: schemas.TaskCreateRequest,
    service: TaskService = Depends(get_task_service),
):
    try:
        task = await service.create_task(
            title=req.title,
            description=req.description,
            deadline=req.deadline,
        )
        return task
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))


@router.patch("/{task_id}/status", response_model=schemas.TaskResponse)
async def update_task_status(
    task_id: int,
    new_status: TaskStatus,
    service: TaskService = Depends(get_task_service),
):
    try:
        task = await service.change_task_status(task_id, new_status)
        return task
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))


@router.get("/", response_model=list[schemas.TaskResponse])
async def list_tasks(
    status: TaskStatus | None = None,
    service: TaskService = Depends(get_task_service),
):
    tasks = await service.list_tasks(status)
    return tasks

第四步：应用入口

# src/taskmanager/main.py
from fastapi import FastAPI
from contextlib import asynccontextmanager
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
from .infrastructure.db import models
from .api import tasks

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 启动时创建数据库表（生产应使用 Alembic 迁移）
    engine = create_async_engine("sqlite+aiosqlite:///./tasks.db")
    async with engine.begin() as conn:
        await conn.run_sync(models.Base.metadata.create_all)
    app.state.session_factory = async_sessionmaker(engine, expire_on_commit=False)
    yield
    # 清理资源
    await engine.dispose()

app = FastAPI(lifespan=lifespan)
app.include_router(tasks.router)

测试策略：依赖倒置的收获

有了清晰的边界，测试变得极其容易。我们只需要针对 TaskService 编写单元测试，模拟 TaskRepository。

# tests/unit/test_task_service.py
import pytest
from datetime import datetime, timedelta
from src.taskmanager.domain.models import Task, TaskStatus
from src.taskmanager.domain.services import TaskService
from src.taskmanager.domain.repositories import TaskRepository


class InMemoryTaskRepository(TaskRepository):
    def __init__(self):
        self._tasks = {}
        self._next_id = 1

    async def add(self, task):
        task.id = self._next_id
        self._tasks[task.id] = task
        self._next_id += 1
        return task

    async def get(self, task_id):
        return self._tasks.get(task_id)

    async def list_by_status(self, status=None):
        if status is None:
            return list(self._tasks.values())
        return [t for t in self._tasks.values() if t.status == status]

    async def update(self, task):
        self._tasks[task.id] = task


@pytest.mark.asyncio
async def test_change_task_status():
    repo = InMemoryTaskRepository()
    service = TaskService(repo)
    deadline = datetime.utcnow() + timedelta(days=1)
    task = await service.create_task("test", "desc", deadline)
    assert task.status == TaskStatus.TODO

    updated = await service.change_task_status(task.id, TaskStatus.DONE)
    assert updated.status == TaskStatus.DONE
    # 验证无法重新打开
    with pytest.raises(ValueError):
        await service.change_task_status(task.id, TaskStatus.TODO)

集成测试只验证基础设施适配器与真实数据库的交互，使用测试数据库或事务回滚。由于业务逻辑已在单元测试中充分覆盖，集成测试数量可大幅减少。

配置管理：优雅的十二要素

在现代 Python 项目中，推荐使用 pydantic-settings 或 python-dotenv + 数据类。示例：

# src/taskmanager/infrastructure/config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str = "sqlite+aiosqlite:///./dev.db"
    debug: bool = False
    api_prefix: str = "/api/v1"

    class Config:
        env_file = ".env"

settings = Settings()

在 main.py 中使用 settings.database_url 等，彻底与环境解耦。

常见陷阱与最佳实践

陷阱1：让 ORM 实体渗入业务层

SQLAlchemy 的 declarative_base 对象带有 session 绑定，若直接传递给业务层，会导致业务代码中意外触发数据库操作，且难以测试。解决方案：定义纯领域模型，并实现映射器（如上述 _to_domain）。

陷阱2：在业务层中引用 Web 框架对象

request.user、request.headers 一旦进入业务函数，表示层和业务层就紧紧耦合。解决：在表示层提取所需信息（用户ID、角色等），作为普通参数传递给业务层。

陷阱3：过度使用全局依赖注入容器

虽然框架如 FastAPI 内置的 Depends 很好，但避免自行实现庞大复杂的 ServiceLocator。在函数签名中显式声明依赖（如 service: TaskService）更可测试、更显式。

总结

Python 项目架构的核心不是选择"最优雅"的模式，而是持续维持关注点分离、依赖倒置和清晰的边界。通过本文的任务管理案例，我们看到：

• 领域层使用纯 Python 对象，零框架依赖，易于演进业务规则。
• 基础设施层适配具体技术，可随时替换（如从 SQLite 切换到 PostgreSQL 或 MongoDB，只需改变 repository 实现）。
• 表示层轻薄，只负责转换 HTTP ↔️ 领域对象，并通过依赖注入组装依赖。

这种架构让项目在初期稍微多写几行胶水代码，但在后期需求变更、添加新功能、编写测试时，能节省数倍的时间。从混乱到清晰，并非一步登天，而是一步步向依赖倒置靠近的过程。希望本文能够为你设计下一个 Python 项目提供扎实的参考。