FastAPI核心原理：从类型注解到请求处理全流程解析

1. 先拆掉那层“自动”的滤镜：从一个最小接口说起

我第一次跑通 FastAPI 的最小示例时，盯着浏览器里的 /docs 页面愣了好几秒：明明只写了一个函数和几个类型注解，怎么就有了整套可以交互调试的接口文档？传一个类型不对的参数进去，还能自动返回 422 而不是直接报错？这种感觉既爽又有点不踏实，因为你不清楚背后到底发生了什么。

其实 FastAPI 的核心原理和架构，恰恰就是围绕“如何在运行时把类型注解变成真实的约束与说明书”展开的。把这个拆明白，你就不只是会用它写接口，而是能诊断性能问题、写出复杂的依赖关系、定制异常处理，甚至能跟团队解释清楚这个框架为什么这么做设计。这篇文章不打算再讲怎么安装、怎么写第一个 hello world，而是从源码和运行机制层面，把请求从 TCP 进入、经过层层处理、再到 JSON 响应返回的完整过程拆开看一遍。适合已经写过一段时间 FastAPI、现在开始追求“知其所以然”的开发者。

1.1 一个最小接口里，有三件事没写但确实发生了

from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class Item(BaseModel): name: str price: float @app.post("/items") def create_item(item: Item) -> dict: return {"name": item.name, "price": item.price}

就这么十几行代码，运行之后至少有三件“看不见”的事情同步发生了：

第一，POST 一个错误的 body，比如把 price 传成字符串，接口会自动返回 422，并且附带非常详细的字段级错误信息。第二，访问 /openapi.json，会得到当前服务的完整 OpenAPI 描述，你一个字注释都没写，但它确实生成了。第三，访问 /docs 和 /redoc，会得到两套可交互的接口文档页面。

这三件事没有一行显式代码去实现，那 FastAPI 是怎么做到的？答案藏在 Python 的运行时自省能力里：在装饰器执行的那一刻，框架会读取函数签名，把每个参数按规则分类，再决定后续怎么解析、怎么校验、怎么生成文档。理解了这个入口，后面所有“自动”都会变成可预测的行为。

1.2 为什么值得把原理追到底

很多人停在“会用”的层面：定义模型、写依赖、加中间件，用起来确实顺手。但一旦遇到下面这些场景，知识缺口就暴露了：接口偶发变慢，你分不清是事件循环被阻塞还是线程池在排队；一个依赖函数被重复执行了，你却找不到缓存开关；自定义异常处理器不生效，因为中间件顺序跟你想的完全相反；路由里一个固定路径被动态路径抢了先，请求落到了错误的分支上。

这些都不是“查文档能背下来”的知识，而是需要理解框架的调用链之后才能判断的问题。所以我这篇文章的核心思路是：先把框架的分层结构和请求处理流程搭建出来，再回到每个环节里讲清原理。读完以后你再遇到 FastAPI 相关的怪问题，至少知道该去哪一层找原因。

2. 类型注解是怎么变成校验、请求体定义和 OpenAPI 文档的

2.1 路由注册时，FastAPI 到底干了多少活

当你写 @app.post("/items") 时，FastAPI 不是简单地把函数存进路由表里，它走的是 APIRoute 初始化流程。在这个过程中，关键一步是拿到函数的签名信息，然后对每个参数做一轮“分类”。Python 的 inspect.signature 能取出每个参数的名称、默认值和注解，FastAPI 在这个基础上结合路径模板、参数类型、特殊标记类，最终判断一个参数应该归到哪一类。

这个分类规则是整个框架的基石，我把它整理成一张表：

参数特征	FastAPI 的默认归类	典型写法
参数名出现在路径模板中	Path 参数	/items/{item_id}
不在路径里、类型是 Python 基础类型	Query 参数	limit: int = 10
注解是 Pydantic 模型类	Body 参数	item: Item
注解带 Header / Cookie 等标记类	请求头 / Cookie 参数	user_agent: str | None = Header(None)
注解是 Depends(...)	依赖项	commons: dict = Depends(common_params)

