FastAPI、Uvicorn、Pydantic

FastAPI、Uvicorn、Pydantic

📚 概述

这三个库是现代 Python Web 服务开发的核心组件，它们协同工作：

• Pydantic：数据验证和序列化

• FastAPI：高性能 Web 框架

• Uvicorn：ASGI 服务器

  客户端请求 → Uvicorn(服务器) → FastAPI(路由框架) → Pydantic(数据验证) → 业务逻辑 → 响应

  graph LR
  客户端请求 --> Uvicorn(ASGI服务器)
  Uvicorn --> FastAPI(路由分发/处理)
  FastAPI --> Pydantic(数据验证/序列化)
  Pydantic --> FastAPI(返回验证后的数据)
  FastAPI --> Uvicorn(返回响应)
  Uvicorn --> 客户端

---

1️⃣ Pydantic - 数据验证和序列化库

Pydantic 是一个 Python 数据验证库，使用类型提示（Type Hints）进行数据校验和转换。它确保数据符合预期的类型和格式。

核心特性

特性	说明
类型检查	在运行时验证数据类型
自动转换	自动将数据转换为正确类型
验证	支持自定义验证规则
序列化	将模型转为字典或 JSON
反序列化	将字典/JSON 转为模型对象

使用场景

1. API 请求数据验证
2. 配置文件验证
3. 数据库 ORM 模型
4. 环境变量解析

代码示例

from pydantic import BaseModel, Field, validator
from typing import Optional
from datetime import datetime

# 定义数据模型
class SKUPredictionRequest(BaseModel):
    """SKU 预测请求模型"""
    sku: str = Field(..., min_length=1, description="SKU 编码")
    days: int = Field(default=7, ge=1, le=365, description="预测天数")
    file_path: Optional[str] = None
    
    class Config:
        schema_extra = {
            "example": {
                "sku": "KW908-EU",
                "days": 7,
                "file_path": "data.xlsx"
            }
        }
    
    @validator('sku')
    def validate_sku(cls, v):
        """自定义验证：SKU 不能为空"""
        if not v.strip():
            raise ValueError('SKU 不能为空')
        return v.upper()

class PredictionResponse(BaseModel):
    """预测响应模型"""
    sku: str
    days: int
    predictions: list
    data_source: str
    timestamp: datetime = Field(default_factory=datetime.now)

# 使用示例
try:
    # 验证输入数据
    request = SKUPredictionRequest(sku="kw908-eu", days=10)
    print(request.sku)  # "KW908-EU" (自动转换为大写)
    print(request.model_dump())  # 转为字典
    print(request.model_dump_json())  # 转为 JSON 字符串
except ValueError as e:
    print(f"验证失败: {e}")

工作流程

原始数据(dict/JSON)
    ↓
Pydantic 类型检查
    ↓
字段验证(@validator)
    ↓
类型转换(string → int 等)
    ↓
模型对象(BaseModel 实例)

Pydantic 的优势

✅ 自动类型转换 ：days: int = "7" 自动转为 7

✅ 详细错误提示 ：指出具体哪个字段验证失败

✅ OpenAPI 集成 ：自动生成 API 文档

✅ 性能高效：底层用 Rust 实现（Pydantic v2）

---

2️⃣ FastAPI - 高性能 Web 框架

FastAPI 是一个现代、快速的 Python Web 框架，用于构建 API。它基于 Starlette 框架和 Pydantic，提供自动文档生成、类型检查、异步支持等功能。

核心特性

特性	说明
高性能	基于异步 ASGI，与 Node.js 和 Go 性能相近
自动文档	自动生成 Swagger UI 和 ReDoc 文档
类型提示	利用 Python 类型注解实现自动验证
依赖注入	内置依赖注入系统
异步支持	原生支持 async/await
CORS 支持	跨域资源共享配置简单

使用场景

1. RESTful API 服务
2. 微服务架构
3. 实时数据处理
4. WebSocket 通信
5. GraphQL API

代码示例

from fastapi import FastAPI, File, UploadFile, Form
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
import pandas as pd

# 初始化 FastAPI 应用
app = FastAPI(
    title="SKU销售预测系统",
    description="基于XGBoost的时间序列预测",
    version="1.0.0"
)

