Python全栈开发：前后端分离项目架构详解

---

在现代Web开发中，前后端分离已成为主流架构模式。本文将详细介绍如何使用纯Python技术栈构建一个完整的前后端分离项目，包括项目结构设计、技术选型和最佳实践。

技术栈选择

后端技术栈

• 框架: FastAPI（高性能异步Web框架）
• 数据库: PostgreSQL + SQLAlchemy ORM
• 缓存: Redis
• 认证: JWT Token
• API文档: Swagger/OpenAPI（FastAPI自带）
• 测试: pytest + httpx
• 依赖管理: Poetry

前端技术栈

• 框架: Streamlit 或 Reflex（纯Python前端框架）
• 状态管理: 内置状态管理
• HTTP客户端: httpx/requests
• 数据可视化: Plotly + Dash（可选）

项目整体结构

my-python-fullstack-project/
├── README.md
├── docker-compose.yml
├── .env.example
├── .gitignore
├── requirements.txt
├── backend/                    # 后端服务
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py            # FastAPI应用入口
│   │   ├── config.py          # 配置文件
│   │   ├── dependencies.py    # 依赖注入
│   │   ├── database.py        # 数据库连接
│   │   ├── models/           # 数据模型
│   │   │   ├── __init__.py
│   │   │   ├── user.py
│   │   │   ├── product.py
│   │   │   └── base.py
│   │   ├── schemas/          # Pydantic模式
│   │   │   ├── __init__.py
│   │   │   ├── user.py
│   │   │   ├── product.py
│   │   │   └── response.py
│   │   ├── api/              # API路由
│   │   │   ├── __init__.py
│   │   │   ├── deps.py
│   │   │   ├── v1/
│   │   │   │   ├── __init__.py
│   │   │   │   ├── auth.py
│   │   │   │   ├── users.py
│   │   │   │   └── products.py
│   │   │   └── api.py
│   │   ├── crud/             # CRUD操作
│   │   │   ├── __init__.py
│   │   │   ├── base.py
│   │   │   ├── user.py
│   │   │   └── product.py
│   │   ├── core/             # 核心功能
│   │   │   ├── __init__.py
│   │   │   ├── security.py   # 安全相关
│   │   │   ├── auth.py       # 认证逻辑
│   │   │   └── exceptions.py # 异常处理
│   │   ├── services/         # 业务逻辑层
│   │   │   ├── __init__.py
│   │   │   ├── user_service.py
│   │   │   └── product_service.py
│   │   └── utils/            # 工具函数
│   │       ├── __init__.py
│   │       ├── logger.py
│   │       └── helpers.py
│   ├── alembic/              # 数据库迁移
│   │   ├── versions/
│   │   ├── env.py
│   │   └── alembic.ini
│   ├── tests/                # 测试文件
│   │   ├── __init__.py
│   │   ├── conftest.py
│   │   ├── test_auth.py
│   │   └── test_users.py
│   ├── Dockerfile
│   ├── requirements.txt
│   └── pyproject.toml
├── frontend/                  # 前端应用
│   ├── app.py                # 主应用文件
│   ├── config.py             # 前端配置
│   ├── pages/                # 页面组件
│   │   ├── __init__.py
│   │   ├── home.py
│   │   ├── auth/
│   │   │   ├── __init__.py
│   │   │   ├── login.py
│   │   │   └── register.py
│   │   ├── dashboard/
│   │   │   ├── __init__.py
│   │   │   ├── overview.py
│   │   │   └── analytics.py
│   │   └── products/
│   │       ├── __init__.py
│   │       ├── list.py
│   │       └── detail.py
│   ├── components/           # 可复用组件
│   │   ├── __init__.py
│   │   ├── sidebar.py
│   │   ├── header.py
│   │   └── forms/
│   │       ├── __init__.py
│   │       ├── auth_forms.py
│   │       └── product_forms.py
│   ├── services/             # API服务
│   │   ├── __init__.py
│   │   ├── api_client.py     # HTTP客户端封装
│   │   ├── auth_service.py
│   │   └── product_service.py
│   ├── utils/                # 前端工具
│   │   ├── __init__.py
│   │   ├── constants.py
│   │   ├── validators.py
│   │   └── formatters.py
│   ├── static/               # 静态资源
│   │   ├── css/
│   │   ├── js/
│   │   └── images/
│   ├── tests/                # 前端测试
│   │   ├── __init__.py
│   │   └── test_components.py
│   ├── Dockerfile
│   └── requirements.txt
├── shared/                   # 共享代码
│   ├── __init__.py
│   ├── constants.py          # 共享常量
│   ├── exceptions.py         # 共享异常
│   └── utils.py              # 共享工具
├── scripts/                  # 部署脚本
│   ├── deploy.sh
│   ├── backup.sh
│   └── init_db.py
├── docs/                     # 项目文档
│   ├── api.md
│   ├── deployment.md
│   └── development.md
└── nginx/                    # Nginx配置└── nginx.conf

详细目录结构说明

后端架构（backend/）

1. 应用核心（app/）

