FastAPI 模式

异步陷阱

• 在异步端点中混用同步数据库驱动（如 psycopg2、PyMySQL）会阻塞事件循环 —— 应改用异步驱动（如 asyncpg、aiomysql），或通过 run_in_executor 运行同步代码
• 在异步端点中使用 time.sleep() 会导致整个事件循环阻塞 —— 应改用 await asyncio.sleep()
• 在异步端点中执行 CPU 密集型任务会挤占其他请求的资源 —— 应将其卸载至 ProcessPoolExecutor 或后台工作进程
• 异步端点调用执行 I/O 的同步函数时仍会阻塞 —— 整个调用链必须全部为异步

Pydantic 校验

• 模型中的默认值（如 items: list = []）会成为跨请求共享的可变状态 —— 应使用 Field(default_factory=list)
• Optional[str] 并不会使字段在请求中变为可选 —— 需显式指定 = None，或使用 Field(default=None)
• Pydantic v2 使用 model_validate() 替代已弃用的 parse_obj()，使用 model_dump() 替代已弃用的 .dict()
• 使用 Annotated[str, Field(min_length=1)] 定义可复用的校验类型，避免重复声明约束条件

依赖注入

• 依赖项默认在每次请求时运行 —— 对开销较大的依赖可使用 lru_cache 缓存，或将其缓存在 app.state 中作为单例
• Depends() 若不传入参数，则自动复用类型提示作为依赖项 —— 写法简洁但可能令读者困惑
• 嵌套依赖构成有向无环图（DAG）—— 若 A 依赖 B 和 C，而 B 与 C 均依赖 D，则 D 仅执行一次（按请求缓存）
• 对需清理资源的依赖（如数据库会话、文件句柄）使用 yield 依赖 —— yield 后的代码无论端点是否抛出异常均会执行

生命周期（Lifespan）与启动逻辑

• @app.on_event("startup") 已被弃用 —— 应改用 lifespan 异步上下文管理器
• 应在生命周期内将共享资源（如数据库连接池、HTTP 客户端）存入 app.state，而非使用全局变量
• 生命周期逻辑每个 worker 进程仅执行一次 —— 若使用 4 个 Uvicorn worker，则会创建 4 个独立的数据库连接池

from contextlib import asynccontextmanager
@asynccontextmanager
async def lifespan(app):
    app.state.db = await create_pool()
    yield
    await app.state.db.close()
app = FastAPI(lifespan=lifespan)

请求与响应

• 端点应返回 dict，而非直接返回 Pydantic 模型 —— FastAPI 自动处理序列化，且性能更优
• 对于返回新建资源的 POST 端点，应设置 status_code=201 —— 默认的 200 状态码语义上不准确
• 返回非 JSON 响应时，应使用 Response 并指定 media_type="text/plain" —— 否则直接返回字符串仍会被 JSON 编码
• 设置 response_model_exclude_unset=True 可从响应中排除值为 None 的字段 —— 输出更清晰简洁

错误处理

• 应使用 raise HTTPException(status_code=404) 抛出错误 —— 不应返回 Response 对象，否则将绕过中间件
• 可通过 @app.exception_handler(CustomError) 注册自定义异常处理器 —— 但注意其无法捕获 HTTPException
• 使用 detail= 参数提供面向用户的提示信息，并单独记录原始错误日志 —— 切勿向客户端泄露堆栈跟踪

后台任务

• BackgroundTasks 在响应发送后执行，但仍处于同一进程内 —— 不适用于长时间运行的任务
• 后台任务按添加顺序串行执行 —— 不应假定其具备并行性
• 若后台任务失败，客户端无法感知 —— 应自行实现错误处理与告警机制

安全性

• OAuth2PasswordBearer 仅用于 OpenAPI 文档生成 —— 它本身不校验令牌，实际校验逻辑需在依赖项中实现
• CORS 中间件在中间件注册顺序中必须置于异常处理器之后 —— 否则错误响应将缺失 CORS 头
• Depends(get_current_user) 应应用于路径操作（path operation），而非路由器（router）—— 路由器级依赖会影响所有子路径（包括健康检查接口）

测试

• TestClient 即使对异步端点也以同步方式运行 —— 如需真正异步测试，应使用 httpx.AsyncClient 配合 ASGITransport
• 可通过 app.dependency_overrides[get_db] = mock_db 覆盖依赖项 —— 比 monkeypatch 更清晰可靠
• TestClient 必须配合上下文管理器使用（即 with TestClient(app) as client:），否则生命周期钩子（startup/shutdown）不会触发