FastAPI 深潜教程 · 入口

起点：把 FastAPI 当作一台机器来拆

这份教程把 FastAPI 当作一台分层的机器来拆开看——不是教怎么快速跑通一个接口，而是讲清每一层各自做什么、代价在哪、什么时候会失效。一句话定位：给会写 Python、但没碰过 web 框架的工程师，讲清一个 HTTP 请求穿过 FastAPI 时到底发生了什么。

基于版本：FastAPI 0.136.3 / Pydantic v2 / Python 3.10+（最低）。 ·  阅读时间：半天（deep-dive，比官方文档深一层）。 ·  代码验证状态：核心示例已在 FastAPI 0.135.2 / Pydantic 2.12.4 / Python 3.13 本机实测。

▸适合谁

这份教程假设三件事。三条都点头，进度会很顺；任意一条不成立，先补它再回来。

  • 能写并能调试 Python，且认得基本的 async/await 语法（async/await 是 Python 声明协程的关键字；看到 async def 不陌生就够，不要求精通事件循环）。
  • 理解函数、类、类型注解（type hint，写在参数和返回值上的类型声明，如 x: int）这三样是 Python 的日常工具。
  • 想搞懂框架内部怎么运转，而不只是求一个能跑的接口——愿意为"为什么这样设计"多花时间。

▸不适合谁

下面三类读者，别的资源更对路：

  • 想要复制即用模板的人：直接看 FastAPI 官方教程，它按任务切分、给现成片段，上手最快。
  • 没写过 Python 的人：先过一遍 Python 官方教程，尤其是函数、类、类型注解三章，再回来。
  • 只想要 quickstart、跑通就走的人：本教程刻意停在机制层、讲实现与代价，对"五分钟出活"是负担而非帮助。

▸读完之后你能做到什么

读完你能在脑子里追踪一个 HTTP 请求从操作系统 socket 一路到 JSON 响应、穿过 Uvicorn→ASGI→Starlette→FastAPI 每一层时各自发生了什么——这是官方文档按主题切分、从不连起来讲的那条链。

这条链拆开，是五条可验证的能力（每条都能当面讲出来，不是"读过有印象"）：

  • 解释为什么普通 def 路由比 async def 路由更"安全"——前者被框架丢进线程池、阻塞调用不会拖垮服务，后者直接跑在单线程事件循环上。
  • 说清一个类型注解（如 item: Item）如何被框架同时用来做请求校验、响应序列化和生成 OpenAPI 文档——同一份注解，三处复用。
  • 画出一张依赖注入图的解析顺序：子依赖先于父依赖、缓存让同一依赖每请求只跑一次、yield 清理按后进先出（LIFO）逆序展开。
  • 判断一个具体需求该选 FastAPI 还是 Flask / Django / 裸 Starlette，并说出分水岭在哪（WSGI 还是 ASGI、要不要 admin/ORM、是不是 CPU 密集）。
  • 定位请求生命周期里 Pydantic 校验发生在第几阶段——为什么一个字段缺失能在你的函数执行之前就返回 422。

▸一句话本质

一句话本质

在 FastAPI 里，Python 类型注解不是给编辑器看的提示，而是运行时的唯一真相来源。 同一个 item: Item 注解，被框架在启动时读出来，同时生成请求校验、响应序列化、依赖解析和 OpenAPI 文档——你写的类型签名就是规约，没有第二份 schema。其余一切，都是架在 ASGI 协议之上的一层薄封装。

这句话是整份教程的轴。它有一个配套的反直觉转折，留到 03 原理 · async 节展开：并发模型是反的——普通 def 路由被框架自动丢进线程池，所以在里面写阻塞调用是安全的；async def 路由直接跑在单线程事件循环上，在里面写阻塞调用会冻住整个服务。

▸现状速览（截至 2026-06）

现状速览 · 截至 2026-06

核心编程模型（path operation + Pydantic 模型 + Depends）自 ~2019 稳定，可当地基学。正在变：Pydantic v2（Rust 内核 pydantic-core，比 v1 快 5–50×）自 FastAPI 0.100（2023-07） 成为标准；依赖注入的推荐写法已从 x = Depends(f) 改为 x: Annotated[X, Depends(f)]；启停钩子从 @app.on_event 改为 lifespan 上下文管理器（lifespan 是管理应用启动/关闭的上下文管理器）；最低 Python 3.10；LLM token 流式输出现以 SSE（Server-Sent Events，服务端单向推送）为主且已是一等公民。

已被取代：Pydantic v1 写法（.dict()、orm_mode、@validator）在 FastAPI 0.136.x（2026） 已彻底移除；@app.on_event；= Depends() 默认值写法（仍可用但不再是文档默认）；Python ≤3.9。最新版 FastAPI 0.136.3（2026-05），仍是 0.x（0.x 是版本号习惯，不代表不成熟）。

▸流畅感警告

流畅感警告

深潜教程最容易骗过自己的地方，是把"熟悉"误当成"学会"。读到这三句心里话时，停一下：

「我读得很顺」——顺，往往只是因为术语眼熟。读懂句子和能在脑子里跑一遍机制，是两件事。

「我做题很快」——快，多半是命中了套路题型。把同一个机制换个场景再问，速度才说明问题。

「我没卡壳」——没卡壳，常常意味着还没碰到真正的机制层。卡住是信号，说明摸到了文档没讲透的那一层。

对治办法贯穿全程：每章末的 self-check 先合上教程作答，预测题先停十秒再展开，最后在 04 自测亲手把请求生命周期画一遍。

▸概念地图

这张图是后面每个细节的挂钩。两件事先看明白：竖向那条地基链是分层封装关系（下面一层被上面一层封装），不是调用顺序；右侧四个产物全部派生自同一份类型注解。

Uvicorn ASGI Starlette FastAPI 本教程主角 驱动 实现 继承 类型注解 item: Item 启动时读出 请求校验 响应序列化 OpenAPI 文档 Depends 依赖解析 派生四产物 async / def 调度 事件循环 · 线程池 调度
图 0.1FastAPI = 一份类型注解派生四产物 + 一条分层地基链。注意：路由 / 请求对象 / 线程池其实都在 Starlette 层，FastAPI 真正新增的只有"读注解→派生四产物"这一层封装。

▸学习路径建议

这是概念向教程，四章按依赖顺序写。按目标挑一条路径，不必每次都从头啃：

▸目录

开始阅读 → 01 概念

▸学完之后

这四章建立的是 FastAPI 的核心机制模型。往实战走，下面五个方向每个都在这套 schema 上加一块新拼图：

  • 异步数据库栈（SQLAlchemy 2.0 async + asyncpg）——补上"async def 路由里怎么不阻塞地查库"，对应 03 章 async 节没展开的 I/O 部分。
  • 生产部署（Uvicorn/Gunicorn workers、容器化）——补上"单进程事件循环之外，怎么用多进程吃满多核"，对应地基链最底下 Uvicorn 那一层。
  • 认证与安全（OAuth2 + JWT）——补上"Depends 怎么承载鉴权"，把依赖注入从取资源扩展到查权限。
  • SSE / WebSocket 流式输出（给 LLM / agent 后端）——补上"ASGI 的 send 可多次调用怎么变成流式响应"，对应 02 章 ASGI 节的核心机制。
  • 测试（TestClient / httpx）——补上"不起真实服务器怎么跑完整请求生命周期",把 7 阶段流程变成可断言的测试。