底层机制与设计权衡

把"底层机制"讲清楚的标准只有一个：能说出被放弃的备选方案，并解释代价落在哪里。下面五个机制，每一个都配一张备选方案对比表——表里被放弃的两三行，正是这个设计存在的理由。读完任何一节，工程师都应能回答"换成另一种做法会怎样"。

3.1类型注解 → 四个产物

一份函数签名被读一次，同时驱动校验、类型转换、OpenAPI 文档和编辑器补全。

运行方式

程序导入时，@app.get(...) 装饰器（这是 01 章定义的 path operation decorator，路径操作装饰器）就调用 inspect.signature() 读出处理函数每个参数的注解与默认值。来源按三条规则推断——这三条是 FastAPI 的核心约定：

• 参数名出现在路径模板的 {} 里 → 路径参数（path parameter）；
• 注解是一个 Pydantic 模型（用类型注解声明数据形状的类）→ 请求体（request body）；
• 注解是普通标量（int、str、bool 等）且名字不在路径里 → 查询参数（query parameter）。

用 Path() / Query() / Body() 标注可以显式覆盖默认推断。规则定下来源后，同一个注解被分发给四个去处：Pydantic 校验器（值合法吗）、类型转换（URL 里的 "5" 转成 int 的 5）、OpenAPI schema 生成器（写进 /openapi.json）、以及静态类型检查器与编辑器。没有第二份 schema 文件——签名本身就是规约。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):       # 一个 Pydantic 模型
    name: str
    price: float

@app.put("/items/{item_id}")
def update_item(item_id: int, q: str | None = None, item: Item = None):
    # item_id —— 名字在路径 {item_id} 里      → 路径参数
    # q       —— 普通标量、名字不在路径里      → 查询参数
    # item    —— 注解是 Pydantic 模型          → 请求体
    return {"item_id": item_id, "q": q, "item": item}

这条推断链的全貌见下图：一个注解进去，四个产物出来。

3.2Pydantic v2 在定义时编译进 Rust

模型类一被定义，字段就被编译成 Rust 校验器并缓存；每次请求只是一次 Rust 调用，没有逐字段的 Python 循环。

运行方式

class Item(BaseModel) 这行触发 Pydantic 的元类（metaclass，控制类如何被创建的类）。元类里的 GenerateSchema 遍历每个字段的注解，产出一份 core schema——一个带 type 键的嵌套 dict（例如 {'type': 'model', 'fields': {...}}），存在类属性 __pydantic_core_schema__ 上。这份 dict 随即交给 Rust 写的 pydantic-core，编译成两个分开的本地对象：

• SchemaValidator——一棵校验器树，缓存为 __pydantic_validator__，负责 validate_python() / validate_json()（输入 → 模型实例）；
• SchemaSerializer——序列化器，缓存为 __pydantic_serializer__，负责 to_python() / to_json()（模型实例 → 可发送的数据）。

校验与序列化是两个不同的编译产物，方向相反、独立编译。这解释了 01 章 response_model 的行为：请求进来走 SchemaValidator，响应出去走 SchemaSerializer，是两段独立的本地代码，不是同一个对象正反跑。运行时每次请求只调用一次编译好的校验器，把整批数据交给 Rust，没有 Python 层的逐字段 for 循环。

from pydantic import BaseModel

class Item(BaseModel):       # ← 类定义这一刻：元类触发，编译已发生
    name: str
    price: float

# 编译产物在类定义后立刻就存在，无需先校验一次：
print(type(Item.__pydantic_validator__))   # SchemaValidator
print(type(Item.__pydantic_serializer__))  # SchemaSerializer
print(Item.__pydantic_core_schema__["type"])  # 'model'

# 每次校验只是一次 Rust 调用，不是 Python 逐字段循环：
obj = Item.model_validate({"name": "pen", "price": 2.5})
print(obj.model_dump())  # {'name': 'pen', 'price': 2.5}

注：示例输出基于 Pydantic 2.12.4；SchemaValidator / SchemaSerializer 是 pydantic_core 暴露的类型名，跨小版本稳定。

3.3依赖注入图：解析、缓存、清理

Depends 存的是未调用的函数；框架递归读签名连成一张图，请求时深度优先解析，yield 依赖按 LIFO 逆序清理。

运行方式

Depends(get_db) 存进去的是未被调用的函数对象 get_db 本身（注意没有那对括号）。框架对它做递归签名自省：get_db 的参数若也是 Depends(...)，就继续往下读，直到所有依赖连成一张有向图。请求到来时，框架对这张图做深度优先遍历（DFS）——先解析子依赖，再解析父依赖，因为父依赖的执行需要子依赖的结果作为入参。

两个机制决定行为细节：

• 每请求缓存：默认 use_cache=True，每个唯一可调用对象在一次请求内只执行一次，结果存进请求级的字典。同一个 get_db 出现在五个子依赖里，也只调用一次、五处共享同一结果。传 use_cache=False 才强制每次重跑。
• yield 依赖的清理：用 yield 而非 return 的依赖，被当作（异步）上下文管理器压入一个 AsyncExitStack（一个能按栈序统一关闭多个上下文的对象）。yield 之前是 setup、yield 出的值被注入处理函数、yield 之后的清理代码在栈展开时按 LIFO（后进先出）逆序执行。默认清理发生在响应已经发出之后。

LIFO 顺序不是细节：它保证父依赖的清理代码运行时，它依赖的子资源还没被关。下图把一张三层依赖图的解析顺序与清理顺序并排画出。

from typing import Annotated
from fastapi import Depends, FastAPI

app = FastAPI()

def get_db():
    db = open_connection()   # yield 之前：setup
    try:
        yield db             # yield 出的值被注入处理函数
    finally:
        db.close()           # yield 之后：清理，默认在响应发出后跑

