FastAPI + SQLAlchemy PythonWeb体系梳理

前言
[一、FastAPI：现代异步 Web 框架](#一、FastAPI：现代异步 Web 框架)
- [1.1 FastAPI 是什么](#1.1 FastAPI 是什么)
- [1.2 FastAPI 用来干什么](#1.2 FastAPI 用来干什么)
- [1.3 为什么选择 FastAPI](#1.3 为什么选择 FastAPI)
- [1.4 配套运行服务：Uvicorn](#1.4 配套运行服务：Uvicorn)
- - [1.4.1 什么是 Uvicorn](#1.4.1 什么是 Uvicorn)
  - [1.4.2 Uvicorn 用来干什么](#1.4.2 Uvicorn 用来干什么)
  - [1.4.3 核心工作机制（底层原理）](#1.4.3 核心工作机制（底层原理）)
  - [1.4.4 启动命令](#1.4.4 启动命令)
[二、FastAPI 怎么用](#二、FastAPI 怎么用)
- [2.1 路由系统](#2.1 路由系统)
- [2.2 请求参数](#2.2 请求参数)
- - 1.路径参数
  - [2. 查询参数](#2. 查询参数)
  - [3. 请求体参数](#3. 请求体参数)
- [2.3 响应处理](#2.3 响应处理)
- [2.4 异常处理](#2.4 异常处理)
- [2.5 中间件](#2.5 中间件)
- [2.6 依赖注入](#2.6 依赖注入)
[三、异步 SQLAlchemy ORM 数据库框架](#三、异步 SQLAlchemy ORM 数据库框架)
- [3.1 基础概念：ORM & SQLAlchemy](#3.1 基础概念：ORM & SQLAlchemy)
- [3.2 核心组件](#3.2 核心组件)
- - [3.2.1 异步数据库引擎（Engine）](#3.2.1 异步数据库引擎（Engine）)
  - [3.2.2 模型基类 Base](#3.2.2 模型基类 Base)
  - [3.2.3 异步会话 AsyncSession](#3.2.3 异步会话 AsyncSession)
- [3.3 数据表初始化（项目启动自动建表）](#3.3 数据表初始化（项目启动自动建表）)
- [3.4 ORM 标准 CRUD 实操](#3.4 ORM 标准 CRUD 实操)
- - [3.4.1 通用查询规则](#3.4.1 通用查询规则)
  - [3.4.2 各类查询操作](#3.4.2 各类查询操作)
  - [3.4.3 新增数据](#3.4.3 新增数据)
  - [3.4.4 更新数据](#3.4.4 更新数据)
  - [3.4.5 删除数据](#3.4.5 删除数据)
[四、FastAPI + 异步 SQLAlchemy 整体整合架构](#四、FastAPI + 异步 SQLAlchemy 整体整合架构)
- [4.1 全链路请求流转](#4.1 全链路请求流转)
- [4.2 整合核心要点](#4.2 整合核心要点)

前言

FastAPI 是当下 Python 生态中高性能异步 Web 接口框架，凭借原生异步支持、自动类型校验、交互式接口文档等特性，广泛应用于后端接口、微服务、爬虫服务等场景。

而 SQLAlchemy 作为 Python 生态最成熟的 ORM 框架，其异步版本完美适配 FastAPI 异步架构，是企业级项目的主流技术组合。

一、FastAPI：现代异步 Web 框架

1.1 FastAPI 是什么

FastAPI 是一个基于 Python 3.8+ 的现代化 Web 框架，专门用于快速构建 API 接口服务。它融合了 Starlette（Web 框架内核）和 Pydantic（数据验证）的优势，提供了高性能与开发效率的完美平衡。

1.2 FastAPI 用来干什么

构建 RESTful API：快速实现增删改查接口
开发微服务：轻量级、高性能，适合服务拆分
提供后端服务：为前端、移动端提供数据接口
实时通信：支持 WebSocket，实现实时推送
AI 模型服务：快速部署机器学习模型为 API

1.3 为什么选择 FastAPI

特性	说明
异步高性能	基于 async/await，性能媲美 Node.js 和 Go
自动文档生成	开箱即用的 Swagger UI 和 ReDoc，无需手动维护
类型提示与验证	Pydantic 自动验证请求数据，减少手写校验代码
开发效率高	编辑器智能提示，减少调试时间
依赖注入系统	优雅地复用代码逻辑

1.4 配套运行服务：Uvicorn

FastAPI 本身只是应用框架，必须依靠 ASGI 服务器才能对外提供服务，Uvicorn 是官方推荐的运行载体，本节沿用统一逻辑讲解。

1.4.1 什么是 Uvicorn

Uvicorn 是一款纯异步 ASGI 协议服务器，专门用于运行 FastAPI、Starlette 等 ASGI 应用，底层基于 uvloop（高性能异步事件循环）和 httptools（HTTP 解析工具）优化。

补充区分：传统 Flask/Django 使用 WSGI 服务器（Gunicorn、uWSGI），仅支持同步代码；Uvicorn 同时兼容同步、异步代码，是异步框架的专属服务容器。

1.4.2 Uvicorn 用来干什么

监听服务器端口，接收客户端 HTTP 请求；
解析 HTTP 报文，将请求转发给 FastAPI 应用；
管理异步事件循环、进程 / 线程调度，处理并发请求；
接收 FastAPI 生成的响应数据，回传给客户端。

1.4.3 核心工作机制（底层原理）

WSGI 和 ASGI 是 Python 生态统一规定的「通信协议 / 接口规范」，用来规范 Web 服务器和 Python Web 应用（框架）之间的数据交互规则：

协议差异：

WSGI（web服务器网关接口）为同步阻塞协议，原生串行处理请求，借助多线程 / 多进程虽能优化并发，但线程依旧会被 IO 阻塞，并发能力存在明显瓶颈，仅适用于传统低并发 Web 项目。

ASGI （异步服务器接口）基于事件循环和协程实现异步非阻塞，并发能力远优于 WSGI，同时原生支持异步语法与长连接能力，资源占用更少，是当下高并发接口、异步服务的主流选择。

进程模型

开发环境：默认单进程，配合热加载监听代码变更；
生产环境：支持多进程，利用 CPU 多核资源进一步提升并发。

完整请求流转

客户端发起请求 → 操作系统 TCP 端口监听 → Uvicorn 解析 HTTP 协议 → 分发至 FastAPI 路由 → 执行接口逻辑 → 生成响应 → Uvicorn 封装报文返回客户端。

热加载 --reload 原理

开发专用参数，会实时监听项目目录文件，代码修改后自动重启服务；生产环境必须关闭，会造成额外性能损耗。

1.4.4 启动命令

python 复制代码

# 1. 开发环境：热加载启动（main=文件名，app=FastAPI实例）
uvicorn main:app --reload

# 2. 生产环境：绑定IP、端口 + 多进程（关闭热加载）
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

二、FastAPI 怎么用

2.1 路由系统

什么是路由？

路由是 URL 地址与处理函数之间的映射关系，决定用户访问特定地址时执行哪段代码。

定义路由：

python 复制代码

from fastapi import FastAPI

app = FastAPI()

# GET 请求 - 查询资源
@app.get("/users")
async def list_users():
    return {"users": []}

# POST 请求 - 创建资源
@app.post("/users")
async def create_user():
    return {"status": "created"}

# PUT 请求 - 完整更新
@app.put("/users/{user_id}")
async def update_user(user_id: int):
    return {"user_id": user_id}

# DELETE 请求 - 删除资源
@app.delete("/users/{user_id}")
async def delete_user(user_id: int):
    return {"deleted": user_id}

2.2 请求参数

FastAPI 将请求参数分为三类，结合内置工具实现精准校验，是接口开发的核心：

1.路径参数

是什么 ：拼接在 URL 路径中的参数，格式： /资源/{参数}；

用途：定位唯一资源（如根据 ID 查询单条数据）；

使用 & 校验 ：通过 Path 实现范围、长度、必填校验。

python 复制代码

from fastapi import Path

# 分类ID：1~100
@app.get("/category/{cate_id}")
async def get_cate(cate_id: int = Path(..., ge=1, le=100)):
    return {"cate_id": cate_id}

2. 查询参数

是什么 ：URL 中 ? 之后的键值对参数（?k1=v1&k2=v2）；

用途：资源过滤、分页、排序等批量操作；

使用 & 校验 ：通过 Query 设置默认值、范围、长度。

python 复制代码

from fastapi import Query

# 图书查询：分类默认值，价格50~100
@app.get("/book")
async def get_book(
    category: str = Query("Python开发", min_length=5),
    price: int = Query(..., ge=50, le=100)
):
    return {"category": category, "price": price}

3. 请求体参数

是什么 ：存放在 HTTP 请求 Body 中的 JSON 数据；

用途：POST/PUT 请求，传递大批量数据（新增、修改资源）；

使用 & 校验 ：基于 Pydantic.BaseModel 定义模型，搭配 Field 校验字段。

python 复制代码

from pydantic import BaseModel, Field

# 定义请求体模型
class Book(BaseModel):
    book_name: str = Field(..., min_length=2, max_length=20)
    author: str = Field(..., min_length=2, max_length=10)
    publisher: str = Field("黑马出版社")
    price: float = Field(..., gt=0)

# 新增图书接口
@app.post("/book/add")
async def add_book(book: Book):
    return book.dict()

2.3 响应处理

是什么 ：接口返回给客户端的数据 / 内容；

用途：按照业务需求返回 JSON、HTML、文件、文本等内容；

分类与用法：

内置多类型响应：FastAPI 提供多种响应类，适配不同场景；
response_model：如果是json类型，基于 Pydantic 模型强制约束响应格式，统一接口输出。

python 复制代码

from fastapi.responses import HTMLResponse, FileResponse
from pydantic import BaseModel

# 1. 返回HTML页面
@app.get("/html", response_class=HTMLResponse)
async def get_html():
    return "<h1>FastAPI 页面</h1>"

# 2. 返回文件下载
@app.get("/file")
async def get_file():
    return FileResponse("./test.png")

# 3. 约束JSON响应格式
class NewsResp(BaseModel):
    id: int
    title: str

@app.get("/news/{id}", response_model=NewsResp)
async def get_news(id: int):
    return {"id": id, "title": "新闻标题"}

2.4 异常处理

是什么 ：主动捕获业务异常并返回标准错误信息；

用途：统一客户端错误提示（4xx 状态码）；

用法：使用 HTTPException 抛出异常。

python 复制代码

from fastapi import HTTPException

@app.get("/news/{id}")
async def get_news(id: int):
    if id not in [1,2,3]:
        raise HTTPException(status_code=404, detail="新闻ID不存在")
    return {"id": id}

2.5 中间件

是什么 ：中间件是全局 HTTP 请求拦截函数 ，每一次客户端请求都会触发执行，分为「请求前置逻辑」和「响应后置逻辑」。

用途：处理全接口通用逻辑：全局日志记录、跨域处理、全局身份认证、接口性能监控、统一设置响应头。

核心特征 & 执行规则：

作用范围：全局所有接口，无法单独对某个接口生效；
执行顺序：多个中间件同时存在时，遵循 自下而上 执行；
执行时机：请求到达路由函数前执行前置逻辑，响应返回客户端前执行后置逻辑。

实操用法 :

通过 @app.middleware("http") 装饰器定义异步中间件：

python 复制代码

@app.middleware("http")
async def http_middleware(request, call_next):
    # 前置逻辑：请求进入路由前
    print("请求开始")
    
    # 执行后续路由/中间件逻辑，获取响应
    response = await call_next(request)
    
    # 后置逻辑：响应返回客户端前
    print("请求结束")
    return response

2.6 依赖注入

是什么 ：依赖注入是 FastAPI 内置的代码复用机制 ：将通用逻辑封装为独立函数（依赖项 ），框架自动调用依赖项，并把执行结果注入到路由函数中。

用途：抽离多个接口的重复代码，实现逻辑解耦；典型场景：分页参数、数据库会话、局部接口权限校验、公共参数提取。

核心特征 & 执行规则：

代码复用：通用逻辑只编写一次，多处引用；
解耦：业务代码与公共代码分离，便于维护；
易测试：可快速替换模拟依赖，完成单元测试；
灵活性高：按需绑定接口，不影响全局。

实操用法:

python 复制代码

from fastapi import Depends, Query

# 1. 定义依赖项：通用分页参数
async def page_params(
    skip: int = Query(0, ge=0),
    limit: int = Query(10, le=60)
):
    return {"skip": skip, "limit": limit}

# 2. 路由中声明依赖，自动注入结果
@app.get("/news/list")
async def news_list(page: dict = Depends(page_params)):
    return {"data": [], "page": page}

@app.get("/user/list")
async def user_list(page: dict = Depends(page_params)):
    return {"data": [], "page": page}

底层原理: 路由函数执行前，FastAPI 会自动解析 Depends 标记的依赖项，串行执行所有依赖函数，将返回值作为参数传入路由函数。

三、异步 SQLAlchemy ORM 数据库框架

FastAPI 开发接口必然需要对接数据库，异步 SQLAlchemy 是目前适配 FastAPI 最优的 ORM 方案

3.1 基础概念：ORM & SQLAlchemy

什么是 ORM:

ORM（对象关系映射）是一种编程思想：将编程语言中的「对象」与数据库中的「数据表」建立映射关系。开发者通过操作 Python 对象实现数据库增删改查，无需手写原生 SQL 语句。

什么是 SQLAlchemy:

SQLAlchemy 是 Python 生态功能最全面、企业级使用最广泛的 ORM 框架，分为两个版本：

同步版本：适配传统 WSGI 框架（Django/Flask）；
异步版本：sqlalchemy $asyncio$ ，原生支持 async/await，完美对接 FastAPI 异步架构。

SQLAlchemy 用来干什么:

以面向对象的方式操作 MySQL、PostgreSQL 等关系型数据库；
自动管理数据库连接、事务、SQL 语句生成；
统一数据表结构定义，实现代码层面的表结构维护；
规避手写 SQL 带来的注入风险，简化数据库代码。

3.2 核心组件

异步 SQLAlchemy 由 异步引擎、模型基类、异步会话 三大核心组件构成

3.2.1 异步数据库引擎（Engine）

是什么

异步引擎是 SQLAlchemy 对接数据库的顶层入口，是整个 ORM 的核心调度器。

用来干什么

管理数据库连接池，复用长连接，避免频繁创建 / 销毁连接；
SQL 编译：引擎做「翻译官」，把 Python 代码转成数据库能看懂的 SQL（数据库不负责翻译）；
请求调度：引擎做「总指挥」，分配连接执行SQL、管理事务、处理异步、转换结果；

底层工作原理

不再依赖传统同步 DBAPI，直接对接 aiomysql/asyncpg 等异步驱动，基于 asyncio 事件循环实现非阻塞数据库 IO，和 FastAPI 异步架构完全对齐；
内置连接池机制：pool_size 为常驻连接数，max_overflow 为临时溢出连接数，高并发下自动扩容，空闲连接自动回收，大幅提升并发性能。

实操代码

python 复制代码

from sqlalchemy.ext.asyncio import create_async_engine

# 数据库连接串：mysql+aiomysql 代表使用异步MySQL驱动
DB_URL = "mysql+aiomysql://root:123456@localhost:3306/fastapi_test?charset=utf8"

# 创建异步引擎
async_engine = create_async_engine(
    url=DB_URL,
    echo=True,          # 开发开启SQL日志，生产关闭
    pool_size=10,       # 连接池常驻连接数
    max_overflow=20     # 连接池最大临时溢出连接
)

3.2.2 模型基类 Base

是什么：

Base 是所有数据表模型的统一父类，需要继承官方基类 DeclarativeBase。

用来干什么：

统一规范项目中所有数据表模型的结构；
封装公共字段（创建时间、更新时间），避免重复定义；
收集全局数据表元数据 metadata，支持批量建表、删表。

底层原理

元类 DeclarativeMeta：作为所有模型的创建器，在类定义阶段自动执行 __new__；
独立存储：解析当前模型的表名、字段后，将表结构赋值给当前模型类的 __table__，单表信息随模型独立保存；
全局汇总：把每张表的结构同步存入根类 DeclarativeBase.metadata.tables，统一管理全项目数据表；

业务基类 Base：继承官方 DeclarativeBase，统一注入公共字段，作为项目所有数据表模型的父类。

python 复制代码

class DeclarativeMeta(type):
    def __new__(cls, name, bases, attrs):
        # 1. 创建当前模型类
        model_cls = super().__new__(cls, name, bases, attrs)  
        # 跳过根基类本身（只处理业务数据表模型）
        if name == "DeclarativeBase":
            return model_cls  
        # 2. 解析当前模型的字段、表名等结构
        table_name = attrs.get("__tablename__", name.lower())
        columns = {k: v for k, v in attrs.items() if hasattr(v, "is_column")}
        table_info = {"table_name": table_name, "columns": columns}
        # 3. 单独存储：当前模型类绑定自身表结构 __table__
        model_cls.__table__ = table_info
        # 4. 全局汇总：存入根基类的 metadata（全量表集合）
        DeclarativeBase.metadata.tables[table_name] = table_info
        return model_cls

实操代码：

python 复制代码

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from sqlalchemy import DateTime, String, func
from datetime import datetime

# 自定义全局基类（所有模型都继承此类）
class Base(DeclarativeBase):
    # 公共字段：创建时间（数据插入时自动赋值）
    create_time: Mapped[datetime] = mapped_column(
        DateTime, insert_default=func.now(), comment="创建时间"
    )
    # 公共字段：更新时间（数据修改时自动刷新）
    update_time: Mapped[datetime] = mapped_column(
        DateTime, insert_default=func.now(), onupdate=func.now(), comment="更新时间"
    )

# 业务模型：用户表（自动继承Base的公共字段）
class User(Base):
    __tablename__ = "user"  # 绑定数据库表名
    
    id: Mapped[int] = mapped_column(primary_key=True, comment="用户ID")
    username: Mapped[str] = mapped_column(String(255), comment="用户名")
    password: Mapped[str] = mapped_column(String(255), comment="密码")

3.2.3 异步会话 AsyncSession

是什么：

会话（Session）是 ORM 执行数据库 CRUD、事务管理的载体对象，相当于数据库的「操作上下文」。

用来干什么：

执行查询、新增、更新、删除等数据库操作；
管理事务：正常执行自动提交，异常自动回滚；
绑定异步引擎，复用连接池中的数据库连接。

底层规则：

通过 async_sessionmaker 创建会话工厂，统一生成会话实例；结合 FastAPI 依赖注入，管控会话「创建→使用→提交 / 回滚→关闭」的完整生命周期。

实操代码（会话工厂 + 依赖注入）：

python 复制代码

from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession

# 1. 创建异步会话工厂
AsyncSessionLocal = async_sessionmaker(
    bind=async_engine,        # 绑定异步引擎
    class_=AsyncSession,      # 指定异步会话类型
    expire_on_commit=False    # 事务提交后对象不失效，避免重复查询
)

# 2. 封装为依赖项，供路由统一调用
async def get_db() -> AsyncSession:
    async with AsyncSessionLocal() as session:
        try:
            yield session       # 将会话注入路由函数
            await session.commit()  # 无异常：提交事务
        except Exception:
            await session.rollback()# 异常：事务回滚
            raise
        finally:
            await session.close()   # 强制关闭会话，释放连接

3.3 数据表初始化（项目启动自动建表）

用途：

项目启动时自动根据模型类创建数据表，无需手动执行 SQL 建表语句。

原理：

异步引擎无法直接执行同步建表逻辑，需要通过 conn.run_sync() 包装同步方法，配合 FastAPI 启动事件执行。

代码实现：

python 复制代码

# 建表函数
async def create_tables():
	 # async with 异步上下文管理器，调用.aenter()赋值给conn
	 # async_engine.begin() 先获取连接，再开启事务
    async with async_engine.begin() as conn:
        # 执行同步建表逻辑
        await conn.run_sync(Base.metadata.create_all)

# 应用启动事件：服务运行时自动建表
@app.on_event("startup")
async def startup():
    await create_tables()

3.4 ORM 标准 CRUD 实操

基于上述三大组件，完成数据库常规增删改查，所有接口通过 Depends(get_db) 注入数据库会话。

3.4.1 通用查询规则

构造查询语句：select(模型类)；
执行查询：await db.execute(查询语句)；
解析结果：
- scalars().all()：获取全部数据；
- scalar_one_or_none()：获取单条数据；
- scalar()：获取聚合计算结果（计数、求和等）。

3.4.2 各类查询操作

python 复制代码

from sqlalchemy import select, func

# 1. 查询所有用户
@app.get("/user/all")
async def get_all_user(db: AsyncSession = Depends(get_db)):
    stmt = select(User)
    res = await db.execute(stmt)
    return res.scalars().all()

# 2. 主键查询单条数据
@app.get("/user/{user_id}")
async def get_user(user_id: int, db: AsyncSession = Depends(get_db)):
    user = await db.get(User, user_id)
    return user

# 3. 条件查询（等值、模糊、逻辑、包含）
@app.get("/user/filter")
async def filter_user(db: AsyncSession = Depends(get_db)):
    # 模糊查询：用户名以"张"开头
    stmt = select(User).where(User.username.like("张%"))
    # 逻辑与：ID>1 且 用户名=张三
    # stmt = select(User).where((User.id > 1) & (User.username == "张三"))
    # 包含查询：ID在[1,2,3]中
    # stmt = select(User).where(User.id.in_([1,2,3]))
    res = await db.execute(stmt)
    return res.scalars().all()

# 4. 聚合查询（统计总数）
@app.get("/user/count")
async def user_count(db: AsyncSession = Depends(get_db)):
    stmt = select(func.count(User.id))
    res = await db.execute(stmt)
    return {"total": res.scalar()}

# 5. 分页查询（公式：offset = (页码-1) * 每页条数）
@app.get("/user/page")
async def page_user(page: int = 1, page_size: int = 3, db: AsyncSession = Depends(get_db)):
    skip = (page - 1) * page_size
    stmt = select(User).offset(skip).limit(page_size)
    res = await db.execute(stmt)
    return res.scalars().all()

3.4.3 新增数据

流程：实例化模型对象 → db.add() → 事务提交

python 复制代码

@app.post("/user/add")
async def add_user(username: str, password: str, db: AsyncSession = Depends(get_db)):
    new_user = User(username=username, password=password)
    db.add(new_user)
    await db.commit()
    return {"msg": "新增成功"}

3.4.4 更新数据

流程：查询对象 → 重新赋值字段 → 事务提交

python 复制代码

@app.put("/user/update/{user_id}")
async def update_user(user_id: int, new_name: str, db: AsyncSession = Depends(get_db)):
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(404, "用户不存在")
    user.username = new_name
    await db.commit()
    return {"msg": "更新成功"}

3.4.5 删除数据

流程：查询对象 → db.delete() → 事务提交

python 复制代码

@app.delete("/user/del/{user_id}")
async def del_user(user_id: int, db: AsyncSession = Depends(get_db)):
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(404, "用户不存在")
    await db.delete(user)
    await db.commit()
    return {"msg": "删除成功"}

四、FastAPI + 异步 SQLAlchemy 整体整合架构

4.1 全链路请求流转

客户端请求 → Uvicorn（ASGI 服务）→ FastAPI 路由分发 → 中间件（全局逻辑）→ 依赖注入（分页 / 数据库会话）→ 路由函数 → 异步 SQLAlchemy（会话 + 引擎 + 连接池）→ 数据库 → 逐层回流响应至客户端。

4.2 整合核心要点

数据库会话 AsyncSession 必须通过依赖注入管理，保证每个请求独立会话、连接正常释放；
项目启动事件执行自动建表，保证模型与数据表结构一致；
数据库操作必须捕获异常，确保事务回滚，避免数据脏写；
中间件处理全局逻辑，依赖注入处理局部复用逻辑，二者配合解耦代码。