理解了这张表，你就能回答一个高频疑问：“为什么我不写 Query() 或 Body()，FastAPI 也知道该从哪里取数据？”因为分类不是靠你显式标注，而是靠路径位置、参数类型和默认值组合推断出来的。当然你也可以在参数里显式写 Query(max_length=10)、Body(embed=True)，用来覆盖默认推断或者附加约束。

有一个细节特别提醒：这个环节依赖类型注解能被正确解析。如果你用了 fromfutureimport annotations 让注解变成字符串，FastAPI 会通过 typing 的解析机制去还原，这时如果某个类型在模块导入路径里不可达，启动阶段就会直接报错。我在协助排查一个老项目升级时就碰到过这个坑：某个函数把自定义类型写成了字符串注解，而那个类型在代码里拼写有误，结果整个服务在路由注册阶段就崩了，根本没有等到请求进来。

提示：路由装饰器不仅仅是注册动作，它还会完成参数分类、依赖收集、响应模型准备。这也是为什么很多参数类型的问题会在启动时暴露，而不是等到请求时才暴露。

2.2 Pydantic 模型：校验发生在你的业务代码之前

当一个带 body 的请求到达，FastAPI 的调用链会先按已经分类好的 Body 参数类型，把接收到的字节流解析成 Python 字典，再交给 Pydantic 模型去校验。校验通过后实例化出模型对象，才轮到你的业务函数执行。

这里有个容易被忽略的分层：字节流解析和参数校验是两步。默认的 JSONDecoder 解析失败会返回 422，但错误信息只包含 “JSON decode error” 一类内容；Pydantic 校验失败也会返回 422，但是错误结构是字段级别的，会明确告诉你哪个字段哪个规则没通过。我见过不少人在排查 422 时只看外层 detail，忽略这两类错误的结构差异，结果顺着一个模棱两可的信息查了很久才发现问题根本不在字段取值上。

Pydantic v2 的校验核心是 pydantic-core，用 Rust 实现，速度相对之前版本提升非常明显。对绝大多数接口来说，模型校验的开销远小于业务逻辑本身。但要注意：如果你的模型里有复杂的 validator，比如需要查数据库确认某个值是否存在，那校验就不再是纯 CPU 运算，而是可能阻塞事件循环的环节。这种重逻辑不应该放在模型 validator 里，更好的做法是放到依赖或者服务层，用依赖注入的机制去完成。

2.3 响应模型不是文档装饰，它是响应契约

response_model 参数是另一处很容易被误解的地方。很多人觉得它只是为了让文档好看一点，实际上 FastAPI 拿到 response_model 后会走一遍过滤和序列化流程：你 return 的数据会被转换成模型允许的字段结构，模型里没定义的字段会被丢掉，类型对不上的地方会被修正或者报错。

这意味着 response_model 能帮你守住接口对调用方的承诺。比如从数据库查出来的 ORM 对象往往带着内部字段，像密码哈希、内部标记之类的东西。如果 response_model 只暴露外层需要的字段，那这些多余字段在响应阶段就会被自动过滤掉。这比你在业务代码里手动逐个 select 字段更省心，也避免了“某天加了一个字段忘了过滤”导致的信息泄露。

当然，它也有成本：每次响应都要做模型层面的校验和序列化，在极端高并发场景下会带来额外的 CPU 开销。如果你确认数据完全可信，又追求极致吞吐，可以跳过 response_model，直接返回 dict 或 JSONResponse。我个人的习惯是默认保留 response_model，因为带来的契约价值大于那一点开销，尤其在接口数量多、团队协作频繁的项目里，响应结构的稳定比微小的性能提升重要得多。

2.4 OpenAPI 文档的生成链路

文档不是“另写一份”的，它是一个树状推导过程：FastAPI 收集所有路由、HTTP 方法、路径参数、查询参数、请求模型、响应模型，然后让每个 Pydantic 模型生成对应的 JSON Schema，最后汇总成符合 OpenAPI 3.x 规范的字典，挂到 /openapi.json 上。

