在使用 FastAPI 进行后端开发时，许多开发者容易陷入“代码逻辑正确但运行报错”的困境。作为 Codex 中文指南，我们聚焦于那些常被忽视的底层机制与配置陷阱，帮助你在早期阶段避开这些深坑。
误解一：忽略依赖注入的生命周期
FastAPI 的核心优势在于其依赖注入系统，但这也是故障高发区。许多开发者误以为所有依赖都是无状态的，从而在数据库连接或外部 API 客户端的管理上出现疏漏。例如，未正确关闭异步连接池会导致资源泄漏，进而引发服务不可用。务必确保在依赖项中使用 yield 语句来管理生命周期，并在测试环境中模拟这些依赖，以避免在生产环境触发异常。
误解二：混淆 Pydantic 验证与业务逻辑
另一个常见误区是将 Pydantic 的模型验证视为万能的安全屏障。虽然 Pydantic 能高效处理数据序列化与校验，但它并不负责复杂的业务规则验证。如果将核心业务逻辑直接嵌入到 Pydantic 模型中，不仅会导致代码耦合度极高，还会使得错误追踪变得极其困难。正确的做法是保持模型简洁，仅在视图层调用专门的 Service 类来处理复杂逻辑，并确保在出错时返回明确的 HTTP 状态码而非默认的 500 错误。
误解三：异步编程中的阻塞操作
FastAPI 基于 Starlette 构建，天然支持异步编程。然而，如果在异步路由函数中调用了同步阻塞库（如传统的 requests 库），将会阻塞整个事件循环，导致其他请求响应延迟甚至超时。开发者应始终使用 httpx 等异步 HTTP 客户端，并避免在异步上下文中执行 CPU 密集型任务。通过监控应用的性能指标，可以及时发现并解决此类隐蔽的性能瓶颈。