分层架构与请求生命周期

一个 FastAPI 应用在内存里不是单一的整体，而是三段代码叠在一起：最底下是 Uvicorn（一个 ASGI 服务器，负责和操作系统的 socket 打交道），中间是 Starlette（路由与请求对象的所有者），最上面是 FastAPI（在每个 path operation 外面加校验和文档的那一层）。三者靠一份叫 ASGI 的协议（asynchronous server gateway interface，异步服务器网关接口）咬合在一起。看懂这三层的分工，才能解释 01 章那句"其余一切都是架在 ASGI 协议之上的一层薄封装"到底薄在哪、厚在哪。

2.1ASGI 协议——底下的契约

ASGI 把一个 web 应用定义成一个 async 可调用对象 async def app(scope, receive, send)，三个参数就是它和服务器之间的全部约定。

三个参数各司其职：scope 是这条连接的元数据 dict——type（"http" 还是 "websocket"）、method、path、headers 都在里面，它在连接建立时就备好、整条连接期间不变。receive 是一个 async 可调用对象，await 它会拉取一个客户端事件 dict（例如请求体分块 {"type": "http.request", "body": b"...", "more_body": False}）。send 也是一个 async 可调用对象，把事件 dict 推送回客户端——先发一个 http.response.start（带状态码和响应头），再发一个或多个 http.response.body。

关键不在三个名字，而在交互形态是消息传递，不是返回值。应用不 return 一个响应；它通过 await send(...) 把响应一块一块推出去。

# 一个最小的 ASGI 应用：不依赖任何框架，纯协议
# 这正是 Uvicorn 期待拿到的可调用对象形状
async def app(scope, receive, send):
    assert scope["type"] == "http"          # scope=连接元数据 dict

    event = await receive()                  # 拉取一个客户端事件
    # event 形如：{"type": "http.request", "body": b"", "more_body": False}

    await send({                             # 推送响应开始：状态 + 头
        "type": "http.response.start",
        "status": 200,
        "headers": [(b"content-type", b"text/plain")],
    })
    await send({                             # 推送响应体（可调用多次）
        "type": "http.response.body",
        "body": b"hello from raw ASGI",
    })

为什么不沿用 WSGI

Python 上一代的同步协议 WSGI（web server gateway interface）把应用定义成 app(environ, start_response) -> iterable：一次同步函数调用，environ 进、一个可迭代的字节响应出。一进一出、调用结束即终结。这个形状无法建模一条连接上多次双向收发事件——WebSocket 的每一帧、SSE（server-sent events，服务器推送事件）的每一条消息，都是连接存活期间陆续到来的；也无法在等待 I/O 时把控制权await 让出去给别的连接。

ASGI 用"receive 可以 await 任意多次、send 可以调用任意多次"换来了这两种能力。send 能被反复调用，正是流式输出和 WebSocket 成立的根基——这一点对要把 LLM token 一段段吐给前端的后端尤其重要（03 章会展开 async 并发的代价）。

2.2Starlette——那个 ASGI 应用本体

Starlette 就是图 2.1 里的那个 async def app(scope, receive, send)；它拥有路由、Request/Response、中间件、WebSocket、线程池，唯独不自带服务器。

具体清单（这些全是 Starlette 的，不是 FastAPI 的，01 章三层封装那节已点过名）：

• 路由表：把 scope["method"] + scope["path"] 匹配到一个 endpoint。01 章说的"装饰器在导入时把函数注册进路由表"，那张表就在这里。
• Request / Response：把原始 scope/receive/send 包成可读对象（request.headers、request.query_params、await request.body()）。
• 中间件栈：在 endpoint 外层裹一圈的 ASGI 应用洋葱（CORS、GZip、会话）。
• WebSocket、BackgroundTasks、lifespan（启停钩子的上下文管理器）、以及 run_in_threadpool——把同步 def 函数丢进工作线程的那个调度原语（03 章并发模型的主角）。