Pydantic 模型天然支持生成 JSON Schema，嵌套模型、枚举、字段约束（比如 Field(min_length=3)）都会被表达成 Schema 的一部分。Swagger UI 和 ReDoc 只是读取这个 JSON 去渲染页面。所以只要你改模型定义，文档立即跟着变，这是 FastAPI 在团队协作里最让我舒服的地方：接口文档不会因为忘记维护而过时。

还有个实操建议：如果你想让人对接起来更顺畅，一定给字段加描述和示例，例如 Field(description="商品名称", examples=["苹果"])。OpenAPI 的展示效果会有质的差别。对内部小工具类接口可能无所谓，但面向合作方或客户的 API，这些描述直接决定对接效率。这一步框架不会自动帮你做，属于团队约定层面的东西。

3. 三层架构拆解：Uvicorn、Starlette 与 FastAPI 各守哪条边界

3.1 一句话分清三者的关系

FastAPI 不是从零写出来的 Web 框架，它是三层结构的最上面一层，下面两层分别是 Uvicorn 和 Starlette。很多人以为安装了 fastapi 就自带服务器，其实还要单独装 uvicorn 才能跑起来，这就是原因所在。

Uvicorn 是 ASGI 服务器，负责把 HTTP/1.1、WebSocket 这类协议层的字节流，解析成 ASGI 规范里的 scope 字典，同时管理连接生命周期。Starlette 是 ASGI 框架，提供路由、中间件、请求与响应对象、模板、静态文件、后台任务这些 Web 基础设施。FastAPI 则是在 Starlette 之上叠加了一层语义：自动参数解析、Pydantic 校验、依赖注入、OpenAPI 文档生成。

打个比方：Uvicorn 是快递站的分拣员，只关心包裹怎么进怎么出；Starlette 是办公楼里的走廊和房间号规则，告诉你哪个房间在哪、邮件怎么转发；FastAPI 是前台接待员，帮你校验预约凭证、填好访客单，最后把你带到大楼里真正要找的人面前。

3.2 Uvicorn：协议层与应用层之间的翻译官

Uvicorn 不属于你的应用逻辑，它只做“协议翻译”。收到一个 HTTP 请求后，它解析请求行、请求头和请求体，组装出 scope 字典，包括 method、path、query_string、headers 等信息，然后按照 ASGI 规范调用你的应用对象。你的应用对外暴露的只是一个约定：scope 代表请求上下文，receive 用来收消息，send 用来发消息。

Uvicorn 支持不同的 HTTP 解析器，默认情况下使用 httptools，它的解析速度比纯 Python 实现的 h11 快不少，你也可以通过配置切换。这部分对绝大多数业务开发者是透明的，但如果你要优化边缘场景，比如处理超大请求体、调整 keep-alive 超时时间，就需要到 Uvicorn 配置层做文章，而不是在 FastAPI 层改来改去。

我遇到过一个实际案例：某个服务在公网环境下偶尔出现连接被重置的错误，业务方在 FastAPI 代码里排查了很久，最后定位到是 Uvicorn 的 keep-alive 超时和负载均衡空闲超时配置不匹配，连接被中途断开导致。这说明排错时脑子里一定要有“请求链路分层”的地图，知道每一层管什么，就不会把问题全推给业务代码。

3.3 Starlette：低调但无处不在的骨架

打开 FastAPI 源码你会发现，FastAPI 类本身继承了 Starlette 的相关类，路由对象本质上是 Starlette 的 Router，中间件、异常处理器、生命周期管理等机制全部来自 Starlette。FastAPI 做的核心工作是“增强”：

• 把请求处理函数包装成带参数解析能力的 APIRoute；
• 把参数解析、校验、依赖注入、响应模型处理嵌入到路由处理流程中；
• 在启动时收集元数据，生成 OpenAPI schema。

