📦 实战评估：Project Toolkit/后端框架/FastAPI

FastAPI 架构设计

FastAPI 是基于 Starlette + Pydantic 的现代 Python Web 框架，用类型提示驱动自动验证、序列化和文档生成，async-first 设计使其成为 Python 生态中性能最高的 API 框架。

🏗️ 整体架构

┌─────────────────────────────────────────────────────────┐
│                     Client Request                       │
│                   (HTTP / WebSocket)                      │
└──────────────────────────┬──────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────┐
│                  ASGI Server (Uvicorn)                    │
│              异步事件循环 (asyncio / uvloop)                │
└──────────────────────────┬──────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────┐
│                    FastAPI (核心层)                        │
│                                                          │
│  ┌─────────────────────────────────────────────────────┐ │
│  │               Starlette (Web 基础层)                 │ │
│  │  ┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│  │  │ Router │ │ Middleware│ │ Request  │ │ Response │ │ │
│  │  │ 路由   │ │ 中间件    │ │ 请求     │ │ 响应     │ │ │
│  │  └────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│  │  ┌──────────┐ ┌──────────┐ ┌────────────────────┐  │ │
│  │  │ WebSocket│ │ Background│ │ StaticFiles        │  │ │
│  │  │          │ │ Tasks    │ │ Templates(Jinja2)  │  │ │
│  │  └──────────┘ └──────────┘ └────────────────────┘  │ │
│  └─────────────────────────────────────────────────────┘ │
│                                                          │
│  ┌─────────────────────────────────────────────────────┐ │
│  │               FastAPI 扩展层                         │ │
│  │  ┌──────────────┐ ┌────────────┐ ┌───────────────┐ │ │
│  │  │ Dependency   │ │ Security   │ │ APIRouter     │ │ │
│  │  │ Injection    │ │ OAuth2/JWT │ │ 路由分组      │ │ │
│  │  │ 依赖注入      │ │ 安全       │ │               │ │ │
│  │  └──────────────┘ └────────────┘ └───────────────┘ │ │
│  │  ┌──────────────┐ ┌────────────┐ ┌───────────────┐ │ │
│  │  │ OpenAPI      │ │ CORS       │ │ Exception     │ │ │
│  │  │ 自动生成文档   │ │ 跨域       │ │ Handler       │ │ │
│  │  └──────────────┘ └────────────┘ └───────────────┘ │ │
│  └─────────────────────────────────────────────────────┘ │
│                                                          │
│  ┌─────────────────────────────────────────────────────┐ │
│  │               Pydantic (数据层)                      │ │
│  │  ┌──────────────┐ ┌────────────┐ ┌───────────────┐ │ │
│  │  │ BaseModel    │ │ Validators │ │ Serialization │ │ │
│  │  │ 数据模型      │ │ 验证器      │ │ 序列化        │ │ │
│  │  └──────────────┘ └────────────┘ └───────────────┘ │ │
│  └─────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

🔑 核心设计思想

1. 类型提示驱动一切

FastAPI 的核心创新是利用 Python 原生类型提示（Type Hints）同时实现：

• 请求验证：自动校验路径参数、查询参数、请求体
• 序列化：自动将 Python 对象转为 JSON
• 文档生成：自动从类型信息生成 OpenAPI/Swagger 文档
• IDE 支持：自动补全、类型检查

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = False

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    # item_id: int → 路径参数自动转 int，非数字返回 422
    # item: Item → 请求体自动用 Pydantic 验证，不合法返回 422
    return {"item_name": item.name, "item_id": item_id}

设计哲学：一个类型声明，三重收益（验证 + 序列化 + 文档）。这不是魔法，是对 Python 类型系统的深度利用。

2. ASGI 异步原生

FastAPI 基于 ASGI（Asynchronous Server Gateway Interface），原生支持 async/await：

传统 WSGI 框架 (Flask/Django)          ASGI 框架 (FastAPI)
┌─────────────────────┐              ┌─────────────────────┐
│  请求1 → 处理 → 响应  │              │  请求1 ─┐            │
│  请求2 → 等待...     │              │  请求2 ─┼─ 并发处理  │
│  请求3 → 等待...     │              │  请求3 ─┘            │
│  (同步阻塞)          │              │  (异步非阻塞)         │
└─────────────────────┘              └─────────────────────┘

