FastAPI 核心技术与实战

一、FastAPI 简介

什么是 FastAPI？
FastAPI 是一个现代、高性能、极简、易用的 Python Web 框架，专门用来快速构建 API 服务。它基于 Python 最新特性开发，被称为Python 最快的 Web 框架之一，性能直逼 NodeJS 和 Go。
FastAPI 核心特点
超快速度：性能接近 Go / Node
自动生成文档：自带 Swagger 和 ReDoc 交互式文档
强类型校验：利用 Python 类型提示自动校验数据
支持异步：可写 async/await 异步接口
开箱即用：极少代码就能完成生产级 API
适用场景
机器学习模型部署（YOLO、Transformer、预测接口）
微服务与后台 API
数据接口、数据分析平台
高并发 IO 密集型服务
快速上线的小型项目

二、FastAPI 核心优势

性能极高
基于 Starlette（异步 Web 框架）+ Pydantic（数据校验）速度排名：FastAPI ≈ Starlette > Flask > Django
开发效率翻倍
不用写接口文档
不用写参数校验
自动处理 JSON 转换
自动生成可调试的在线接口页面
类型安全，减少 BUG
通过类型提示自动校验：
字符串、数字、枚举
日期、路径、邮箱
复杂嵌套结构
错误请求会直接返回清晰的错误信息，不会崩溃。

三、FastAPI 安装与基础使用

安装命令

bash 复制代码

pip install fastapi uvicorn
fastapi：框架本体
uvicorn：异步运行服务器

最简单 API 示例（main.py）

python 复制代码

from fastapi import FastAPI
创建应用
app = FastAPI()

定义路由（首页）

@app.get("/")
def home():
    return {"message": "Hello FastAPI!"}

启动服务

bash 复制代码

uvicorn main:app --reload

打开自动文档
Swagger UI（调试用）：http://127.0.0.1:8000/docs
ReDoc（美观文档）：http://127.0.0.1:8000/redoc
✅ 不用写文档，框架自动生成

四、路由与请求处理

路径参数

python 复制代码

@app.get("/user/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

查询参数

python 复制代码

@app.get("/item")
def get_item(name: str, price: float = 0):
    return {"name": name, "price": price}

请求体（最重要）
使用 Pydantic 模型自动校验：

python 复制代码

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    desc: str | None = None

@app.post("/add_item")
def add_item(item: Item):
    return {"item": item}

文件上传

python 复制代码

from fastapi import File, UploadFile

@app.post("/upload")
def upload(file: UploadFile = File(...)):
    return {"filename": file.filename}

五、响应模型与数据验证

定义响应模型

python 复制代码

class ItemResponse(BaseModel):
    name: str
    price: float

@app.get("/item/{id}", response_model=ItemResponse)
def get_item(id: int):
    return {"name": "苹果", "price": 5.0}

自定义状态码

python 复制代码

from fastapi import status

@app.post("/create", status_code=status.HTTP_201_CREATED)
def create():
    return {"msg": "创建成功"}

错误处理

python 复制代码

from fastapi import HTTPException

@app.get("/error")
def test_error():
    raise HTTPException(status_code=404, detail="未找到数据")

六、依赖注入系统（FastAPI 灵魂功能）

什么是依赖注入？
把公共逻辑（验证、数据库、登录）写成可复用函数，路由直接调用，不用重复写代码。
最简单依赖

python 复制代码

def common_params(name: str):
    return {"name": name}

@app.get("/test")
def test(data: dict = Depends(common_params)):
    return data

常用场景
登录校验（JWT）
数据库连接
权限判断
请求日志记录
优势：代码干净、易维护、易测试

七、异步支持（高性能关键）

异步路由

python 复制代码

@app.get("/async")
async def async_api():
    return {"msg": "异步接口"}

异步数据库

python 复制代码

异步 ORM：Tortoise / SQLAlchemy 2.0

async def get_data():
    # 异步查询数据库
    return data

什么时候用异步？
IO 密集型（查询数据库、请求第三方接口）
高并发场景
机器学习模型部署
异步能让服务支持更多并发、更快响应。

八、中间件与高级功能

自定义中间件（记录请求时间）

python 复制代码

from fastapi import Request

@app.middleware("http")
async def log_time(request: Request, call_next):
    response = await call_next(request)
    print("请求路径:", request.url.path)
    return response

跨域配置（CORS）

python 复制代码

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

后台任务

python 复制代码

from fastapi import BackgroundTasks

def write_log():
    print("后台执行任务")

@app.get("/bg")
def bg_task(background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log)
    return {"msg": "后台运行中"}

WebSocket 支持

python 复制代码

from fastapi import WebSocket

@app.websocket("/ws")
async def websocket(ws: WebSocket):
    await ws.accept()
    await ws.send_text("连接成功")

九、测试与部署

测试用例（Pytest）

python 复制代码

from fastapi.testclient import TestClient

client = TestClient(app)

def test_home():
    res = client.get("/")
    assert res.status_code == 200

生产环境运行

bash 复制代码

gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

Docker 部署（最常用）

bash 复制代码

FROM python:3.11
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
CMD ["uvicorn", "main:app", "--host", "0.0.0.0"]

十、FastAPI 生态与扩展

FastAPI Users：用户登录、注册、JWT 认证

FastAPI Cache：接口缓存

SQLAlchemy / Tortoise：数据库 ORM

Beanie：MongoDB 异步 ORM

Celery：异步任务队列

十一、实际案例（最实用）

案例 1：CRUD 接口（增删改查）

python 复制代码

省略模型定义

@app.get("/items")
def get_items(): ...

@app.post("/items")
def create_item(): ...

@app.put("/items/{id}")
def update_item(): ...

@app.delete("/items/{id}")
def delete_item(): ...

案例 2：JWT 登录认证

生成 token、校验 token、权限控制

案例 3：机器学习模型部署（YOLO / 预测接口）

python 复制代码

@app.post("/predict")
def predict(img: UploadFile):
    result = model.predict(img)
    return result

✅ 这是目前工业界最常用的部署方式

十二、FastAPI vs 其他框架

FastAPI vs Flask
FastAPI：更快、自动文档、异步、类型校验
Flask：更轻量、生态老、适合简单项目
结论：新项目优先 FastAPI
FastAPI vs Django
Django：大而全、适合后台管理系统
FastAPI：极简、高性能、适合 API 服务
结论：微服务用 FastAPI

十三、未来发展趋势

云原生、Docker、K8s 首选框架

机器学习部署标配

异步生态越来越完善

逐渐成为 Python Web 主流框架