也就是说，当你把 FastAPI() 实例化出来时，你实际上得到了一个被加强过的 Starlette 应用。理解这层继承关系能省去很多困惑：比如你在 Starlette 文档里看到的中间件用法，基本可以直接套到 FastAPI 上，因为底层就是同一套机制。

3.4 FastAPI 加的那层“语义化”价值在哪

既然 Starlette 已经能写 Web 接口了，为什么还要再叠一层 FastAPI？答案是开发体验的语义化。用 Starlette 写接口，你需要自己从 Request 对象里取参数、自己做校验、自己拼错误响应，非常繁琐。FastAPI 把这些重复劳动收敛为声明式描述：你不写参数解析代码，而是写类型注解和 Pydantic 模型；不手动拼错误 JSON，而是通过注册异常处理器统一输出。

好处是，接口的输入输出契约集中到了类型系统里，团队代码的可读性和可维护性都上了一个台阶。缺点是多了一层间接调用，读代码时你可能要跳好几层才能看到完整逻辑。这个权衡我认为是值得的，尤其是当接口数量上百之后，声明式的维护成本远低于手写解析和校验的维护成本。

4. 依赖注入系统：从函数签名到一棵依赖树再到参数组装

4.1 get_dependant：把函数签名变成一棵依赖树

FastAPI 的依赖注入核心在 fastapi/dependencies/utils.py 这个模块里。其中 get_dependant 负责扫描一个函数，无论是端点函数还是依赖函数本身，把它的参数再分类一次：哪些是路径、查询、请求头、正文参数，哪些是子依赖。返回的 Dependant 对象里保存着子依赖列表、请求参数定义和待调用的函数。

到了真正请求进来的时候，solve_dependencies 会递归遍历这棵依赖树。它先处理显式子依赖，再处理当前层级的参数校验，最后把结果合并成一个参数字典，交给 get_route_handler 去调用你的端点函数。这个过程不是平铺直叙的，而是有先后的：依赖的执行优先级、参数取值的顺序、校验失败的时机，都会影响你最终看到的行为。

4.2 嵌套依赖与同名依赖的缓存问题

依赖之间可以互相依赖，这是 FastAPI 非常强大的地方：

def verify_token(authorization: str = Header(...)): # 校验逻辑 return token_data def get_current_user(token_data: dict = Depends(verify_token)): # 根据 token_data 获取用户 return user

FastAPI 默认开启 use_cache 缓存机制，在同一个请求内，同一个依赖可调用对象只会执行一次。这个设计避免了重复校验的开销，但也带来一个容易看懵的现象：两个独立端点都依赖同一个函数时，每次请求各自会执行一次；但一个端点内两个不同参数如果都写着 Depends(same_func)，这个函数只会执行一次。

注意：这个缓存默认是开启的。当你确实需要每次都重新执行时，必须显式写 use_cache=False。比如依赖函数返回一个每次都该不同的随机跟踪 ID，或者内部依赖了会变化的全局状态，这时默认缓存就可能产生不符合预期的结果。

我对这个坑印象很深：有次排查问题，发现一个依赖函数返回“当前请求的随机跟踪 ID”，但它被端点里的两个参数同时引用，结果两个参数拿到的却是同一个 ID。当时所有人都以为代码逻辑有问题，查了很久才发现是缓存机制在起作用。

4.3 yield 依赖与资源清理的时机

FastAPI 支持用 yield 的依赖来管理资源生命周期：

def get_db(): conn = create_connection() try: yield conn finally: conn.close()

请求开始时，FastAPI 会进入这个生成器，拿到 yield 出来的连接；请求结束后，无论端点是否抛异常，生成器都会恢复执行到 finally，确保资源被清理。它的实现基于 contextlib 的 ExitStack，所以当依赖嵌套多层时，清理顺序会保持正确的逆序，先创建的依赖后清理。

