1. 引言
Python 在 Web 开发领域生态极其丰富,从轻量的 Flask、FastAPI 到全栈的 Django,都能快速搭建服务。但项目一旦从 Demo 走向生产,代码如何组织、职责如何划分,就成了决定可维护性的关键。
本文梳理 Python Web 项目中最常规、最通用的架构方案:以分层架构(Layered Architecture)为主线,配合清晰的项目目录结构、依赖注入、配置管理、数据访问与异步任务等常见组件,给出一套可以直接套用的工程骨架。
2. 为什么需要架构
一个典型的 Python Web 项目在成长过程中会遇到这些问题:
- 路由函数里塞满业务逻辑,一个函数几百行;
- 数据库查询、HTTP 调用、业务判断混在一起,无法单测;
- 换一个 ORM 或换一个框架,几乎要重写全部代码;
- 多人协作时,谁都能改任何文件,边界模糊。
架构的本质是划分边界、约束依赖方向。Python Web 项目最常用的做法就是分层:让上层依赖下层,下层不感知上层。
3. 经典分层架构
Python Web 项目最常规的分层如下:
各层职责:
| 层次 | 职责 | 典型内容 |
|---|---|---|
| 接口层(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 项目的常规架构可以概括为一句话:接口层薄、服务层厚、仓储层纯、数据层稳。
- 接口层负责协议与校验;
- 服务层承载业务与事务;
- 仓储层封装数据访问;
- 基础设施层提供配置、日志、缓存等横切能力。
配合清晰的目录结构、依赖注入与配置管理,这套架构既能支撑快速迭代,也能平滑演进到模块化单体甚至微服务。