Python Web 常规架构实践:从分层设计到可落地工程结构

Source

1. 引言

Python 在 Web 开发领域生态极其丰富,从轻量的 Flask、FastAPI 到全栈的 Django,都能快速搭建服务。但项目一旦从 Demo 走向生产,代码如何组织、职责如何划分,就成了决定可维护性的关键。

本文梳理 Python Web 项目中最常规、最通用的架构方案:以分层架构(Layered Architecture)为主线,配合清晰的项目目录结构、依赖注入、配置管理、数据访问与异步任务等常见组件,给出一套可以直接套用的工程骨架。

2. 为什么需要架构

一个典型的 Python Web 项目在成长过程中会遇到这些问题:

  • 路由函数里塞满业务逻辑,一个函数几百行;
  • 数据库查询、HTTP 调用、业务判断混在一起,无法单测;
  • 换一个 ORM 或换一个框架,几乎要重写全部代码;
  • 多人协作时,谁都能改任何文件,边界模糊。

架构的本质是划分边界、约束依赖方向。Python Web 项目最常用的做法就是分层:让上层依赖下层,下层不感知上层。

3. 经典分层架构

Python Web 项目最常规的分层如下:

客户端 / 前端

接口层 API / Router

服务层 Service

仓储层 Repository / DAO

数据层 Model / DB

外部依赖 Client

异步任务 Task

各层职责:

层次 职责 典型内容
接口层(API / Router) 参数校验、鉴权、序列化、返回响应 FastAPI Router、Flask Blueprint、Django View
服务层(Service) 业务编排、事务边界、领域规则 业务用例函数/类
仓储层(Repository) 数据访问抽象,屏蔽 ORM 细节 CRUD 封装、查询构造
数据层(Model) 表结构、实体定义 SQLAlchemy Model、Django Model
基础设施层 配置、日志、缓存、消息队列、外部 HTTP settings、logger、redis client

核心原则:接口层不写业务,服务层不碰 SQL,仓储层不做业务判断。

4. 推荐的项目目录结构

以 FastAPI + SQLAlchemy 为例,一套常见且好维护的结构:

project/
├── app/
│   ├── main.py                 # 应用入口,注册路由与中间件
│   ├── api/                    # 接口层
│   │   ├── deps.py             # 依赖注入(DB Session、当前用户)
│   │   └── v1/
│   │       ├── router.py       # 路由聚合
│   │       └── users.py        # 用户相关接口
│   ├── services/               # 服务层
│   │   └── user_service.py
│   ├── repositories/           # 仓储层
│   │   └── user_repository.py
│   ├── models/                 # 数据层
│   │   └── user.py
│   ├── schemas/                # Pydantic 请求/响应模型
│   │   └── user.py
│   ├── core/                   # 配置、安全、日志
│   │   ├── config.py
│   │   ├── security.py
│   │   └── logging.py
│   ├── db/                     # 数据库连接与会话
│   │   ├── session.py
│   │   └── base.py
│   └── tasks/                  # 异步任务(Celery / ARQ)
│       └── email_task.py
├── tests/
├── migrations/                 # Alembic 迁移脚本
├── requirements.txt
└── .env

按业务能力而非技术类型拆分的变体(更适合中大型项目):

app/
├── modules/
│   ├── user/
│   │   ├── router.py
│   │   ├── service.py
│   │   ├── repository.py
│   │   ├── models.py
│   │   └── schemas.py
│   └── order/
│       └── ...

5. 各层代码示例

5.1 数据层:Model

# app/models/user.py
from sqlalchemy import String
from sqlalchemy.orm import Mapped, mapped_column

from app.db.base import Base


class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)
    username: Mapped[str] = mapped_column(String(64), unique=True, index=True)
    email: Mapped[str] = mapped_column(String(128), unique=True)
    hashed_password: Mapped[str] = mapped_column(String(256))

5.2 仓储层:Repository

# app/repositories/user_repository.py
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession

from app.models.user import User


class UserRepository:
    def __init__(self, session: AsyncSession) -> None:
        self.session = session

    async def get_by_id(self, user_id: int) -> User | None:
        result = await self.session.execute(select(User).where(User.id == user_id))
        return result.scalar_one_or_none()

    async def get_by_username(self, username: str) -> User | None:
        result = await self.session.execute(
            select(User).where(User.username == username)
        )
        return result.scalar_one_or_none()

    async def create(self, username: str, email: str, hashed_password: str) -> User:
        user = User(username=username, email=email, hashed_password=hashed_password)
        self.session.add(user)
        await self.session.flush()
        return user

5.3 服务层:Service

# app/services/user_service.py
from app.core.security import hash_password
from app.repositories.user_repository import UserRepository


class UserService:
    def __init__(self, repo: UserRepository) -> None:
        self.repo = repo

    async def register(self, username: str, email: str, password: str):
        if await self.repo.get_by_username(username):
            raise ValueError("用户名已存在")
        return await self.repo.create(
            username=username,
            email=email,
            hashed_password=hash_password(password),
        )

5.4 接口层:Router

# app/api/v1/users.py
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

from app.api.deps import get_db
from app.repositories.user_repository import UserRepository
from app.schemas.user import UserCreate, UserOut
from app.services.user_service import UserService

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


@router.post("", response_model=UserOut, status_code=201)
async def create_user(payload: UserCreate, db: AsyncSession = Depends(get_db)):
    service = UserService(UserRepository(db))
    try:
        user = await service.register(payload.username, payload.email, payload.password)
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc
    await db.commit()
    return user

可以看到:接口层只做参数接收、异常转换和响应返回,业务规则全部在 Service 中。

6. 常见配套组件

一套完整的 Python Web 架构通常还包含以下部分:

  • 配置管理:pydantic-settings 读取 .env,区分开发/测试/生产环境;
  • 依赖注入:FastAPI 的 Depends,或 dependency-injector 库;
  • 数据库迁移:Alembic 管理表结构版本;
  • 认证鉴权:JWT + OAuth2,统一在 core/security.py;
  • 日志与监控:结构化日志(structlog)、Prometheus 指标;
  • 异步任务:Celery / ARQ / RQ 处理耗时任务,避免阻塞请求;
  • 缓存:Redis 封装为独立 client,通过依赖注入使用;
  • 容器化:Dockerfile + docker-compose,统一运行环境。

7. 架构选型建议

项目规模 推荐方案
小型工具、原型 Flask/FastAPI 单文件或简单分包,不必强行分层
中小型业务系统 分层架构 + 按技术分层目录
中大型、多团队协作 分层 + 按业务模块拆分(模块化单体)
超大型、独立演进 微服务 / 领域驱动设计(DDD)

需要强调的是:不要为了架构而架构。分层带来的收益是边界清晰与可测试性,代价是文件数量增加。项目初期可以适度简化,随着复杂度上升再逐步拆分。

8. 总结

Python Web 项目的常规架构可以概括为一句话:接口层薄、服务层厚、仓储层纯、数据层稳。

  • 接口层负责协议与校验;
  • 服务层承载业务与事务;
  • 仓储层封装数据访问;
  • 基础设施层提供配置、日志、缓存等横切能力。

配合清晰的目录结构、依赖注入与配置管理,这套架构既能支撑快速迭代,也能平滑演进到模块化单体甚至微服务。