这里有两个常见错误。一是把关闭操作写在 try 之外，一旦端点抛异常，连接就直接泄漏。二是把收尾代码写在 yield 之后、finally 之前，以为它每次都会执行。实际上 yield 之后的代码只有在请求真正结束时才会恢复执行，如果生成器被提前关闭，这段代码不一定按你预期的方式跑。生产环境里，资源释放代码统一放到 finally 是最稳的写法，这个习惯值得从第一天就养成。

5. 路由匹配、中间件栈与异常传播：请求进入应用后的执行链

5.1 路由注册与路径匹配的底层逻辑

FastAPI 的路由表本质上是一个有序列表，Starlette 的 Router 按顺序逐个尝试匹配。每个路由对象内部会把路径模板编译成正则表达式，支持 {item_id}、{user_id:int}、{path:path} 这类路径参数转换器。匹配成功后，路径参数会被提取出来，作为端点函数里的 Path 参数传入。

因为匹配是有序的、第一个命中就停止，路由声明顺序就变得很重要。比如 /items/{item_id} 和 /items/me 这两个路由都注册时，如果前者在前，那么访问 /items/me 会被当成 item_id="me" 处理，从而进入错误的逻辑分支。FastAPI 的文档里提醒过“固定路径要放在动态路径之前”，但在真实项目里这个错误依然很常见。给路由排序时，把固定路径或更具体的表达式放在前面是最稳妥的做法。

5.2 中间件栈的顺序：洋葱模型的实际意义

中间件在 Starlette 中的实现方式就是“包装”：每个中间件把应用再包一层，形成一个洋葱结构。请求从最外层进入，逐层向内，到达路由处理后，响应再逐层向外返回。这里的顺序规则很多人记反，我明确说一下：

• 最先 add_middleware 添加的中间件，处于更外层；
• 后 add_middleware 添加的中间件，处于更内层，更接近业务逻辑。

所以如果你要加一个“全局登录校验”中间件，希望它在其他中间件之前执行，你应该最先添加它。反之，如果你希望某个日志中间件能看到最终的响应头，它应该放在相对外层。这个顺序问题排查起来非常隐蔽，因为每个中间件单独看都正常工作，只是组合顺序导致你观察到的数据不符合直觉。

使用 BaseHTTPMiddleware 写中间件时还有一个常见坑：在中间件里读取了请求体，例如 await request.body() 或 request.json()，然后没有重置流，导致下游端点读到的 body 是空的。正确做法是读取后把流重新构造回去，或者把解析结果缓存在请求状态里，让下游直接用。

5.3 异常处理器的注册与全局兜底

Starlette 的中间件栈里，最外层放的是 ServerErrorMiddleware，负责 500 兜底；靠近路由的位置放的是 ExceptionMiddleware。FastAPI 会把 HTTPException、RequestValidationError 等注册为默认异常处理器，输出统一格式的 JSON。

自定义异常处理器时用 @app.exception_handler(MyException)，这个注册是挂在 ExceptionMiddleware 上的。因为中间件栈的顺序，你的处理器能拦截到路由里抛出的异常，但拦截不到更外层 ServerErrorMiddleware 覆盖的某些场景。也就是说，有些极端情况下，比如异常发生在 ExceptionMiddleware 包裹范围之外，你的自定义处理器可能不会触发。这正是“为什么我的处理器没生效”的常见原因之一，排查时要记得看异常发生的位置，而不是只盯着处理器代码有没有写对。

6. def 还是 async def：事件循环面前的两种执行路径

6.1 FastAPI 对“普通函数”的特殊照顾

FastAPI 里，端点函数用 def 和 async def 声明，执行方式完全不同：

• async def：函数直接被事件循环调度执行，和你手写的 asyncio 协程一样；
• def（普通函数）：FastAPI 会把它丢到线程池中执行，执行完再把结果交回事件循环。

这个设计非常关键。它保证了即使你写了一个比较耗时的同步函数，也不会直接阻塞事件循环，因为它在线程池里跑。但别忘了线程池是有限资源，如果大量并发请求都在执行长时间同步阻塞操作，线程池会排队，请求照样变慢，只是“卡的方式”不同。我用一张表总结：

