FastAPI 与 Uvicorn 性能调优指南

一、FastAPI 应用层优化

1. 异步路由设计

   • 对 I/O 密集型操作（如数据库查询、API 调用）使用 async def：

     @app.get("/data")
     async def fetch_data():
         result = await database.query(...)  # 异步数据库操作
         return result
     

   • CPU 密集型任务需配合线程池：

     from concurrent.futures import ThreadPoolExecutor
     @app.get("/process")
     async def heavy_computation():
         with ThreadPoolExecutor() as pool:
             result = await loop.run_in_executor(pool, cpu_bound_func)
         return result
     

2. 依赖注入优化

   • 避免重复初始化依赖对象，使用 lru_cache：

     from functools import lru_cache
     @lru_cache
     def get_shared_service():
         return ExpensiveService()  # 单例模式初始化
     

3. 响应模型精简

   • 使用 Pydantic 的 response_model_exclude_unset=True 过滤未赋值字段：

     @app.get("/items", response_model=Item, response_model_exclude_unset=True)
     

4. 中间件优化

   • 禁用不需要的中间件（如默认 CORS）
   • Gzip 压缩优先使用 FastAPI 内置方案：

     from fastapi.middleware.gzip import GZipMiddleware
     app.add_middleware(GZipMiddleware, minimum_size=1000)  # 仅压缩>1KB响应
     

二、Uvicorn 服务器调优

1. 工作进程配置

   • 推荐公式：$$ \text{workers} = \min(\text{CPU_cores} \times 2 + 1, \text{内存限制}) $$
   • 启动命令示例：

     uvicorn app:app --workers 8 --limit-concurrency 1000
     

2. 连接管理参数

   参数	建议值	作用
   --timeout-keep-alive	5-15 秒	保持连接存活时间
   --backlog	2048	等待连接队列大小
   --limit-max-requests	10000	进程重启前最大请求数

3. 协议优化

   • 启用 HTTP/2（需安装 httptools）：

     uvicorn app:app --http httptools --http2
     

   • WebSocket 连接限制：

     uvicorn app:app --ws-max-size 16777216  # 16MB 消息限制
     

三、系统级协同优化

1. 异步数据库驱动

   • PostgreSQL: 使用 asyncpg 替代 psycopg2
   • Redis: 使用 aioredis 替代同步客户端

2. 监控与诊断

   • 集成 Prometheus 指标：

     from starlette_exporter import PrometheusMiddleware
     app.add_middleware(PrometheusMiddleware)
     

   • 性能分析工具：

     pip install pyinstrument
     uvicorn --app-dir=src app:app --interface asgi3 --instrumentator pyinstrument
     

3. 部署架构建议

   graph LR
     A[负载均衡] --> B[Uvicorn Worker 1]
     A --> C[Uvicorn Worker 2]
     A --> D[...]
     B --> E[异步任务队列]
     C --> E
     E --> F[Redis/消息中间件]
     F --> G[独立计算节点]
   

关键调优原则：

1. 优先保证应用层异步化
2. 通过压力测试确定最优参数（推荐 Locust 或 k6）
3. 监控指标关注：
   • 请求延迟分布（P95/P99）
   • 每秒请求数（RPS）
   • 内存/CPU 利用率
   • 垃圾回收暂停时间