@app.get("/items")
def list_items(db: Annotated[Connection, Depends(get_db)]):
    return db.query("select * from items")
    # 函数返回后，响应先发给客户端，然后才执行上面的 db.close()

3.4async 并发模型（第二个反直觉转折）

事件循环单线程：async def 直接跑在循环上，普通 def 被框架丢进线程池——所以在 def 里写阻塞调用反而更安全。

运行方式

事件循环（event loop，一个在单线程里轮流推进多个协程的调度器）是整个 ASGI 栈的心脏。两类路由进入它的方式完全不同：

• async def 路由直接跑在事件循环这一个线程上。函数里每个 await 是一个让出点（yield point）：协程在此暂停、把线程交回循环，循环趁机去服务别的连接，等这个 await 的 I/O 就绪再回来续跑。
• 普通 def 路由被框架自动包成 await run_in_threadpool(fn)，丢进 AnyIO 的工作线程池（默认 40 个线程）。它在另一个线程里跑，不占用事件循环那个线程。

"阻塞循环"的确切含义：在 async def 里执行 CPU 密集计算或同步 I/O（time.sleep()、同步数据库驱动）且中途没有 await。因为整个事件循环就一个线程，这段不让出的代码一旦占住它，循环无法切去服务任何其它连接——所有并发请求一起卡住，不只是当前这个。

import time
from fastapi import FastAPI

app = FastAPI()

@app.get("/sync-blocking")
def sync_blocking():
    time.sleep(10)        # 阻塞——但被丢进线程池，只卡住一个工作线程
    return {"ok": True}   # 其它请求照常被事件循环服务

@app.get("/async-blocking")
async def async_blocking():
    time.sleep(10)        # 灾难：在事件循环线程上同步阻塞、没有 await
    return {"ok": True}   # 这 10 秒内，整个服务的所有连接都冻住

@app.get("/async-correct")
async def async_correct():
    import asyncio
    await asyncio.sleep(10)  # 正确：await 让出，循环可服务别的连接
    return {"ok": True}

3.5设计权衡与生态定位

WSGI 与 ASGI 是 Python web 生态的根本分水岭；FastAPI 的真正优势是 I/O 等待下的并发，不是裸速度。

运行方式：两条协议血脉

02 章讲过 ASGI 协议把应用定义成一个 async 可调用对象，靠 receive/send 收发消息，所以 send 能调用多次——这是流式输出和 WebSocket 的根基。它的前身 WSGI 是一次同步调用、一进一出，无法在一条连接上多次收发，也无法在空闲时让出。这条协议差异把整个生态切成两半：

• WSGI 一侧：Flask、传统同步 Django。成熟、生态厚、同步编程模型直观，但天生不擅长长连接与高并发 I/O。
• ASGI 一侧：FastAPI、Starlette、Litestar、现代异步 Django。原生支持 async、流式、WebSocket。

下面这棵决策树把"何时选谁"压成四个问题。它直接对应 04 章的判别题。

何时不要用 FastAPI

• CPU 密集型负载：GIL 让 async 帮不上忙，放进 async def 还会阻塞循环（见 3.4）。该用进程池或任务队列，框架选择无关紧要。
• 重服务端渲染 HTML：要返回大量模板渲染的页面而非 JSON，Django 或 Flask + 模板引擎是更顺的主场，FastAPI 的类型/校验优势用不上。
• 需要开箱的 admin 后台 / 成熟 ORM：Django 的 admin 和 ORM 是几乎无可替代的生产力来源；FastAPI 不自带这些，要自己拼装。

3.6跨机制综合：一个请求如何同时用上四者

前五节把机制拆开看。真实的一个请求会在几毫秒内同时用上类型系统、Pydantic 内核、依赖图和并发模型。把它们串成一条时间线，机制之间的接缝才显出来。

设想一个 async def 处理函数：它声明了一个 item: Item 请求体、一个 user: Annotated[User, Depends(get_current_user)] 依赖，而 get_current_user 又依赖 get_db（一个 yield 依赖）。一次 POST /items 进来：

1. 导入时（早已发生）：inspect.signature() 读出这个函数的签名（3.1），把 item 定位成请求体、user 认成依赖；同时 Item 类定义触发元类，SchemaValidator 已编译进 Rust 并缓存（3.2）；get_current_user→get_db 的依赖图也已连好（3.3）。这些都不在请求路径上发生。
2. 依赖解析：请求到来，框架对依赖图做 DFS——先解析子依赖 get_db（运行到它的 yield，连接被压入 AsyncExitStack），再用其结果解析 get_current_user（3.3）。
3. 请求体校验：框架把 JSON body 喂给 Item 那个编译好的 SchemaValidator——一次 Rust 调用（3.2）；不合法就在处理函数执行之前返回 422（3.1 的推断决定了"哪些字段必填"）。
4. 函数执行：因为是 async def，处理函数直接跑在事件循环线程上；函数体里每个 await（比如 await 数据库）都让出，循环趁机服务别的连接（3.4）。若这里误用同步阻塞调用，整个循环会冻住。
5. 响应序列化：返回值过 response_model 对应的 SchemaSerializer——另一个 Rust 产物，方向与校验相反（3.2），多余字段被过滤掉。
6. 清理：响应发出之后，AsyncExitStack 按 LIFO 展开，get_db 的 yield 之后那段关闭连接（3.3）。

四个机制不是四个独立特性，而是同一份类型注解在请求生命周期不同阶段被反复使用的结果：Item 这一个注解，在第 3 步被校验、第 5 步被序列化；Depends 声明的图在第 2 步解析、第 6 步清理。这正是 index 那句"类型签名就是规约"在机制层的全貌——也接上了 02 章 请求生命周期 7 阶段的同一条链。