声明方式	执行位置	适合场景	典型反例
async def	事件循环	I/O 非阻塞操作、异步客户端	内部调用 time.sleep 或同步 requests
def	线程池	同步阻塞操作、较轻的 CPU 任务	高并发下大量长耗时同步任务

6.2 线程池与事件循环：阻塞代码的“隐形调度”

这个机制不只作用于端点函数，也作用于依赖函数。依赖里写 def 一样会被丢到线程池。这意味着，哪怕你非常注意端点函数全部用 async def，还是可能在依赖函数里引入阻塞调用，从而影响整体并发表现。

我碰过一个真实案例：某个接口线上偶尔超时，QPS 不高但延迟波动明显。定位后发现依赖函数里有一段同步的 Redis 客户端调用，而那个依赖被声明成 def。按道理它在线程池里不会阻塞事件循环，但它被多个端点共享，请求并发上来后，线程池里的等待时间开始叠加，最终表现为整体响应时间上升。优化思路不是简单把它改成 async，而是换用异步客户端，从根上减少线程池占用。

提醒：上下文变量会被传递到线程池中，但线程内对上下文变量的修改不会自动同步回事件循环。如果你的代码依赖请求级别的上下文传递，比如用 contextvars 存了请求 ID，在线程里的读写行为可能会和预期不同，需要额外注意。

6.3 常见性能陷阱与诊断方法

我来列举几个实际工作中最容易踩的性能陷阱，以及我的诊断思路：

第一，async def 端点里写 time.sleep。这是最典型的事件循环杀手。一个接口睡一秒，整个进程在这一秒里都没法处理其他请求。正确做法是改用 asyncio.sleep。

第二，async def 端点里调用同步 HTTP 客户端。requests 库的阻塞 socket 会卡住事件循环。需要换成 httpx.AsyncClient 或者 aiohttp 这类异步客户端。

第三，纯 CPU 密集的大计算任务。即使放在线程池，大量并发也会把线程池占满。针对这种工作，应该引入多进程方案，而不是指望线程池。

诊断方法方面，先用负载测试观察延迟分布，再结合日志或者在关键路径上加时间戳。更细致一点，可以对运行中的进程做栈采样，看看事件循环当前正卡在哪个协程里。这些工具层面的手段，配合对执行模型的理解，才能快速定位“阻塞到底发生在哪一层”。

7. 一次请求的完整生命线：从 TCP 报文到 JSON 响应

7.1 时间线拆解：谁在什么时候干了什么

我把一次普通 POST /items 请求的完整调用链整理成一张表，方便对照代码里看到的每个环节：

顺序	环节	负责方	说明
1	接收 TCP 连接、解析 HTTP 报文	Uvicorn	生成 scope 和 receive/send 接口
2	进入 ASGI 应用	Uvicorn 转交应用	依次穿过中间件栈
3	路由匹配	Starlette Router	找到对应的 APIRoute
4	解析参数与依赖	FastAPI solve_dependencies	读取 body、校验 path/query/header、执行依赖树
5	执行业务函数	你的代码	事件循环或线程池中运行
6	响应过滤与序列化	FastAPI	response_model 过滤、jsonable_encoder 转换
7	发送 HTTP 响应	ASGI send	逐层返回中间件栈，Uvicorn 写出报文

这个表格看起来简单，但每一步背后都有细节。第四步尤其值得关注：它不是“读一下 body”就完了，而是先确定参数分类，再按依赖树的顺序逐层执行。路径参数、查询参数、请求头参数的校验都在依赖之后，一旦校验失败，请求直接返回 422，根本不会进入你的业务代码。

7.2 响应序列化的细节与响应类型选择