# 配置 CORS（跨域）
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# 定义请求/响应模型
class PredictionRequest(BaseModel):
    sku: str
    days: int = 7
    
class PredictionResponse(BaseModel):
    sku: str
    predictions: list
    data_source: str

# 路由定义
@app.get("/")
async def root():
    """根路由"""
    return {"message": "欢迎使用SKU预测系统"}

@app.post("/predict/daily", response_model=PredictionResponse)
async def predict_daily(
    sku: str = Form(...),
    days: int = Form(7),
    file: UploadFile = File(None)
):
    """
    日度预测接口
    - **sku**: SKU编码（必填）
    - **days**: 预测天数（可选，默认7）
    - **file**: 历史数据文件（可选）
    """
    # Pydantic 自动验证输入数据
    if not sku:
        raise ValueError("SKU不能为空")
    
    # 处理文件
    data_source = "database"
    if file:
        df = pd.read_excel(file.file)
        data_source = "file"
    
    # 调用预测模型
    predictions = call_xgboost_model(sku, days, file)
    
    return PredictionResponse(
        sku=sku,
        predictions=predictions,
        data_source=data_source
    )

@app.get("/health")
async def health_check():
    """健康检查"""
    return {"status": "healthy"}

# 异步函数示例
@app.post("/predict/batch")
async def predict_batch(requests: list[PredictionRequest]):
    """批量预测（支持异步处理）"""
    results = []
    for req in requests:
        result = await async_predict(req.sku, req.days)
        results.append(result)
    return {"results": results}

async def async_predict(sku: str, days: int):
    """异步预测函数"""
    # 异步数据库查询、API调用等
    return {"sku": sku, "prediction": "..."}

# 启动应用
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=9999)

FastAPI 工作流程

HTTP 请求
    ↓
FastAPI 路由匹配
    ↓
Pydantic 数据验证
    ↓
执行处理函数(async/sync)
    ↓
Pydantic 响应序列化
    ↓
HTTP 响应(JSON)

自动生成的文档

• Swagger UI : http://localhost:9999/docs
• ReDoc : http://localhost:9999/redoc
• OpenAPI Schema : http://localhost:9999/openapi.json

FastAPI 的优势

✅ 开发速度快 ：代码量少，配置简单

✅ 性能优秀 ：异步处理，高并发

✅ 自动文档 ：零额外工作生成 API 文档

✅ 类型安全 ：静态类型检查

✅ IDE 友好：完美的自动补全支持

---

3️⃣ Uvicorn - ASGI 服务器

Uvicorn 是一个轻量级的 ASGI（Asynchronous Server Gateway Interface）服务器，用于运行 Python 异步 Web 应用。它是 FastAPI 的推荐服务器。

ASGI vs WSGI

特性	WSGI	ASGI
并发模型	同步（每请求一个线程）	异步（事件驱动）
性能	较低	高效
WebSocket	❌ 不支持	✅ 支持
长连接	❌ 不支持	✅ 支持
框架	Flask、Django	FastAPI、Starlette
服务器	Gunicorn、uWSGI	Uvicorn、Daphne

核心特性

特性	说明
异步支持	原生支持 async/await
自动重载	开发模式下代码变化自动重启
多进程	支持 worker 进程池
SSL/TLS	支持 HTTPS
WebSocket	全双工通信

使用场景

1. 开发环境：快速迭代、热重载
2. 生产环境：高并发处理、长连接支持
3. 实时应用：WebSocket 通信
4. 异步任务：后台任务处理

代码示例

import uvicorn
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"Hello": "World"}

# 方式1：直接运行
if __name__ == "__main__":
    uvicorn.run(
        app,
        host="0.0.0.0",      # 监听所有网卡
        port=9999,            # 端口
        workers=4,            # 进程数（生产环境）
        reload=True,          # 热重载（开发环境）
        ssl_keyfile="key.pem",
        ssl_certfile="cert.pem",
        access_log=True,      # 访问日志
        log_level="info"      # 日志级别
    )

# 方式2：命令行运行
# uvicorn api_server:app --host 0.0.0.0 --port 9999 --workers 4

