FastAPI 系列

  1. FastAPI 系列：从第一个接口到生产部署（当前篇）

  2. FastAPI 为什么适合做 JSON API

  3. 第一个接口怎么跑起来

  4. 路径、查询和请求体为什么要分开声明

  5. Pydantic 模型怎么当契约

  6. 路由怎么拆

  7. 依赖注入到底省了什么

  8. 数据库会话怎么进接口

  9. 状态码和异常为什么不要裸 raise

  10. 鉴权怎么接到 Depends 上

  11. 中间件、CORS 和后台任务分别解决什么

  12. 测试怎么写才不连真实库

  13. 生产怎么部署

FastAPI 的卖点经常被说成「快」和「自动文档」。真正让它适合 JSON API 的，是三件事叠在一起：ASGI 异步入口、用类型提示当契约、启动时生成 OpenAPI。把这三件事当成口号，后面就会把阻塞库塞进 async def，或者把密码字段漏进响应。

FastAPI 请求进入后同时得到 OpenAPI 与交互文档

这个系列覆盖什么

覆盖一条完整路径：安装并启动、声明参数、用 Pydantic 建模、拆 Router、用 Depends 管生命周期、接 SQLAlchemy、规范化异常、接 JWT、分清中间件和后台任务、用 TestClient 替换依赖、最后按官方建议部署。

默认读者已经会一点 Python。不要求你先会 Flask 或 Django，但需要能读类型提示，例如 str | None 和 Annotated。

和 Flask、Django 差在哪

问题

Flask / Django 常见做法

FastAPI 默认做法

请求校验

自己解析 JSON，或再接 Marshmallow

函数参数上的 Pydantic 模型

接口文档

后补 Swagger 或 drf-spectacular

启动时从类型生成 OpenAPI

并发模型

WSGI 线程 / 进程为主

ASGI，I/O 等待时让出事件循环

管理后台

Django Admin 开箱即用

不自带，需要自己做或接工具

FastAPI 不是「更小的 Django」。它适合以 JSON API 为中心的服务；后台页面、全家桶 ORM、电池式用户系统不是它的默认能力。

本系列不讲什么

  • 不把 FastAPI 当成模板引擎教程。需要 HTML 页面时，官方支持 Jinja2，但本系列不展开。
  • 不讲 GraphQL、gRPC，也不把 WebSocket 做成主线。
  • 不对比所有 ASGI 框架。选型时只要记住：要类型驱动的 OpenAPI，FastAPI 是目前最省事的一条路。

贯穿全系列的三条约束

  1. 契约进类型。 路径、查询、请求体、响应各自声明，不要在函数里东拼西凑 dict。

  2. 副作用进 Depends。 数据库会话、当前用户、配置对象用依赖注入，这样测试才能替换。

  3. 开发命令不等于生产命令。 fastapi dev 有热重载；生产用 fastapi run 或 uvicorn --workers。

常见误区

FastAPI 比 Flask 快，所以业务也会更快

框架基准测的是「空路由能扛多少请求」。一旦路由里有同步数据库驱动或 CPU 重计算，瓶颈就不在框架。

有 /docs 就等于接口设计完成

文档只反映你声明的类型。字段没建模、鉴权没进 OpenAPI、错误响应没登记，文档会看起来完整，实际不可用。

async def 写上就异步了

async def 里调用阻塞库，事件循环会被卡住。后面部署篇会再强调：要么用异步驱动，要么把阻塞调用放到线程池。

小结

把 FastAPI 当成「用类型提示写 JSON API 的 ASGI 框架」，而不是万能 Web 全家桶。下一篇从 ASGI、Pydantic 和 OpenAPI 这三层把原理说清楚，然后再安装运行。

参考资料