FastAPI 默认会把响应数据经过 jsonable_encoder 转成 JSON 可序列化的 Python 结构，再交给 JSONResponse 输出。如果你返回的是字符串，会被 JSON 编码成带引号的字符串；如果你返回的是 Response 子类对象，比如 StreamingResponse、RedirectResponse，FastAPI 会把它直接作为最终响应发送，不经过数据转换。

这也提醒我们：想要精细控制响应类型，比如流式下载、文件返回、HTML 渲染，最好直接返回 Starlette 的 Response 子类，而不是返回一个对象让 FastAPI 帮你猜。在实际项目里，下载型接口我经常用 StreamingResponse，它支持异步迭代器，适合大文件流式传输，避免把整个文件读进内存。理解了这个“返回值到网络报文的转换链”，你就知道什么时候该用哪种响应类型。

8. 源码阅读路线与几个容易买错的“直觉结论”

8.1 想读源码，从哪里开始最省力

我的建议是按“问题驱动”来读，不要试图从 main 函数一路啃到底。先聚焦你最常疑惑的几个点：

• fastapi/routing.py 里的 get_route_handler：看端点函数是如何被包装的，这是理解整个请求流程的总开关；
• fastapi/dependencies/utils.py 里的 get_dependant 和 solve_dependencies：依赖解析的完整脉络都在这里；
• fastapi/applications.py 里的 add_api_route：看路由注册时收集了哪些元数据。

Starlette 那边主要看 routing.py 和 middleware 目录，把 Router 的匹配机制和中间件栈结构搞清楚，再回头看 FastAPI 就轻松多了。Pydantic 的源码可以晚点再看，先用好它的功能层面，需要深入时再研究它的 Schema 生成和校验流程。

8.2 几个和直觉相反但很重要的结论

这些年我踩过、也带人排查过不少问题，总结出几个反直觉的结论，非常值得记住：

第一，并不是所有代码都写成 async def 就更快。如果你的业务本身就是同步阻塞逻辑，强行 async 反而会卡住事件循环，写成 def 让线程池去扛反而稳定。

第二，Depends 的默认缓存是“同一请求内同一依赖只执行一次”，而不是“每个参数各执行一次”。依赖函数里的状态共享行为要格外小心。

第三，Pydantic 模型的字段顺序会影响生成的 JSON Schema 顺序，进而影响文档展示顺序。模型字段排序看起来是小事，但对文档可读性影响很大，尤其是大模型。

第四，中间件的添加顺序决定了嵌套顺序，嵌套顺序又决定了请求前后处理的先后。加中间件之前，最好先把顺序图画一遍。

第五，异常处理器并不能捕获所有异常。ServerErrorMiddleware 在更外层，它自己的处理分支不在你自定义处理器的范围内。

8.3 几个实际踩过、也希望大家避开的坑

第一，不要在 async def 端点里用同步文件读取，或者做大的内存分配。这类操作虽然不是网络阻塞，但同样会长时间占用事件循环，影响同进程其他协程的调度。

第二，数据库会话的关闭一定要放在 finally。使用 yield 依赖时，在 finally 里释放连接最稳。有人习惯在 yield 之后直接写关闭逻辑，一旦端点在依赖恢复执行前抛出异常，清理代码可能根本没机会运行。

第三，中间件里读 body 要想到“下游还要读”。读一次 request.body() 之后如果不重置，下游拿到的就是空 body。要么提前消费并把重置后的流放回去，要么在中间件里把解析结果缓存下来，传递一个标记给下游使用。

第四，给异常处理器写返回内容时，要确保返回的是 Response 或者能被 FastAPI 序列化的对象。如果你直接返回一个普通字典，可能不会经过你预期的那条序列化路径，造成响应格式不符合接口约定。

说回我自己的感受，FastAPI 最值得学习的地方不在于它让你少写了多少样板代码，而在于它把 Python 的类型系统和 Web 框架的能力结合得足够紧密。理解这套核心原理之后，你再去看它的源码、去排查线上问题、去设计团队的接口规范，都会有完全不同的视角。对于一个长期维护的项目来说，这种认知带来的收益远大于记住几个 API 用法。