Uvicorn 启动参数详解

# 基础启动
uvicorn api_server:app --host 0.0.0.0 --port 9999

# 开发模式（代码变化自动重启）
uvicorn api_server:app --reload

# 生产模式（多进程）
uvicorn api_server:app --workers 4 --host 0.0.0.0 --port 9999

# 启用 HTTPS
uvicorn api_server:app --ssl-keyfile=key.pem --ssl-certfile=cert.pem

# 指定日志级别
uvicorn api_server:app --log-level debug

# 后台运行（Linux/Mac）
nohup uvicorn api_server:app --host 0.0.0.0 --port 9999 > server.log 2>&1 &

Uvicorn 工作流程

HTTP 请求到达 Uvicorn
    ↓
ASGI 应用调用
    ↓
FastAPI 应用处理
    ↓
生成响应
    ↓
Uvicorn 返回 HTTP 响应

Uvicorn 的优势

✅ 高性能 ：事件驱动，支持高并发

✅ 轻量级 ：依赖少，启动快

✅ 异步优化 ：充分利用现代 CPU

✅ 开发友好 ：热重载功能方便开发

✅ 标准化：遵循 ASGI 规范

---

4️⃣ 三者的协作关系

架构图

┌─────────────────────────────────────────────────────┐
│                   客户端请求                       
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│              Uvicorn 服务器                        
│  (监听 0.0.0.0:9999, 事件驱动, 支持异步)              
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│              FastAPI 框架                        
│  (路由匹配, 依赖注入, 自动文档)                       
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│           Pydantic 数据验证                       
│  (类型检查, 自动转换, 自定义验证)          
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│            业务逻辑处理                          
│  (调用模型, 数据库查询, 计算)                     
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│           Pydantic 响应序列化                       
│  (模型转 JSON)                                     
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│              FastAPI 返回响应                     
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│              Uvicorn 发送 HTTP                     
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│                   客户端接收                        
└─────────────────────────────────────────────────────┘

完整工作流程示例

# 1. 定义数据模型 (Pydantic)
from pydantic import BaseModel

class PredictionRequest(BaseModel):
    sku: str
    days: int = 7

class PredictionResponse(BaseModel):
    sku: str
    predictions: list

# 2. 创建 FastAPI 应用
from fastapi import FastAPI

app = FastAPI()

# 3. 定义路由处理函数
@app.post("/predict/daily", response_model=PredictionResponse)
async def predict_daily(request: PredictionRequest):
    # Pydantic 自动验证并转换输入
    print(f"收到请求: SKU={request.sku}, 天数={request.days}")
    
    # 业务逻辑
    predictions = [100, 105, 110, 115, 120, 125, 130][:request.days]
    
    # Pydantic 自动序列化输出
    return PredictionResponse(
        sku=request.sku,
        predictions=predictions
    )

# 4. 使用 Uvicorn 运行
if __name__ == "__main__":
    import uvicorn
    # Uvicorn 启动服务器，处理 HTTP 请求
    uvicorn.run(app, host="0.0.0.0", port=9999)

# 客户端请求示例:
# curl -X POST "http://localhost:9999/predict/daily" \
#      -H "Content-Type: application/json" \
#      -d '{"sku": "KW908-EU", "days": 5}'

---

总结对照表

工具	主要职责	位置	何时使用
Pydantic	数据验证和序列化	应用层	处理所有输入/输出数据
FastAPI	Web 框架和路由	应用层	定义 API 端点和业务逻辑
Uvicorn	ASGI 服务器	服务器层	启动应用并处理 HTTP 请求

类比理解

现实餐厅类比：
- Uvicorn   = 餐厅大堂（接待客人，处理订单传递）
- FastAPI   = 餐厅管理系统（菜单、订单流程、流程管理）
- Pydantic  = 订单检查系统（检查订单是否完整、数据是否正确）

---

📖 学习资源

• FastAPI 官方文档: https://fastapi.tiangolo.com/
• Pydantic 官方文档: https://docs.pydantic.dev/
• Uvicorn 官方文档: https://www.uvicorn.org/
• ASGI 规范: https://asgi.readthedocs.io/

---