关键点：一个 FastAPI worker 处理 I/O 并发的能力相当于 8-10 个 Django worker。

3. 依赖注入系统

FastAPI 内置了强大的依赖注入（Dependency Injection）系统，是其架构的核心支柱：

# 依赖函数：可以是普通函数或 async 函数
async def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

async def get_current_user(token: str = Depends(oauth2_scheme)):
    user = decode_token(token)
    if not user:
        raise HTTPException(status_code=401)
    return user

# 路由函数声明依赖，FastAPI 自动注入
@app.get("/users/me")
async def read_users_me(
    current_user: User = Depends(get_current_user),
    db: Session = Depends(get_db)
):
    return current_user

依赖注入的用途：

• 数据库连接管理
• 认证和授权
• 配置注入
• 请求参数复用
• 服务层抽象

4. 中间件管道

Request → [CORS] → [GZip] → [认证] → [日志] → Router → Response
                                                    │
Response ← [CORS] ← [GZip] ← [处理] ← [日志] ←───┘

@app.middleware("http")
async def add_process_time_header(request: Request, call_next):
    start_time = time.time()
    response = await call_next(request)
    process_time = time.time() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response

🧩 核心组件

Starlette — Web 基础层

FastAPI 完全构建在 Starlette 之上，继承其所有能力：

Pydantic — 数据验证层

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

class UserCreate(BaseModel):
    username: str = Field(..., min_length=3, max_length=50)
    email: str = Field(..., pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')
    age: int = Field(..., gt=0, le=150)
    created_at: datetime = Field(default_factory=datetime.now)

    @validator('username')
    def username_alphanumeric(cls, v):
        if not v.isalnum():
            raise ValueError('用户名必须是字母数字')
        return v

Pydantic v2 变化（2026 年 FastAPI 最低要求 Pydantic 2.7+）：

• 核心用 Rust 实现，验证速度提升 5-50 倍
• @validator → @field_validator
• Config 类 → model_config

路由系统

from fastapi import APIRouter

# 路由分组
router = APIRouter(
    prefix="/api/v1/users",
    tags=["users"],
    responses={404: {"description": "Not found"}}
)

@router.get("/")
async def list_users():
    ...

@router.get("/{user_id}")
async def get_user(user_id: int):
    ...

# 在主应用中注册
app.include_router(router)

安全系统

from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from fastapi import Depends, HTTPException, status

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

# OAuth2 密码流
@app.post("/token")
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
    user = authenticate_user(form_data.username, form_data.password)
    if not user:
        raise HTTPException(status_code=401)
    access_token = create_access_token(data={"sub": user.username})
    return {"access_token": access_token, "token_type": "bearer"}

# 受保护的路由
@app.get("/protected")
async def protected_route(token: str = Depends(oauth2_scheme)):
    payload = verify_token(token)
    return {"user": payload["sub"]}

📐 请求处理流程

1. 客户端发送 HTTP 请求
       │
2. Uvicorn (ASGI Server) 接收
       │
3. 中间件链处理（CORS、GZip、自定义中间件）
       │
4. 路由匹配（Router 根据 method + path 找到对应函数）
       │
5. 依赖注入解析（Depends() 递归解析所有依赖）
       │
6. 参数验证（Pydantic 验证路径参数、查询参数、请求体）
       │  - 验证失败 → 返回 422 Unprocessable Entity
       │
7. 执行路由函数
       │  - 抛出 HTTPException → 返回对应状态码
       │  - 抛出其他异常 → 返回 500
       │
8. 响应序列化（Pydantic response_model 自动序列化输出）
       │
9. 中间件链反向处理
       │
10. Uvicorn 发送 HTTP 响应

🆚 与 Flask/Django 架构对比

🔗 相关链接

• Python Starlette Pydantic ASGI REST API 微服务
• FastAPI 官方文档
• Starlette 文档
• Pydantic 文档
• TechEmpower Benchmarks

📝 个人备注

（留白，供后续补充学习心得）