它不自带服务器：Starlette 是被调用的那个 app，需要你另配一个 ASGI 服务器（默认 Uvicorn）去真正监听端口、读写 socket、调用它。

2.3FastAPI 加了什么

FastAPI 继承 Starlette，在每个路由处理函数外面再包一层：签名自省 → Pydantic 校验 → 序列化 → Depends 解析 → 自动 OpenAPI。

机制上，app = FastAPI() 创建的对象是 Starlette 应用的子类。路由匹配、Request 对象、中间件栈、run_in_threadpool 线程池调度——全是继承来的，FastAPI 一行没改。它新增的只有每个 path operation 外面那层 per-endpoint 封装：用 inspect.signature() 读注解 → 按 path/query/body 规则定位参数来源 → 喂给 Pydantic 编译好的校验器 → 跑你的函数 → 用 response_model 的序列化器把返回值转成 JSON → 顺带把这套类型信息汇成 OpenAPI schema。这层封装薄，但承担了 01 章整章的编程模型。

2.4请求生命周期 7 阶段

一个请求从 socket 字节到 JSON 响应，按固定顺序穿过 7 个阶段；其中 Pydantic 校验（阶段④）发生在你的函数（阶段⑤）之前。

前三节是静态分层，这一节是动态流程：同一个请求在这三层里依次经过哪些处理。这是本章的核心，也是 01 章"类型注解即规约"真正发力的地方——同一份注解会在这条链上被读到两次。

逐阶段：每一阶段在哪一层、做了什么

• ① Uvicorn 解析 socket 字节（IMPL 层）：从 TCP 连接读出原始 HTTP 字节，解析成 scope dict，备好 receive/send，然后 await 调用上层那个 ASGI app（即 Starlette/FastAPI）。
• ② Starlette 路由匹配（MID 层）：拿 scope["method"] + scope["path"] 在路由表里查，命中 FastAPI 为这个 path operation 注册的处理器。没命中→404。
• ③ 依赖图解析（CORE 层）：解析这个 endpoint 的 Depends 图——子依赖深度优先（先子后父），按需缓存，yield 型依赖的 setup 段推入一个 AsyncExitStack 待命（解析顺序与缓存的代价详见 03 章 DI 节）。
• ④ 参数解析 + Pydantic 校验（CORE 层，本阶段是关键）：按 01 章的来源规则从 path/query/headers/body 取值，喂给类定义时就编译好的（Rust）校验器。任一字段不合规→框架在这里构造 422 响应直接返回，你的函数根本不会被调用。
• ⑤ 处理函数执行（APP 层）：到这一步入参已是合法、类型正确的 Python 对象。async def 路由直接在事件循环上跑；普通 def 路由被 await run_in_threadpool(fn) 丢进线程池（03 章并发模型展开）。
• ⑥ response_model 序列化（CORE 层）：返回值过一遍 response_model 的（Rust）序列化器——这就是 01 章说的"返回值被再次跑过模型"，能借此过滤掉模型没声明的字段、转成 JSON 可写的形态。
• ⑦ 经 send 发出响应（一路下沉回 IMPL 层）：序列化后的 JSON 通过 send 推出——先 http.response.start（状态+头），再 http.response.body。这正是 2.1 那个裸协议动作。
• 事后：响应发出之后，AsyncExitStack 按 LIFO（后进先出）展开，跑各 yield 依赖 yield 之后的清理段；BackgroundTasks 也在此时执行。

把 01 章的 item: Item 放进这条生命周期走一遍

01 章那个 def create_item(item: Item)——参数注解是 Pydantic 模型 Item，按规则被当成请求体。现在跟着它穿过上面的 7 阶段，看同一份注解如何在两个不同阶段各被用一次：

一份 item: Item，进来时当校验器（阶段④）、出去时当序列化器（阶段⑥），中间在你函数里只是个普通对象。这就是 01 章 threshold 那句"你写的类型签名就是规约，没有第二份 schema"在运行时的具体兑现——没有"输入 schema"和"输出 schema"两份东西在同步，是同一份注解在生命周期的两端各被读了一次。