• main.py: FastAPI应用的入口点，包含应用初始化、中间件配置和路由注册
• config.py: 应用配置管理，使用Pydantic Settings进行环境变量管理
• database.py: 数据库连接和会话管理

2. 数据层（models/）

使用SQLAlchemy定义数据模型，每个模型对应一个文件：

# models/user.py
from sqlalchemy import Column, Integer, String, Boolean
from .base import Baseclass User(Base):__tablename__ = "users"id = Column(Integer, primary_key=True, index=True)email = Column(String, unique=True, index=True)hashed_password = Column(String)is_active = Column(Boolean, default=True)

3. API模式层（schemas/）

使用Pydantic定义请求和响应模型，确保数据验证和API文档生成：

# schemas/user.py
from pydantic import BaseModel, EmailStrclass UserCreate(BaseModel):email: EmailStrpassword: strclass UserResponse(BaseModel):id: intemail: stris_active: boolclass Config:from_attributes = True

4. API路由层（api/）

按版本和功能模块组织API端点：

# api/v1/users.py
from fastapi import APIRouter, Depends
from ...services.user_service import UserServicerouter = APIRouter()@router.post("/", response_model=UserResponse)
async def create_user(user_data: UserCreate, service: UserService = Depends()):return await service.create_user(user_data)

5. 业务逻辑层（services/）

封装复杂的业务逻辑，保持控制器的简洁：

# services/user_service.py
class UserService:def __init__(self, db: Session = Depends(get_db)):self.db = dbasync def create_user(self, user_data: UserCreate) -> User:# 业务逻辑实现pass

前端架构（frontend/）

1. 应用入口（app.py）

# app.py
import streamlit as st
from pages.home import show_home
from pages.auth.login import show_logindef main():st.set_page_config(page_title="My App", layout="wide")# 路由逻辑if "authenticated" not in st.session_state:show_login()else:show_home()if __name__ == "__main__":main()

2. 页面组件（pages/）

按功能模块组织页面组件，每个页面负责特定的UI逻辑。

3. 可复用组件（components/）

抽象通用的UI组件，提高代码复用性。

4. API服务层（services/）

封装与后端API的交互逻辑：

# services/api_client.py
import httpx
from typing import Optionalclass APIClient:def __init__(self, base_url: str):self.base_url = base_urlself.token: Optional[str] = Noneasync def request(self, method: str, endpoint: str, **kwargs):headers = kwargs.get('headers', {})if self.token:headers['Authorization'] = f'Bearer {self.token}'async with httpx.AsyncClient() as client:response = await client.request(method, f"{self.base_url}{endpoint}", headers=headers, **kwargs)return response.json()

关键配置文件

1. docker-compose.yml

version: '3.8'
services:backend:build: ./backendports:- "8000:8000"environment:- DATABASE_URL=postgresql://user:pass@db:5432/myapp- REDIS_URL=redis://redis:6379depends_on:- db- redisfrontend:build: ./frontendports:- "8501:8501"environment:- API_BASE_URL=http://backend:8000depends_on:- backenddb:image: postgres:13environment:- POSTGRES_DB=myapp- POSTGRES_USER=user- POSTGRES_PASSWORD=passvolumes:- postgres_data:/var/lib/postgresql/dataredis:image: redis:7-alpineports:- "6379:6379"volumes:postgres_data:

2. 后端Dockerfile

FROM python:3.11-slimWORKDIR /appCOPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txtCOPY . .CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

3. 前端Dockerfile

FROM python:3.11-slimWORKDIR /appCOPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txtCOPY . .EXPOSE 8501CMD ["streamlit", "run", "app.py", "--server.port=8501", "--server.address=0.0.0.0"]

开发工作流

1. 环境设置

# 克隆项目
git clone <repository-url>
cd my-python-fullstack-project# 设置虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows# 安装依赖
pip install -r requirements.txt

2. 开发模式启动

# 启动后端
cd backend
uvicorn app.main:app --reload --port 8000# 启动前端（新终端）
cd frontend
streamlit run app.py --server.port 8501

3. 生产环境部署

# 使用Docker Compose
docker-compose up -d# 数据库迁移
docker-compose exec backend alembic upgrade head

项目优势

1. 技术一致性

• 前后端都使用Python，降低了技术栈的复杂性
• 开发团队只需掌握一种主要编程语言
• 代码共享和维护更加容易

2. 高性能

• FastAPI提供了异步支持和高性能
• 自动生成API文档
• 内置数据验证和序列化

3. 快速开发

• Streamlit提供了快速构建Web应用的能力
• 丰富的组件库和可视化支持
• 无需前端框架的复杂配置

4. 良好的可扩展性

• 清晰的分层架构
• 模块化设计
• 易于测试和维护

最佳实践建议

1. 代码组织

• 遵循单一职责原则
• 使用依赖注入
• 保持接口的一致性

2. 错误处理

• 统一的异常处理机制
• 友好的错误消息
• 适当的日志记录

3. 安全性

• JWT token认证
• 输入验证和清理
• CORS配置
• 环境变量管理

4. 性能优化

• 数据库查询优化
• 缓存策略
• 异步处理
• 资源压缩