04.7.15.3 异步执行模型与中间件
所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.7 Python / 04.7.15 FastAPI 框架
覆盖范围
async def与def端点的调度差异、AnyIO 线程池与依赖调度- 阻塞调用拖垮事件循环的机理、症状识别与安全迁移
anyio、uvloop、asyncio.timeout与超时释放- Starlette 中间件执行顺序、
BaseHTTPMiddleware的流式与开销问题、纯 ASGI 中间件写法 HTTPException、exception_handler、RequestValidationError与统一错误响应lifespan替代on_event、资源初始化与释放StreamingResponse、SSE、文件下载与背压- WebSocket 端点、握手鉴权、连接登记与广播
- 请求体大小限制、文件上传策略
asyncio.Semaphore并发限流、取消传播与客户端断开处理
04.7.15.3-001 同一个端点写成 async def 还是 def,执行位置有什么不同?
一句话结论
async def 端点直接在事件循环协程里 await 执行;def(同步)端点被 AnyIO 线程池调度到工作线程里执行,不占用事件循环线程。端点函数签名决定调度路径,二者可以访问同样的请求与依赖,差别只在“跑在协程还是线程”。
概念解释
- FastAPI 基于 Starlette 的
Request/Route体系,调度判断在路由调用端点时完成。 - 异步端点适合 IO 等待(HTTP、数据库异步驱动、消息队列);同步端点适配阻塞库、同步 ORM、CPU 小任务。
原理流程
- 路由处理器解析参数与依赖后,调用
fastapi.routing.run_endpoint_function。 - 函数对象是协程函数(
iscoroutinefunction为真)时直接await,运行在事件循环线程。 - 否则经
starlette.concurrency.run_in_threadpool进入anyio.to_thread.run_sync,由 AnyIO 线程池承载。 - 线程内返回值再交回事件循环做响应模型序列化。
代码或图示
@app.get("/async")
async def async_endpoint():
# 事件循环线程内执行,等待时让出控制权
return await some_async_io()
@app.get("/sync")
def sync_endpoint():
# AnyIO 工作线程内执行,阻塞不卡事件循环
return blocking_query()
常见误区
- 写成
async def并不等于“更快”:里面只要还有阻塞调用,照样卡住事件循环。 - 同步端点之间由线程并发承载,但受线程池容量限制,不是无限并发;线程池耗尽时新请求排队等待。
追问
- 框架怎么判断端点是不是协程函数?答:用
inspect.iscoroutinefunction/asyncio.iscoroutinefunction判断。 - 同步端点返回普通值还是协程?答:返回普通值,由路由层统一收集后序列化。
- 两种端点能混用同一套依赖吗?答:能,依赖自身是同步或异步会走各自的调度路径。
04.7.15.3-002 FastAPI 如何决定端点跑在事件循环还是线程池?
一句话结论
框架按端点(及每个依赖)是否为协程函数分别调度:协程函数 await 执行,普通函数通过线程池执行。判断基于函数本身的 __wrapped__/协程标记,而不是看返回值或参数类型。
概念解释
- 调度逻辑在
fastapi.routing与starlette.concurrency中:端点、路径参数、依赖、安全校验函数各自被独立判定。 - 被装饰器包装的函数要保证协程标记正确透传,否则可能被误判进线程池。
原理流程
- 请求进入路由后,先解析依赖树,逐个收集可调用对象。
- 每个可调用对象经协程判定:是协程函数则直接 await,否则进线程池。
- 端点同样按上述规则执行。
- 所有结果汇总后进入响应模型校验与序列化。
代码或图示
# 判定口径(框架内部等价逻辑)
import inspect
def dispatch(func, *args, **kwargs):
if inspect.iscoroutinefunction(func):
return func(*args, **kwargs) # 事件循环内 await
return run_in_threadpool(func, *args, **kwargs) # 线程池
常见误区
- 以为路由上挂的
def依赖会跟着async def端点一起在协程里跑:实际上同步依赖仍进线程池。 - 以为线程池执行就没有并发上限:所有同步端点与同步依赖共享同一 AnyIO 线程池限额。
追问
- 依赖和端点的调度是独立的吗?答:独立,每个可调用对象分别判定。
- 协程装饰器没透传标记会怎样?答:可能被当成普通函数扔进线程池,
await语义丢失。
04.7.15.3-003 同步 def 端点底层通过什么机制切到线程池?
一句话结论
同步端点由 starlette.concurrency.run_in_threadpool 包装,内部调用 anyio.to_thread.run_sync,把阻塞函数提交到 AnyIO 工作线程,事件循环继续处理其他请求;函数返回后协程被唤醒继续后续流程。
概念解释
anyio.to_thread提供线程原语,并通过默认限流器限制并发线程数。- 线程内拿到的
Request对象不能跨线程长期持有,请求结束后上下文失效。
原理流程
- 路由层发现端点是普通函数,调用
run_in_threadpool。 anyio.to_thread.run_sync从线程池取工作线程执行函数。- 阻塞期间事件循环不被占用,可接受新连接、处理其他协程。
- 函数返回后 anyio 通过事件循环唤醒对应协程,回到路由层做序列化。
代码或图示
from starlette.concurrency import run_in_threadpool
@app.get("/report")
def build_report():
# 阻塞计算在工作线程完成
return expensive_blocking_report()
# 手动把阻塞调用放进线程池(在 async 端点里)
async def caller():
result = await run_in_threadpool(expensive_blocking_report)
return result
常见误区
- 以为线程池是 Python
concurrent.futures.ThreadPoolExecutor直连:FastAPI 走的是 AnyIO 线程原语,限额由 AnyIO 限流器管理。 - 在同步端点里保存
Request引用并在后台线程继续读 body:请求上下文已结束,行为不可靠。
追问
run_in_threadpool与asyncio.to_thread等价吗?答:底层都是线程池提交,FastAPI/Starlette 用 AnyIO 版本以保持跨后端一致。- 线程池里能访问
Request吗?答:能,仅限端点执行期间,跨请求持有会失效。
04.7.15.3-004 AnyIO 默认线程池容量是多少,满了会怎样?
一句话结论
AnyIO 默认线程限流器有总令牌数(默认 40,具体数值以所装 anyio 版本为准,待确认:验证点:anyio.to_thread.current_default_thread_limiter().total_tokens 在本机版本的输出);令牌耗尽后,新的 to_thread 提交会排队等待已释放的线程,表现为同步端点响应变慢、请求堆积,但事件循环本身不被卡死。
概念解释
- 限流器按令牌而非固定线程数工作:线程按需创建,上限由令牌控制。
- 可在启动时调大
total_tokens,但线程数受内存、GIL 与下游连接数约束。
原理流程
- 每次
run_in_threadpool先申请一个令牌。 - 有空闲令牌则创建/复用工作线程执行;无令牌则协程挂起排队。
- 函数结束归还令牌,唤醒排队请求。
- 线程复用由 AnyIO 后端维护。
代码或图示
import anyio.to_thread
limiter = anyio.to_thread.current_default_thread_limiter()
limiter.total_tokens = 100 # 启动阶段、lifespan 中调整
常见误区
- 以为同步端点慢是事件循环阻塞:线程池满时症状是排队等待,CPU 与单请求延迟要看下游耗时。
- 盲目调大令牌数:线程过多会加剧 GIL 竞争与内存占用,下游数据库连接先被打满。
追问
- 怎么查看当前版本默认令牌数?答:调用
current_default_thread_limiter().total_tokens打印确认。 - 线程池满会报错吗?答:默认不抛错,先排队;排队过久会由上游超时或客户端断开兜底。
04.7.15.3-005 线程池里的同步代码与事件循环协程共享哪些上下文?
一句话结论
两者共享 Python 进程内存、全局变量、连接池与应用实例;但 contextvars 上下文会随线程/协程边界传递,请求级状态(当前用户、请求头)应通过参数或依赖显式传入,不能依赖线程局部变量跨边界读取。
概念解释
- 事件循环协程与工作线程属于同一进程,模块级对象、缓存、客户端实例天然共享。
- AnyIO 提交线程时会复制当前上下文变量,线程内可读,但线程内修改不会回写协程侧。
原理流程
- 应用启动时创建的连接池、配置对象挂在进程内存中,各线程/协程共享引用。
- 请求进入时依赖解析产生请求级对象,通过函数参数传入端点。
- 线程执行期间读取复制过来的上下文变量;写操作留在线程内。
- 请求结束,请求级对象随垃圾回收失效。
代码或图示
# 共享:进程级连接池
db_pool = make_sync_pool()
def get_user(user_id: int, db_pool=db_pool):
return db_pool.query(user_id) # 显式传入,不靠线程局部状态
常见误区
- 用全局可变字典在请求间存“当前用户”:多线程并发下互相覆盖。
- 在工作线程里直接修改
contextvars变量后期待协程侧读到:上下文是复制快照,不会回传。
追问
- 进程级连接池为什么可以共享?答:同一进程内线程/协程共用引用,池内部保证自身线程安全。
- 请求级状态该放哪里?答:放依赖注入返回的请求级对象,随参数传递。
04.7.15.3-006 同步端点里能直接 await 吗?同步与异步依赖分别怎么被调度?
一句话结论
不能:def 端点内写 await 是语法错误。同步依赖作为普通函数进线程池执行;异步依赖作为协程在事件循环内 await;混合依赖树中框架会分别调度,最终把结果注入端点参数。
概念解释
- 依赖解析由
fastapi.dependencies.utils完成,每个Depends项独立判定协程性。 - 同步依赖返回的值会被原样传给下游依赖或端点。
原理流程
- 解析依赖树,收集所有依赖可调用对象。
- 协程依赖在事件循环内 await;普通依赖经线程池执行。
- 依赖结果按声明顺序注入,供后续依赖与端点使用。
- 任一依赖抛错即中断链路并进入异常处理。
代码或图示
async def get_current_user(token: str = Depends(oauth2_scheme)):
return await verify_token(token) # 异步依赖:事件循环内
def get_db_session():
session = Session()
try:
yield session
finally:
session.close() # 同步依赖:线程池内
@app.get("/me")
async def me(user: User = Depends(get_current_user), db=Depends(get_db_session)):
...
常见误区
- 以为异步端点里的同步依赖会阻塞事件循环:同步依赖同样进线程池,不在协程线程阻塞。
- 以为依赖必须和端点同签名:不需要,各自独立调度。
追问
- 依赖生成器(
yield依赖)的退出段何时执行?答:响应返回后按依赖树逆序执行清理。 - 同步依赖里能拿异步客户端吗?答:可以引用共享实例,但不要在同步函数里 await 其协程方法。
04.7.15.3-007 run_in_threadpool 与 run_sync 分别是什么,何时使用?
一句话结论
run_in_threadpool(Starlette)/ anyio.to_thread.run_sync 用于把普通阻塞函数丢进线程池;run_sync 是部分库(如适配器、第三方扩展)里对“同步回调在线程中执行”的封装。FastAPI 应用内需要手动卸载阻塞代码时,首选 run_in_threadpool 或 anyio.to_thread。
概念解释
- 线程池卸载解决“阻塞事件循环”,进程池卸载解决“GIL 下 CPU 密集”。
- 两者都属于把阻塞工作移出事件循环,但承担的瓶颈类型不同。
原理流程
- 识别代码是 IO 阻塞还是 CPU 密集。
- IO 阻塞(驱动调用、序列化小任务)用线程池。
- CPU 密集(大计算、图像/密码批量哈希)考虑进程池或独立任务队列。
- 在线程/进程内执行完毕后把结果交回协程。
代码或图示
from starlette.concurrency import run_in_threadpool
import anyio
async def handle():
text = await run_in_threadpool(blocking_parse, raw)
# CPU 密集示例:进程池(按需引入 concurrent.futures)
heavy = await anyio.to_process.run_sync(heavy_compute, payload)
常见误区
- 用线程池跑 CPU 密集任务:GIL 仍在,线程并行收益有限。
- 在线程池里再启动事件循环:嵌套事件循环容易报“already running”。
追问
- 线程池和进程池怎么选?答:IO 阻塞选线程池,GIL 受限的 CPU 密集选进程池或队列任务。
anyio.to_process默认可用吗?答:需 anyio 进程原语支持,生产中要评估序列化开销与进程生命周期。
04.7.15.3-008 混合使用 async def 端点与同步依赖时,依赖在哪个线程执行?
一句话结论
同步依赖在 AnyIO 工作线程执行,异步端点本身在事件循环协程执行;框架跨边界把依赖结果传回协程。也就是说“端点是 async”不会把它的同步依赖也拉进事件循环。
概念解释
- 调度判定发生在每个可调用对象上,签名决定执行位置。
- 依赖生成器的退出清理段跟随其被调度的同一位置执行。
原理流程
- 依赖解析先跑同步依赖:进线程池得到 session。
- 结果传回事件循环,注入异步端点参数。
- 端点 await 异步 IO。
- 响应生成后,
yield依赖的退出段在线程池关闭 session。
代码或图示
def get_db(): # 同步:线程池
session = sync_session_factory()
try:
yield session
finally:
session.close()
@app.get("/items/{i}")
async def item(i: int, db: Session = Depends(get_db)):
# 端点在协程;db 是线程内创建后传入的对象
return await run_in_threadpool(db.get, i)
常见误区
- 在
async def端点里直接调用同步 session 的方法:这又是阻塞调用,应再包一层线程池。 - 以为同步依赖的 session 跨线程长期安全:session 生命周期由依赖管理,不要把它存到全局。
追问
- 异步端点配同步 ORM 的推荐写法?答:同步查询用
run_in_threadpool包裹,或改用异步驱动。 - 依赖退出段会在异常时执行吗?答:会,
yield后的清理在 finally 语义下执行。
04.7.15.3-009 为什么同步阻塞式数据库驱动通常配 def 端点?
一句话结论
同步驱动的查询方法在等待数据库响应期间阻塞调用线程;配 def 端点时阻塞发生在工作线程,事件循环继续服务其他请求。若配 async def 端点直接调用同步驱动,等待期间事件循环被冻结,整进程并发能力坍塌。
概念解释
- 同步驱动没有 await 挂起点,只能靠线程隔离阻塞。
- 异步驱动(asyncpg、aiomysql、async SQLAlchemy 等)配合
async def端点,等待时挂起协程。
原理流程
- 同步驱动建立 TCP 连接,查询后阻塞读响应。
def端点把这段阻塞隔离在工作线程。- 事件循环同时调度其他协程,连接等待不占循环。
- 驱动响应到达工作线程,查询结果返回路由层。
代码或图示
# 同步驱动:端点用 def
@app.get("/users")
def list_users(db: Session = Depends(get_db)):
return db.query(User).all()
# 异步驱动:端点用 async def
@app.get("/users-async")
async def list_users_async(db: AsyncSession = Depends(get_async_db)):
result = await db.execute(select(User))
return result.scalars().all()
常见误区
- 把同步 session 塞进
async def端点“顺便查库”:阻塞读响应期间整个循环停摆。 - 混用同步/异步驱动连接池:各自的连接与 session 不能跨池借用。
追问
- 为什么异步驱动在等待时不阻塞循环?答:基于事件循环注册 socket 可读事件,等待期间挂起协程。
- 同步驱动能否靠多开线程池扛住并发?答:能部分缓解,但受线程数与 DB 连接上限约束。
04.7.15.3-010 async def 端点里调用同步阻塞库会发生什么?
一句话结论
阻塞库在等待或计算期间占住事件循环线程,循环无法切换到其他协程;表现为所有并发请求同时变慢、超时、连接堆积,直到阻塞函数返回。这是 FastAPI 异步服务最常见的线上事故之一。
概念解释
- 事件循环单线程顺序执行协程,任何没有 await 让出点的阻塞都会冻结调度。
- 症状与“下游数据库慢”相似,但根因是本机循环被占,下游指标可能并不高。
原理流程
- 协程进入阻塞调用(同步 HTTP、
time.sleep、大哈希、同步 IO)。 - 阻塞期间循环无法处理就绪协程、定时器与新连接事件。
- 其他请求的响应推迟到阻塞返回后才被调度。
- 积压连接占满服务端与下游连接池,连锁超时。
代码或图示
import requests, time
@app.get("/bad")
async def bad():
time.sleep(2) # 阻塞循环
r = requests.get("https://x") # 阻塞循环
return r.json()
@app.get("/good")
async def good():
r = await httpx.AsyncClient().get("https://x")
return r.json()
常见误区
- 看到是
async def就认为代码一定非阻塞:签名不决定体内是否阻塞。 - 用
asyncio.create_task包装同步阻塞函数:任务仍在同一循环线程,阻塞照样冻结。
追问
- 阻塞库必须换掉吗?答:可换异步实现,或用线程池/进程池卸载,不能直接在协程里调。
- 怎么快速确认是循环阻塞?答:看单 worker CPU、事件循环延迟与全请求延迟是否同步抬升。
04.7.15.3-011 阻塞调用拖垮事件循环的机理是什么?
一句话结论
CPython 的事件循环在单个线程上顺序调度就绪协程;阻塞调用不注册挂起事件也不返回控制权,循环停在当前协程内,定时器、连接接受、其他协程全部无法被调度,形成“单点阻塞、全局排队”。
概念解释
- 异步并发依赖“等待时让出循环”:IO 等待由 epoll/kqueue 监听,协程挂起。
- 阻塞调用没有让出点,循环的下一步就绪协程要等当前函数返回后才可见。
原理流程
- 循环从就绪队列取协程执行。
- 协程进入同步阻塞:线程在内核态/用户态等待,不返回循环。
- 新连接、socket 可读、定时器到期等事件堆积在循环层未处理。
- 阻塞返回后循环批量处理积压请求,延迟呈突刺。
代码或图示
正常:协程 await IO → 让出循环 → 调度其他协程 → IO 就绪后唤醒
阻塞:协程进入同步等待 → 循环停住 → 其他请求全部排队 → 阻塞返回后批量补发
常见误区
- 以为有 GIL 就一定多线程并行:事件循环自身是单线程调度,阻塞即停摆。
- 把阻塞误判成“下游慢”:本机循环阻塞时,下游 RTT 与错误率可能正常。
追问
- 为什么协程等待 IO 不会阻塞循环?答:等待挂起并把控制权交回循环,事件由循环统一监听唤醒。
- 阻塞 100ms 影响多大?答:并发量越高,积压请求越多,延迟按排队长度放大。
04.7.15.3-012 如何识别事件循环被阻塞(症状与监控指标)?
一句话结论
典型症状:单 worker 下所有接口同时变慢、CPU 未必打满、下游无明显慢查询;可观测指标看事件循环延迟(loop lag)、请求 P99 突刺、挂起协程数与线程池队列长度,配合 py-spy/tracemalloc/循环延迟探针定位阻塞点。
概念解释
- 循环延迟:定时器被推迟执行的时长,是判断阻塞最直接的信号。
- 线程池排队与事件循环阻塞是两类问题,要分别看队列长度与 loop lag。
原理流程
- 接入 loop lag 探针:周期调度
loop.call_later,测量回调实际延迟。 - 监控 P50/P95/P99 与并发在途请求数,对比下游耗时。
- 阻塞时段抓取进程栈(
py-spy dump),定位停留在同步库帧的协程。 - 按库与路径归类,决定换异步实现或卸载线程池/进程池。
代码或图示
import time, asyncio
async def lag_probe(interval: float = 1.0):
last = time.perf_counter()
while True:
await asyncio.sleep(interval)
now = time.perf_counter()
lag = now - last - interval
last = now
if lag > 0.05:
print(f"loop lag: {lag:.3f}s")
常见误区
- 只看平均延迟:阻塞突刺被均值掩盖,必须看 P99 与尾延迟分布。
- 发现慢就加 worker:本机循环阻塞在每个 worker 内都会复现,扩容只能分摊不能消除根因。
追问
py-spy能抓协程栈吗?答:能抓当前线程调用栈,结合阻塞帧定位同步库调用。- 线程池满和循环阻塞怎么区分?答:线程池满看排队与线程占用,循环阻塞看 loop lag 与全局同步延迟。
04.7.15.3-013 CPU 密集型任务为什么不该放在异步端点里?
一句话结论
CPU 密集计算在单线程协程里持续占用循环,阻塞其他请求;即便用线程池卸载,GIL 仍限制线程并行,CPU 密集任务吞吐提升有限。正确做法是拆到进程池、后台任务队列(Celery/RQ/独立 worker)或独立微服务。
概念解释
- GIL 保证同一进程同一时刻只有一个线程执行 Python 字节码,线程并行对纯计算帮助不大。
- 异步模型的优势在 IO 等待,不在计算并行。
原理流程
- 端点收到请求,识别任务为 CPU 密集(大循环、图像、压缩、批量哈希)。
- 不在循环线程内执行;提交进程池或任务队列。
- 队列 worker 独立进程消费,释放 GIL 竞争。
- 结果通过回调、轮询或消息通知前端。
代码或图示
# 不推荐:在请求线程里同步重算
@app.post("/hash-batch")
async def hash_batch(rows: list[dict]):
return [hash_password(r["pw"]) for r in rows] # CPU 密集
# 推荐:投递到后台任务队列,接口立即返回任务 ID
@app.post("/hash-batch")
def hash_batch(rows: list[dict]):
task_id = hash_queue.enqueue(batch_hash, rows)
return {"task_id": task_id}
常见误区
- 用
asyncio.to_thread解决 CPU 密集:GIL 仍串行,线程切换反而增加开销。 - 把大计算做成“长耗时端点”:占用在途连接,拖垮在线接口容量。
追问
- 小批量计算能否在线程池跑?答:量小可接受,需压测确认不影响尾延迟。
- 进程池的代价是什么?答:参数需序列化传递,进程启动与内存开销更高。
04.7.15.3-014 常见阻塞陷阱库和写法有哪些?
一句话结论
高频阻塞点:requests/urllib 同步 HTTP、time.sleep、同步数据库驱动、同步 Redis 客户端、大对象 json.dumps/加密哈希/正则回溯、阻塞式文件读写与 DNS 解析。这些在 async def 端点内直接调用都会冻结循环。
概念解释
- 阻塞分 IO 等待阻塞与 CPU 计算阻塞,二者卸载方式不同。
- 第三方 SDK 常只提供同步客户端,接入前要确认有无异步实现。
原理流程
- 审查端点与依赖体内的库调用。
- 标注同步 HTTP/驱动/客户端与重计算函数。
- IO 阻塞替换异步客户端或包线程池;CPU 密集拆进程/队列。
- 上线后用 loop lag 回归验证。
代码或图示
# 阻塞陷阱对照
time.sleep(1) # 阻塞:asyncio.sleep(1)
requests.get(url) # 阻塞:httpx.AsyncClient
redis_client.get(key) # 阻塞:redis.asyncio
open(path, "rb").read() # 阻塞:aiofiles 或线程池
hashlib.pbkdf2_hmac(...) # CPU:控制规模或进程池
常见误区
- 以为
httpx就一定异步:httpx.Client是同步,httpx.AsyncClient才是异步。 - 只检查端点函数体,漏掉依赖、工具函数和中间件里的同步调用。
追问
- 同步 SDK 没有异步版怎么办?答:用线程池隔离,或在服务边界改造调用方式。
- 文件上传读取算阻塞吗?答:大文件同步读写是,流式/异步方式或线程池处理。
04.7.15.3-015 如何把阻塞调用安全地移出事件循环?
一句话结论
IO 阻塞用异步客户端重写,或经 run_in_threadpool/anyio.to_thread 提交线程池;CPU 密集经进程池或后台队列;卸载后仍要控制并发限额与超时,避免下游被打满。
概念解释
- 卸载要在调用边界做,保留类型与异常透传。
- 线程内对象不要跨请求共享,注意关闭资源。
原理流程
- 判定阻塞类型(IO 等待 / CPU 计算)。
- IO:优先异步客户端;无异步实现则线程池包裹。
- CPU:进程池或任务队列异步化。
- 设置超时与并发上限,捕获异常并记录,结果交回协程返回。
代码或图示
from starlette.concurrency import run_in_threadpool
import anyio
async def enrich(order: Order):
# 同步第三方查询 → 线程池
profile = await run_in_threadpool(legacy_sdk.fetch_profile, order.user_id)
# 异步 HTTP → 直接 await
async with httpx.AsyncClient() as client:
goods = await client.get(f"https://api/goods/{order.goods_id}")
return merge(profile, goods.json())
常见误区
- 卸载后不设超时:阻塞线程被长期挂住,线程池逐渐耗尽。
- 线程池内持有连接未关闭:连接泄漏随请求累积。
追问
- 卸载后异常会透传到端点吗?答:会,线程/任务内异常在线程返回时重新抛出到协程。
- 批量阻塞调用要不要加信号量?答:要,线程池/下游都需要并发上限保护。
04.7.15.3-016 time.sleep 与 asyncio.sleep 在端点里的行为差异?
一句话结论
time.sleep 是线程级阻塞:在事件循环线程内调用会冻结整个循环;asyncio.sleep 是协程级挂起:到期前把控制权交还循环,可调度其他协程。异步端点里等待一律用 asyncio.sleep 或 anyio 的 sleep。
概念解释
time.sleep由操作系统挂起当前线程,不区分事件循环。asyncio.sleep注册定时器事件,协程挂起,循环继续跑别的就绪任务。
原理流程
- 调用
asyncio.sleep(n):协程向循环注册定时器后挂起。 - 循环处理其他就绪协程与网络事件。
- 定时器到期,协程进入就绪队列被唤醒。
time.sleep(n)则直接阻塞当前线程,循环在睡眠期间无动作。
代码或图示
import asyncio, time
@app.get("/async-wait")
async def async_wait():
await asyncio.sleep(1) # 让出循环
return "ok"
@app.get("/bad-wait")
async def bad_wait():
time.sleep(1) # 冻结循环
return "ok"
常见误区
- 在
def端点里用asyncio.sleep:同步函数没有 await 上下文,不能直接挂起。 - 用
time.sleep做压测等待:单机压测时它会人为放大循环阻塞,结果失真。
追问
anyio.sleep与asyncio.sleep区别?答:anyio 提供跨后端统一的 sleep 原语,底层仍映射到事件循环定时器。- 同步端点里想等待怎么办?答:用
time.sleep隔离在线程内,不影响循环。
04.7.15.3-017 阻塞导致的超时与连接堆积链路是怎样的?
一句话结论
循环阻塞 → 在途请求无法被调度 → 客户端/上游网关超时重试 → 新连接持续进入 → 服务端连接表、线程池、下游连接池被占满 → 健康检查失败、整服务雪崩。阻塞是单点,堆积是链式放大。
概念解释
- 每个在途请求占服务端一条连接、一份内存、可能一个下游连接。
- 重试会把一次慢请求变成多次流量,放大下游压力。
原理流程
- 某端点进入阻塞调用,循环延迟抬升。
- 其他请求排队等待,响应时间拉长。
- 上游网关/客户端超时后重试,重复请求叠加。
- 连接与池位耗尽,健康探针超时,编排层摘除实例。
代码或图示
阻塞调用 → 循环停摆 → 请求排队 → 客户端超时重试 → 连接/池位耗尽 → 健康检查失败 → 实例下线
常见误区
- 只给端点设业务超时,不限制整体在途并发:阻塞期新请求仍持续接入。
- 重试次数无上限:雪崩期间重试把下游彻底打穿。
追问
- 怎么打断这条链路?答:入口限流、连接与线程池上限、下游超时、重试退避与熔断、健康检查联动。
- 阻塞恢复后堆积会自动消化吗?答:会逐步消化,但积压期超时请求已经流失,需观测尾延迟。
04.7.15.3-018 大 JSON 序列化与加密计算算阻塞吗,怎么拆?
一句话结论
算。大对象遍历、json.dumps、json.loads、批量密码哈希、压缩解压、正则回溯都占住 CPU,在循环线程内执行即阻塞;小任务可在线程池跑,大计算量拆到进程池或后台队列,并控制单次数据规模。
概念解释
- 序列化是 CPU + 内存操作,响应模型校验也会遍历字段。
- Pydantic 模型构造与校验同样有 CPU 成本,大 payload 时不可忽略。
原理流程
- 定位热点:按接口测量序列化与校验耗时占比。
- 小规模重计算用线程池卸载;大规模计算走进程池/任务队列。
- 限制单次入参/出参规模,分页或流式返回。
- 选择更快的序列化路径(按需
orjson等替代实现,待确认:验证点:项目依赖中是否已引入及与 Pydantic 的兼容方式)。
代码或图示
import json
from starlette.concurrency import run_in_threadpool
@app.get("/export")
async def export():
rows = await load_rows()
# 大 JSON 构造放到线程池,避免占循环
payload = await run_in_threadpool(json.dumps, rows, ensure_ascii=False)
return Response(payload, media_type="application/json")
常见误区
- 以为序列化很快:上万行的列表
model_dump+ JSON 编码是可观的 CPU 段。 - 用线程池跑超大计算:GIL 下线程并行收益有限,应进程隔离。
追问
- 响应模型序列化能绕过吗?答:可直接返回
Response/JSONResponse手写编码,但要放弃模型校验收益。 - 大文件导出怎么做?答:分页 + 流式响应(见本页流式相关题),不一次性构造全量列表。
04.7.15.3-019 anyio 在 FastAPI 里承担什么角色?
一句话结论
AnyIO 是 FastAPI/Starlette 的并发原语层:线程池提交、同步原语(锁、信号量、条件事件、队列)、任务组与超时上下文都基于 AnyIO,使应用代码在 asyncio 与 trio 后端之间保持一致语义。
概念解释
- FastAPI 不直接依赖
asyncio原语做线程调度,而是走 AnyIO 封装。 - 任务组(task group)用于并发管理子任务的启动与取消传播。
原理流程
- ASGI 服务器选定事件循环后端,AnyIO 适配该后端。
- 同步端点/依赖经
anyio.to_thread进线程池。 - 需要并发子任务时用
anyio.create_task_group()。 - 超时、锁、信号量等原语由 AnyIO 统一暴露。
代码或图示
import anyio
async def fetch_all(urls):
async with anyio.create_task_group() as tg:
results = []
async def worker(u):
results.append(await http_get(u))
for u in urls:
tg.start_soon(worker, u)
return results
常见误区
- 直接混用
asyncio与trio原语:跨后端行为不一致,应用层应优先 AnyIO 抽象。 - 以为 AnyIO 是 Web 框架:它只是并发与 IO 兼容层,不提供路由与响应。
追问
- AnyIO 与 asyncio 的关系?答:AnyIO 是上层封装,可映射到 asyncio 后端,也支持 trio。
- 任务组和
create_task相比优势?答:统一管理子任务生命周期、异常与取消传播,退出时等待所有子任务结束。
04.7.15.3-020 uvloop 是什么,为什么能提速,什么场景不能用?
一句话结论
uvloop 是基于 libuv 的高性能 asyncio 事件循环实现,替代默认 asyncio 循环,在网络 IO 密集场景降低调度与回调开销;纯 Python 计算瓶颈下收益有限,且与某些依赖默认循环行为的库存在兼容风险,Windows 下支持受限(待确认:验证点:当前 uvloop 版本在目标部署平台的官方支持矩阵)。
概念解释
- 提速主要来自更高效的 IO 多路复用、定时器与回调调度,不是改变 GIL 规则。
- 部署在 Linux 容器中收益最明显;本地 Windows 开发不一定启用。
原理流程
- uvicorn 按 loop 配置选择事件循环实现。
- 选用 uvloop 后,socket 注册、定时器、连接事件由 libuv 处理。
- 协程调度与回调路径更短,IO 密集 QPS 与延迟改善。
- 依赖若假定默认循环实现(如私有访问循环内部对象),可能不兼容。
代码或图示
# uvicorn 显式指定
uvicorn app:app --loop uvloop --host 0.0.0.0 --port 8000
常见误区
- 上了 uvloop 就能解决阻塞调用:阻塞线程/循环问题依旧存在。
- 忽略平台兼容:在不支持或未安装 uvloop 的环境强行指定会启动失败。
追问
- 怎么确认运行时用的是不是 uvloop?答:打印事件循环实例类型,或查看 uvicorn 启动日志的 loop 配置。
- 安装 uvloop 后会自动替换默认循环吗?答:由服务器 loop 配置决定,需显式选择或 auto 探测。
04.7.15.3-021 asyncio.timeout、timeout= 参数与 asyncio.wait_for 有何区别?
一句话结论
asyncio.timeout(Python 3.11+)是上下文管理器,进入块内统一限时,超时抛 TimeoutError;asyncio.wait_for(coro, timeout) 对单个协程限时并在超时取消它;FastAPI 路由没有内置 timeout= 参数,接口级超时需在调用下游时自行包裹(如 anyio/asyncio 超时上下文或客户端超时)。
概念解释
- 超时的本质是“等待有上限”,必须覆盖所有外部调用与整体等待段。
asyncio.timeout支持reschedule()与嵌套超时计算剩余时间。
原理流程
- 在需要限制的调用段进入超时上下文。
- 内部等待事件超过剩余时限即触发超时异常。
- 超时向上传播,触发取消与资源清理。
- 下游 HTTP 客户端同时配置自身超时,避免连接长期挂住。
代码或图示
import asyncio
@app.get("/call")
async def call():
async with asyncio.timeout(3.0):
return await downstream.query()
# 旧写法(3.11 之前)
result = await asyncio.wait_for(downstream.query(), timeout=3.0)
常见误区
- 以为 FastAPI 端点自带整体超时:框架不强制,超时要在依赖与调用层显式设置。
- 只给 HTTP 客户端设超时,漏了数据库与消息队列等待:这些段仍可能无限挂起。
追问
wait_for超时后会取消协程吗?答:会向被等待协程发出取消,由其清理资源。- Python 3.10 及更早用什么?答:
asyncio.wait_for或 anyio 超时原语。
04.7.15.3-022 超时触发后协程里的资源会怎样释放?
一句话结论
超时取消会把 CancelledError 抛进协程,finally 与上下文管理器退出段执行清理;若代码吞掉取消、持有连接未关闭,资源会泄漏。必须把释放逻辑放在 finally/async with/yield 依赖退出段,且不在清理段再做无限等待。
概念解释
- 依赖生成器的退出段、
async with块、try/finally是三类可靠清理位置。 - 取消传播期间再次 await 可能被二次取消,清理动作要短而稳。
原理流程
- 超时或断连触发取消,协程收到
CancelledError。 - 沿调用栈展开,执行各层
finally与上下文退出。 yield依赖在响应/取消后逆序执行清理。- 清理完成后取消继续向上传播;客户端侧不再等待响应。
代码或图示
@app.get("/job")
async def job():
session = await pool.acquire()
try:
async with asyncio.timeout(5):
return await session.work()
finally:
await pool.release(session) # 取消时也会执行
常见误区
- 用
except Exception吞掉CancelledError:取消被掩盖,协程与连接泄漏。 - 清理段里再发起无超时的下游调用:清理自身也可能被挂住。
追问
- 怎么验证取消时资源确实释放?答:压测中断连/超时场景,观测连接数、池水位与日志清理记录。
- 后台任务被取消后要补做业务吗?答:按业务语义决定,通常靠任务队列重试保证最终一致。
04.7.15.3-023 anyio.to_thread 与 anyio.to_process 的适用边界是什么?
一句话结论
anyio.to_thread 卸载 IO 阻塞与小计算,共享进程内存,开销低但受 GIL 限制;anyio.to_process 隔离 CPU 密集任务,参数经序列化传递,内存与启动成本更高。选型先分清瓶颈是等待还是计算。
概念解释
- 线程适合等待阻塞:线程挂起时不占 GIL。
- 进程适合并行计算:绕过 GIL,但对象不能直接共享。
原理流程
- 分析热点属于 IO 等待还是 CPU 占用。
- IO 阻塞选
to_thread,注意线程池限额。 - CPU 密集选
to_process或外部任务队列,评估序列化与进程数。 - 结果返回协程,异常随调用边界重新抛出。
代码或图示
import anyio
async def handle():
# IO 阻塞 → 线程
text = await anyio.to_thread.run_sync(read_blocking_file, path)
# CPU 密集 → 进程(按需使用)
image = await anyio.to_process.run_sync(encode, raw)
return text, image
常见误区
- 进程内传大对象:序列化成本可能超过计算本身。
- 频繁起进程:进程启动开销大,应复用 worker 进程池而非每请求新建。
追问
- 生产里 CPU 密集更常用什么?答:独立任务队列与常驻 worker 进程,接口只投递任务并返回 ID。
- 线程内能否访问协程侧对象?答:能读传入对象引用,但线程安全与生命周期要自行保证。
04.7.15.3-024 Starlette 中间件在请求生命周期中的执行顺序?
一句话结论
中间件按 add_middleware 逆序包裹:后添加的在最外层(先进入、最后返回),先添加的靠近路由(后进入、先返回)。请求自上而下穿过中间件链到达路由,响应沿原路逆向回程;异常从路由向上抛出,由外层中间件或异常处理器接管。
概念解释
- 中间件分两类:基于
BaseHTTPMiddleware的函数式包装,与纯 ASGI 可调用对象。 - CORS、认证、日志等横切关注点都在链上。
原理流程
- 应用初始化时中间件被组装成嵌套调用链。
- 请求进入:从最外层依次向内,经过各中间件
dispatch/ASGI 段。 - 到达路由执行端点,生成响应。
- 响应回程:从内向外依次经过中间件
call_next之后的段落。
代码或图示
app.add_middleware(CORSMiddleware, ...) # 最外层
app.add_middleware(AuthMiddleware) # 内层,靠近路由
# 请求:CORS → Auth → 路由;响应:路由 → Auth → CORS
常见误区
- 以为添加顺序就是执行顺序:实际是“后加者在外层”。
- 把认证放在 CORS 内层:预检请求可能在认证之前被挡,跨域报错难排查。
追问
- 中间件里读到的响应一定包含端点状态码吗?答:
call_next返回后可读响应元数据,但流式 body 的分块行为取决于中间件实现。 - 中间件能短路返回吗?答:能,不调用
call_next直接返回响应即短路。
04.7.15.3-025 BaseHTTPMiddleware 的工作原理是什么?
一句话结论
BaseHTTPMiddleware 把 ASGI 的 receive/send 消息流包装成类似 HTTP 请求/响应的抽象:子类实现 dispatch(request, call_next),call_next 向下执行内层链路并返回响应对象;框架在内部用任务组与队列桥接 ASGI 消息和高阶响应。
概念解释
- 它是 Starlette 提供的便捷基类,屏蔽了原始 ASGI 消息细节。
- 内部通过 anyio 任务组运行内层应用,消息经队列在 ASGI 层与高阶层之间流转。
原理流程
- 请求到达,中间件构造
Request(scope, receive)。 dispatch执行前置逻辑(鉴权、日志、头处理)。- 调用
call_next(request),内层链路在独立任务中执行,响应被收集成Response。 - 中间件做后置改写后把响应发回外层。
代码或图示
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request
class LogMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request: Request, call_next):
resp = await call_next(request)
resp.headers["X-App"] = "fastapi"
return resp
常见误区
- 以为它是零成本抽象:桥接任务组与队列本身有调度开销。
- 在
dispatch里多次读 request body:body 流被消费后内层拿不到,需缓存后重放。
追问
call_next返回的响应包含 body 吗?答:包含收集后的响应对象,但流式场景见下一题的已知限制。- 中间件里能拿到路由参数吗?答:高阶请求对象上一般不直接暴露路由匹配结果,需从 scope 或依赖侧获取。
04.7.15.3-026 BaseHTTPMiddleware 处理流式响应有什么已知问题?
一句话结论
BaseHTTPMiddleware 内部会把内层 send 的消息收集/缓冲在任务组与队列中,对 StreamingResponse、SSE、长连接流式输出存在缓冲延迟、body 分段交互不充分等已知限制;需要严格流式转发或高性能链时,应改用纯 ASGI 中间件。
概念解释
- 高阶响应模型天然假设“先有完整响应再处理”,与逐块推送的流式模型存在张力。
- Starlette 官方文档对该基类的流式与可组合性有明确限制说明(待确认:验证点:所用 Starlette 0.4x 版本文档中关于 BaseHTTPMiddleware 流式行为的最新表述)。
原理流程
- 内层生成器逐块
send响应消息。 BaseHTTPMiddleware桥接层经队列传递这些消息。- 缓冲与任务调度引入延迟,首字节时间与推送节奏受影响。
- 纯 ASGI 中间件直接透传
send消息,不做高阶收集。
代码或图示
# 流式端点
@app.get("/stream")
async def stream():
async def gen():
for i in range(10):
yield f"data: {i}\n\n"
await asyncio.sleep(0.2)
return StreamingResponse(gen(), media_type="text/event-stream")
常见误区
- 在
BaseHTTPMiddleware里给 SSE 加日志/改头后发现客户端收不到实时推送:缓冲层拖慢了消息透传。 - 以为流式响应经过该中间件会自动逐块回调:高阶层拿到的是收集后的响应对象。
追问
- 流式接口能不能完全不用中间件?答:横切逻辑可下沉到纯 ASGI 中间件或依赖层。
- 怎么验证流式是否被缓冲?答:观察首字节时间、消息到达间隔与长连接保活表现。
04.7.15.3-027 为什么 BaseHTTPMiddleware 会有额外开销?
一句话结论
每个请求都要经过高阶抽象桥接:构造 Request/Response、启动 anyio 任务组、消息队列收发与任务调度切换;相比纯 ASGI 中间件直接操作 receive/send 消息,多了对象构造、队列往返与协程切换成本,高 QPS 下可观测到 CPU 与延迟增量。
概念解释
- 开销来自抽象层级,而非某个算法;链路中间件越多,每请求桥接次数越多。
- 功能简单的横切逻辑用纯 ASGI 写法更省。
原理流程
- 请求进入基类
__call__,建立队列与任务组。 - 内层应用在任务中运行,消息经队列双向传递。
- 响应被组装成高阶对象后再转回 ASGI 消息发出。
- 每步都有协程切换与对象分配,QPS 放大后体现为 CPU 增量。
代码或图示
纯 ASGI:scope/receive/send 直传,零高阶对象
BaseHTTPMiddleware:任务组 + 队列 + Request/Response 构造 + 回程转换
常见误区
- 中间件功能很简单就忽略开销:每个请求都付桥接成本,与逻辑复杂度无关。
- 把多个轻量中间件都挂在基类上:嵌套桥接层数相乘放大开销。
追问
- 怎么量化中间件开销?答:对比挂/不挂中间件的同接口 QPS、P99 与 CPU 占用。
- 便捷性与性能怎么权衡?答:普通业务用基类,热路径/流式/高吞吐链路用纯 ASGI。
04.7.15.3-028 纯 ASGI 中间件的标准写法是什么?
一句话结论
纯 ASGI 中间件是一个可调用对象:接收 app,__call__(scope, receive, send) 返回内部可调用;按 scope["type"] 分流 HTTP/WebSocket,需要前置逻辑时先执行,再 await app(scope, receive, send),需要改响应则包装 send 函数拦截响应消息。
概念解释
- 不依赖
Request/Response高阶对象,直接处理 ASGI 消息字典。 - 中间件工厂模式:外层接收
app与参数,内层处理单次连接。
原理流程
- 工厂构造中间件实例,保存
app与配置。 - 连接到达,ASGI 服务器调用中间件
__call__(scope, receive, send)。 - 前置检查通过后转发给内层
app;包装send以观测/改写响应头。 - 按 scope 类型处理异常或 WebSocket 流程。
代码或图示
class CustomHeaderMiddleware:
def __init__(self, app):
self.app = app
async def __call__(self, scope, receive, send):
if scope["type"] != "http":
await self.app(scope, receive, send)
return
async def send_wrapper(message):
if message["type"] == "http.response.start":
headers = message.setdefault("headers", [])
headers.append((b"x-app", b"fastapi"))
await send(message)
await self.app(scope, receive, send_wrapper)
常见误区
- 忘记按
scope["type"]分流:WebSocket 消息结构与 HTTP 不同,混用会报错。 - 包装
send后原样转发但漏改头:headers 必须是(bytes, bytes)元组列表。
追问
- 纯 ASGI 中间件能读 body 吗?答:能,通过
receive取http.request消息,注意重放给内层。 - 怎么注册纯 ASGI 中间件?答:
app.add_middleware(CustomHeaderMiddleware),基类与纯 ASGI 都走该接口。
04.7.15.3-029 中间件里如何读取与改写请求头、响应头?
一句话结论
请求头在 scope["headers"] 中,是 (bytes, bytes) 元组列表,可用 Request.headers 字典化读取;响应头在 http.response.start 消息的 headers 字段改写。高阶中间件可在 call_next 后改 resp.headers,纯 ASGI 中间件包装 send 修改 start 消息。
概念解释
- 头部名/值在 ASGI 层都是 bytes,高阶对象转成 str。
- 重复同名头需要保留多个元组,不能简单覆盖。
原理流程
- 读取:从 scope headers 解析或用
Request(scope, receive).headers。 - 前置校验:校验不通过直接返回响应,不进内层。
- 改写响应:高阶层改
resp.headers;ASGI 层在send_wrapper中改 start 消息。 - 转发内层应用并回程发送。
代码或图示
from starlette.requests import Request
from starlette.responses import JSONResponse
class HeaderCheck:
def __init__(self, app):
self.app = app
async def __call__(self, scope, receive, send):
request = Request(scope, receive)
if not request.headers.get("x-token"):
resp = JSONResponse({"detail": "unauthorized"}, status_code=401)
await resp(scope, receive, send)
return
await self.app(scope, receive, send)
常见误区
- 把头部当成 str 列表直接拼:ASGI 消息要求 bytes 元组。
- 在内层已发出响应后再改头:start 消息一旦发送,后续不能补改响应头。
追问
- 怎么取原始 host、path?答:
scope["server"]、scope["path"]、scope["headers"],高阶对象也提供对应属性。 - 多值头怎么读?答:
Request.headers.getlist(Starlette 头对象提供多值读取能力,按所用版本核对 API)。
04.7.15.3-030 中间件链中包装 receive/send 后要注意什么?
一句话结论
包装 receive/send 必须原样转发消息字典、保留消息类型语义;消费了请求 body 要重放给内层;包装 send 要区分 http.response.start 与 http.response.body,不能吞掉结束标志(more_body 为假的 body 消息)。
概念解释
receive是拉模型:内层按需取消息,中间件不能一次性读完丢弃。send是推模型:start 先于 body,body 分多块,末块带结束标志。
原理流程
- 包装
receive:拦截消息后要么直接转发,要么缓存并在重放时按原顺序返回。 - 包装
send:观测消息类型与头,追加逻辑后调用原始send。 - 保证消息不丢、不改类型、不破坏
more_body语义。 - WebSocket 消息类型单独处理,不套用 HTTP body 规则。
代码或图示
async def receive_wrapper():
message = await receive()
# 如需读取 body,缓存后供内层再次取用
return message
async def send_wrapper(message):
if message["type"] == "http.response.body":
# 观测 body 分块;不可吞掉 more_body=False 的结束消息
pass
await send(message)
常见误区
- 中间件读完 body 不重放:内层依赖与端点拿到空 body。
- 包装 send 后只转发 start 不转发 body:客户端挂起等待响应体。
追问
- 缓存 body 有什么代价?答:大上传/大 body 占内存,需配合大小限制与流式处理。
- WebSocket 连接在中间件层怎么包装?答:按
websocket.connect/websocket.receive/websocket.send消息类型分别处理。
04.7.15.3-031 如何在中间件里做请求 ID 注入与日志关联?
一句话结论
在最外层中间件读取上游传入的 X-Request-ID,没有则生成 UUID,写入 contextvars 供日志读取,并在响应头回写;日志格式化器从上下文变量取值,保证一条请求的所有日志(含线程池内)带同一请求 ID。
概念解释
- 请求 ID 是跨服务排障的关联键,应贯穿接入层、应用日志与下游调用头。
contextvars在协程与线程边界复制,适合承载请求级标识。
原理流程
- 最外层中间件进入时解析或生成请求 ID。
- 写入上下文变量,下游日志与依赖读取该变量。
- 响应头追加
X-Request-ID返回客户端/上游。 - 请求结束上下文随请求销毁,不跨请求残留。
代码或图示
import uuid, contextvars
from starlette.requests import Request
request_id_var: contextvars.ContextVar[str] = contextvars.ContextVar("request_id")
class RequestIdMiddleware:
def __init__(self, app):
self.app = app
async def __call__(self, scope, receive, send):
if scope["type"] != "http":
await self.app(scope, receive, send)
return
req = Request(scope, receive)
rid = req.headers.get("x-request-id") or uuid.uuid4().hex
request_id_var.set(rid)
async def send_wrapper(message):
if message["type"] == "http.response.start":
message["headers"].append((b"x-request-id", rid.encode()))
await send(message)
await self.app(scope, receive, send_wrapper)
常见误区
- 把请求 ID 存全局变量:并发请求互相覆盖。
- 只在端点日志里打 ID,下游调用头不带:跨服务链路断联。
追问
- 线程池里能读到请求 ID 吗?答:上下文变量随线程提交复制,可读;写回不影响协程侧。
- 上游伪造请求 ID 怎么办?答:可校验格式/长度,或在网关层重新生成并覆盖。
04.7.15.3-032 中间件抛异常与端点抛异常分别由谁处理?
一句话结论
端点与依赖抛出的异常会经过路由层,匹配已注册的 exception_handler(含 HTTPException、RequestValidationError 默认处理器);中间件在 call_next 之前或纯 ASGI 段抛出的异常,发生在异常处理器外层,不会被应用级处理器捕获,需要中间件自身 try/except 或外层服务器兜底。
概念解释
- 异常处理器挂载在应用内部链路,外层中间件处于其包裹范围之外。
- 异常向上冒泡经过各层中间件,最终到 ASGI 服务器。
原理流程
- 端点/依赖抛错 → 路由层按异常类型查找处理器。
- 处理器生成统一响应,沿中间件链回程。
- 中间件前置段抛错 → 跳过内层链路,直接向上冒泡。
- 未被捕获的异常由服务器转成 500 响应或记录 traceback。
代码或图示
# 端点异常:可被 exception_handler 捕获
@app.get("/item/{i}")
def item(i: int):
raise HTTPException(status_code=404, detail="not found")
# 中间件前置异常:需自行兜底
class Guard:
def __init__(self, app):
self.app = app
async def __call__(self, scope, receive, send):
try:
await self.app(scope, receive, send)
except ValueError:
await JSONResponse({"detail": "bad"})(scope, receive, send)
常见误区
- 以为所有异常都能被
@app.exception_handler接住:外层中间件与服务器层异常不在范围内。 - 在中间件里吞掉异常不记录:故障失去 traceback,排障困难。
追问
- 500 异常默认怎么表现?答:未注册处理器时由服务器返回 500,框架默认不暴露内部堆栈给客户端。
- 怎么统一兜底所有未处理异常?答:注册
Exception类型处理器,同时外层中间件做记录与降级。
04.7.15.3-033 HTTPException 的结构与默认响应格式?
一句话结论
HTTPException(status_code, detail=None, headers=None) 携带状态码、错误详情与可选响应头;默认处理器返回 JSON {"detail": ...},状态码取自 status_code,headers 写入响应头。它是业务可预期错误的标准抛错方式。
概念解释
detail可以是字符串、dict 或列表,会原样序列化进detail字段。- 与 500 类未预期异常区分:
HTTPException是主动抛出的受控错误。
原理流程
- 端点/依赖抛出
HTTPException。 - 路由层匹配到内置
http_exception_handler。 - 构造
JSONResponse({"detail": detail}),写入状态码与附加头。 - 响应沿链路回程。
代码或图示
from fastapi import HTTPException
@app.get("/users/{uid}")
def user(uid: int):
if uid <= 0:
raise HTTPException(
status_code=400,
detail={"code": "invalid_uid", "message": "用户 ID 不合法"},
headers={"X-Error": "bad-request"},
)
常见误区
- 用
HTTPException(500, ...)包装内部异常:应记录原始堆栈,500 走未捕获异常处理器。 - 在
detail里塞数据库错误、堆栈或敏感信息:会原样回传客户端。
追问
- 401 响应要带
WWW-Authenticate吗?答:可通过headers参数设置,OAuth2 方案通常需要。 HTTPException能在后台任务里抛吗?答:后台任务异常不再经过请求处理器,只能记录日志。
04.7.15.3-034 如何注册 exception_handler 覆盖默认异常响应?
一句话结论
用 @app.exception_handler(SomeException) 注册处理器函数,签名为 async def handler(request: Request, exc: Exception),返回 Response;可覆盖 HTTPException、RequestValidationError 或自定义异常类型,也可在应用初始化后用 app.add_exception_handler() 追加。
概念解释
- 处理器按异常类型匹配,支持注册
Exception作为最后兜底。 - 处理器内可访问请求对象,记录上下文并生成统一结构响应。
原理流程
- 定义处理器:接收
Request与异常实例。 - 提取错误信息,构造统一响应模型与状态码。
- 用装饰器或
add_exception_handler绑定异常类型。 - 路由层抛错后查表调用对应处理器。
代码或图示
from fastapi import Request, FastAPI
from fastapi.responses import JSONResponse
@app.exception_handler(HTTPException)
async def http_exc_handler(request: Request, exc: HTTPException):
return JSONResponse(
status_code=exc.status_code,
content={"code": exc.status_code, "message": exc.detail},
headers=exc.headers,
)
常见误区
- 处理器返回普通 dict 而不是
Response:处理器必须返回响应对象,路由层不再做模型序列化。 - 覆盖默认处理器后丢失原有状态码/头:新处理器要把
exc.status_code、exc.headers透传。
追问
- 处理器里能抛别的异常吗?答:可以,但再次抛出的异常会继续走匹配,避免在处理器内制造二次错误。
- 多应用(子应用)处理器如何隔离?答:各
FastAPI实例独立维护处理器注册表。
04.7.15.3-035 如何把 RequestValidationError 改成统一错误格式?
一句话结论
注册 @app.exception_handler(RequestValidationError),从 exc.errors() 提取字段位置、类型与输入值,按团队错误结构重组响应;默认格式是 {"detail": [{"loc": [...], "msg": ..., "type": ...}]},字段路径在 loc 中。
概念解释
- 校验异常包含请求体、查询参数、路径参数、头与 Cookie 的全部校验失败项。
exc.errors()中的ctx可能含敏感输入,回传前需筛选字段。
原理流程
- 请求参数解析/Pydantic 校验失败,抛出
RequestValidationError。 - 路由层调用注册的校验异常处理器。
- 遍历
exc.errors(),把loc、msg、type映射成统一字段。 - 返回 422 与统一错误体。
代码或图示
from fastapi.exceptions import RequestValidationError
@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
issues = [
{"field": ".".join(map(str, e["loc"])), "reason": e["msg"]}
for e in exc.errors()
]
return JSONResponse(
status_code=422,
content={"code": "VALIDATION_ERROR", "issues": issues},
)
常见误区
- 直接把
exc.errors()整体回传:可能暴露内部校验类型名与输入值。 - 忽略
body位置前缀:loc第一项是来源(body/query/path等),拼字段名时要保留语义。
追问
- 校验失败默认状态码是多少?答:422 Unprocessable Entity(FastAPI 默认)。
- 怎么在文档里展示自定义错误结构?答:在路由
responses中声明对应状态码的响应模型。
04.7.15.3-036 业务异常类如何自定义并被统一捕获?
一句话结论
定义继承自 Exception 的业务异常(携带错误码、HTTP 状态码、可选消息),注册对应处理器把它映射成统一响应;端点与服务层只抛业务异常,不在每层重复写响应格式。
概念解释
- 业务异常分层:参数错误、鉴权失败、资源不存在、依赖故障等可各成类型。
- 处理器集中做日志、错误码翻译与响应封装。
原理流程
- 定义
BizError(Exception),字段含code、status_code、message。 - 服务/端点抛出具体业务异常。
- 处理器查表生成统一 JSON 响应。
- 未匹配的异常落到
Exception兜底处理器转 500。
代码或图示
class BizError(Exception):
def __init__(self, code: str, message: str, status_code: int = 400):
self.code = code
self.message = message
self.status_code = status_code
@app.exception_handler(BizError)
async def biz_handler(request: Request, exc: BizError):
return JSONResponse(
status_code=exc.status_code,
content={"code": exc.code, "message": exc.message},
)
@app.get("/order/{oid}")
def order(oid: str):
if not oid:
raise BizError("ORDER_EMPTY", "订单号为空", 400)
常见误区
- 服务层直接构造
JSONResponse抛出:业务层与 HTTP 响应耦合,复用困难。 - 自定义异常不继承
Exception:异常链与处理器匹配失效。
追问
- 业务异常需要带原始异常链吗?答:可保存
__cause__/__context__用于日志,响应体不暴露。 - 怎么区分对外错误码与内部日志码?答:响应体用对外稳定码,内部日志另记详细原因与 trace ID。
04.7.15.3-037 统一错误响应应包含哪些字段,如何避免泄漏内部信息?
一句话结论
对外错误体通常含:错误码(稳定枚举)、可读消息、请求 ID、可选字段级问题列表;不包含堆栈、SQL、内部主机名、连接串、原始敏感输入。内部细节写服务端日志,按请求 ID 关联。
概念解释
- 错误消息面向调用方排障,日志面向开发排障,两者粒度不同。
- 500 类未预期异常对外只给通用提示,细节落日志。
原理流程
- 异常处理器按类型选择对外消息模板。
- 附加请求 ID 与字段问题(如有)。
- 服务端记录完整 traceback、异常链与请求上下文。
- 响应体过滤内部字段后发出。
代码或图示
{
"code": "ORDER_NOT_FOUND",
"message": "订单不存在",
"request_id": "9f2c..."
}
常见误区
- 把
str(e)、数据库报错直接回传:暴露表名、列名与查询结构。 - 4xx 与 5xx 共用同一消息模板:客户端无法区分可重试与不可重试错误。
追问
- 开发环境能返回堆栈吗?答:可按环境配置开启调试输出,但生产关闭;不要用调试格式作为默认响应。
- 字段级错误放哪里?答:放
issues/details数组,保留字段路径与原因,不含内部类型细节。
04.7.15.3-038 中间件层异常为什么绕过 exception_handler?
一句话结论
应用异常处理器挂在路由与内层链路这一侧,外层中间件包裹着整个应用;中间件前置段、纯 ASGI 段或 call_next 之外抛出的异常已经越过处理器注册范围,直接冒泡到 ASGI 服务器。要统一处理这部分,需在中间件内自行 try/except,或再包一层兜底中间件。
概念解释
- 链路嵌套顺序:服务器 → 外层中间件 → 异常处理器注册点 → 内层中间件 → 路由。
- 异常只在包裹范围内被对应层级捕获。
原理流程
- 请求穿过外层中间件进入应用。
- 应用内部异常由注册处理器接管并生成响应。
- 外层中间件自身代码抛错时,内层处理器尚未在调用栈上。
- 异常继续向上到服务器,转成默认 500 或由服务器中间件记录。
代码或图示
server
└─ outer middleware ← 此处异常绕过 app.exception_handler
└─ app exception handlers
└─ inner middleware → route handler
常见误区
- 注册了
Exception处理器就以为全链路异常都被接住:外层中间件不在注册范围内。 - 在
call_next之后抛错也期待被处理器接住:同样越过内层范围。
追问
- 怎么给外层中间件也加统一兜底?答:在中间件
__call__内 try/except,生成降级响应并记录日志。 - 服务器层还有哪一层兜底?答:ASGI 服务器会把未捕获异常转为 500 响应并输出错误日志。
04.7.15.3-039 lifespan 与旧版 on_event("startup"/"shutdown") 有什么区别?
一句话结论
lifespan 是一个异步上下文管理器函数(async with 包裹 yield),在同一段代码里表达启动初始化与关闭清理;on_event("startup")/on_event("shutdown") 是两个独立装饰器钩子,旧写法在 FastAPI 0.93 起标记弃用(待确认:验证点:所用 FastAPI 0.11x 版本中 on_event 的弃用警告与移除计划),0.11x 推荐统一使用 lifespan。
概念解释
- lifespan 与 ASGI lifespan 协议对齐:服务器在接受连接前进入,关闭时退出。
- yield 之前是启动段,yield 之后是关闭段,资源对象可在两段间共享。
原理流程
- 服务器启动,触发 ASGI lifespan 事件。
- 执行 lifespan 函数 yield 之前代码:建池、加载配置、预热。
- yield 挂起,应用开始接收请求。
- 收到关闭信号后恢复执行 yield 之后代码:关闭池、释放资源。
代码或图示
from contextlib import asynccontextmanager
@asynccontextmanager
async def lifespan(app: FastAPI):
# 启动段
await pool.open()
yield
# 关闭段
await pool.close()
app = FastAPI(lifespan=lifespan)
常见误区
- 把启动逻辑写成
yield之后:关闭时才执行,应用启动时资源未就绪。 - 关闭段再做长时间阻塞操作:影响优雅停机窗口。
追问
- 旧
startup钩子还能用吗?答:0.11x 中通常仍兼容但有弃用警告,新代码应迁移到 lifespan。 - lifespan 里能注册路由吗?答:路由应在应用构造阶段声明,lifespan 只做运行时资源管理。
04.7.15.3-040 lifespan 函数内部的标准写法是什么?
一句话结论
用 @asynccontextmanager 装饰 async def lifespan(app),函数体以 yield 分段:之前完成初始化并把资源挂到 app.state(或注入共享客户端),之后执行逆序关闭;app 参数接收当前应用实例,yield 不返回响应。
概念解释
app.state是应用级共享命名空间,挂载单例资源供依赖读取。- 资源关闭顺序与初始化相反,避免先关被依赖的连接。
原理流程
- 定义上下文管理器函数,接收
app。 - 启动段创建资源,挂
app.state。 yield让出,应用服务请求。- 关闭段逆序释放资源,异常记录后继续清理。
代码或图示
from contextlib import asynccontextmanager
from fastapi import FastAPI
@asynccontextmanager
async def lifespan(app: FastAPI):
app.state.http_client = httpx.AsyncClient(timeout=5)
app.state.cache = await make_redis()
yield
await app.state.cache.close()
await app.state.http_client.aclose()
app = FastAPI(lifespan=lifespan)
常见误区
- 忘记
yield:函数在启动段执行完即退出,应用直接进入关闭流程。 - 关闭段抛异常中断后续清理:每个资源关闭应独立 try/except,保证其余资源仍释放。
追问
- 资源怎么传给端点?答:通过依赖从
request.app.state读取,或注入共享客户端实例。 - lifespan 是同步函数可以吗?答:必须是异步上下文管理器,ASGI 服务器以 await 方式进入退出。
04.7.15.3-041 数据库连接池、Redis 客户端等资源如何在 lifespan 中初始化与释放?
一句话结论
在启动段创建连接池/客户端并挂到 app.state,依赖层按需取出;关闭段按逆序 close()/disconnect()/aclose() 释放。池参数(大小、超时、回收)在创建时定好,避免每请求新建连接。
概念解释
- 连接池复用 TCP 连接,减少握手与认证开销;客户端实例线程/协程安全才可共享。
- 释放时先停接收新任务,再排空在途请求,最后关连接。
原理流程
- 启动段:按配置创建异步 DB 引擎/会话工厂、Redis 客户端、HTTP 客户端。
- 挂
app.state,依赖工厂从状态取实例。 - 服务期间各请求复用池内连接。
- 关闭段:先关闭缓存/HTTP 客户端,再关闭 DB 引擎,等待在途连接归还。
代码或图示
@asynccontextmanager
async def lifespan(app: FastAPI):
engine = create_async_engine(settings.db_url, pool_size=10, max_overflow=20)
app.state.engine = engine
app.state.redis = Redis.from_url(settings.redis_url)
yield
await app.state.redis.aclose()
await engine.dispose()
async def get_db(request: Request):
async_session = AsyncSessionFactory(request.app.state.engine)
async with async_session as session:
yield session
常见误区
- 在依赖里每请求
create_engine:连接无法复用,句柄与内存泄漏。 - 关闭段直接
dispose()不等在途事务:可能截断未提交工作。
追问
- 同步连接池能挂 lifespan 吗?答:能,同步池在启动段创建、关闭段关闭,端点经线程池使用。
- 池大小怎么定?答:按 worker 数 × 每池连接 ≤ 数据库最大连接数,并压测验证。
04.7.15.3-042 lifespan 失败会怎样,启动检查怎么做?
一句话结论
启动段抛异常会导致应用启动失败:服务器终止启动流程,不进入服务状态;关闭段异常应被记录但尽量不阻断其他资源释放。上线前在启动段做依赖连通性检查(DB、Redis、下游),失败即快速暴露,而不是带着坏配置接流量。
概念解释
- 快速失败(fail-fast)优于带病启动:避免接流量后批量报错。
- 启动检查要设超时,防止依赖宕机时应用无限挂起。
原理流程
- 服务器进入 lifespan,执行启动段。
- 初始化资源并做连通性探活,带超时。
- 任一致命依赖不可用则抛错,启动中止。
- 关闭段逐资源释放,异常记录后继续后续清理。
代码或图示
@asynccontextmanager
async def lifespan(app: FastAPI):
try:
await check_db_connection(timeout=3)
await check_redis(timeout=3)
except Exception:
raise # 快速失败,不接流量
yield
# 关闭段各资源独立兜底
常见误区
- 启动段静默吞掉连接异常:应用启动成功但所有接口 500。
- 探活不设超时:依赖无响应时进程卡在启动阶段,编排层误判。
追问
- 非核心依赖启动失败要中止吗?答:按业务分级,可降级依赖允许启动并在运行期熔断。
- 容器怎么感知启动失败?答:进程退出码非零,编排层据此判定启动失败并重试/告警。
04.7.15.3-043 子应用与多应用之间 lifespan 如何叠加?
一句话结论
挂载子应用(app.mount("/sub", sub_app))后,父应用 lifespan 先进入启动段,再触发子应用 lifespan;关闭时子应用先退出清理,父应用后退出。各应用资源独立初始化与释放,避免父应用提前关闭子应用依赖的连接。
概念解释
- ASGI lifespan 沿挂载链逐层进入与退出,顺序与请求中间件类似但独立。
- 父应用状态与子应用状态互不共享,跨应用资源需在外部构造后注入。
原理流程
- 服务器触发父应用 lifespan 启动段。
- 父应用初始化共享资源后,子应用 lifespan 依次进入。
- 服务请求期间各应用独立运行。
- 关闭时子应用先退出清理,父应用最后释放共享资源。
代码或图示
api_app = FastAPI(lifespan=api_lifespan)
admin_app = FastAPI(lifespan=admin_lifespan)
app.mount("/api", api_app)
app.mount("/admin", admin_app)
常见误区
- 父应用关闭段先 dispose 共享引擎,子应用关闭时再用已关闭资源:顺序颠倒导致报错。
- 以为子应用继承父应用的依赖与状态:挂载后是独立 ASGI 应用实例。
追问
- 多 worker 进程各自跑一次 lifespan 吗?答:是,每个 worker 进程独立初始化一份资源,池容量要按进程数折算。
- 全局单例(如分布式锁)怎么处理?答:用外部存储(Redis/DB)协调,不依赖进程内单例。
04.7.15.3-044 StreamingResponse 解决什么问题,与直接返回大列表有何差异?
一句话结论
StreamingResponse 接收异步生成器或同步迭代器,逐块把响应体写给客户端,避免一次性把全量数据载入内存;直接返回大列表要先构造完整模型列表、完成序列化再发送,内存峰值与首字节延迟都更高。
概念解释
- 流式响应适合导出、日志推送、大文件与 SSE。
- 生成器产出的每块经 ASGI
http.response.body消息分块发送。
原理流程
- 端点返回
StreamingResponse(content_iterable, media_type=...)。 - 路由层不再套用响应模型序列化,直接迭代内容。
- 每块就绪即
sendbody 消息,不等全部完成。 - 迭代结束发送结束标志,关闭连接。
代码或图示
from fastapi.responses import StreamingResponse
@app.get("/export")
async def export():
async def rows():
async for batch in query_batches():
yield batch.model_dump_json() + "\n"
return StreamingResponse(rows(), media_type="application/x-ndjson")
常见误区
- 流式生成器里再做重同步阻塞:逐块产出期间仍可能卡住循环。
- 流式响应绕过响应模型校验:字段约束需要在生成数据时自行保证。
追问
- 同步生成器能用于
StreamingResponse吗?答:可以,框架会在线程池调度迭代;阻塞型迭代需评估对线程池的占用。 - 流式响应怎么设文件名?答:通过
Content-Disposition头(见文件下载题)。
04.7.15.3-045 SSE 端点如何用 StreamingResponse 实现?
一句话结论
SSE(Server-Sent Events)用 StreamingResponse,media_type="text/event-stream",生成器按 SSE 格式产出 data: ...\n\n 分块;需关闭缓冲(响应头 Cache-Control: no-cache、必要时 X-Accel-Buffering: no),并配合心跳保活与断连检测。
概念解释
- SSE 是 HTTP 单向长连接,浏览器
EventSource自动重连。 - 每条消息以双换行结束,事件类型、ID、重试间隔可按协议字段设置。
原理流程
- 端点返回流式响应,声明 event-stream 类型。
- 生成器循环读取事件源(队列、Redis pub/sub、数据库轮询)。
- 按
data: {payload}\n\n格式 yield,中间穿插心跳注释行。 - 客户端断开或生成器结束,连接关闭并清理订阅。
代码或图示
@app.get("/events")
async def events():
async def stream():
while True:
msg = await event_queue.get()
yield f"data: {msg}\n\n"
yield ": ping\n\n" # 心跳注释
await asyncio.sleep(0)
return StreamingResponse(
stream(),
media_type="text/event-stream",
headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
)
常见误区
- 反向代理默认缓冲响应:SSE 被攒批,客户端收不到实时消息,需在代理层关闭缓冲。
- 忘记处理断连:生成器持续向已关闭连接写数据,出现异常与资源泄漏。
追问
- SSE 与 WebSocket 怎么选?答:单向推送选 SSE(HTTP、自动重连、跨域友好);双向实时通信选 WebSocket。
- 消息 ID 与重连怎么实现?答:SSE 协议字段
id:记录最后事件 ID,客户端重连带上Last-Event-ID。
04.7.15.3-046 文件下载响应怎么设置 Content-Disposition 与类型?
一句话结论
文件下载用 FileResponse(支持大文件与发送文件头)或 StreamingResponse;Content-Disposition 设为 attachment; filename="...",中文名需 RFC 5987 编码(filename*=UTF-8''...);media_type 按文件类型设置,Content-Length 由文件大小确定。
概念解释
FileResponse内部使用sendfile/流式读取,避免把整个文件读入内存。- 内联(
inline)与附件(attachment)区别在于浏览器是展示还是下载。
原理流程
- 校验文件存在与访问权限。
- 构造
FileResponse(path, filename=..., media_type=...)。 - 响应头写入
Content-Disposition与长度。 - 服务器流式发送文件块,结束后关闭连接。
代码或图示
from fastapi.responses import FileResponse
from urllib.parse import quote
@app.get("/download/{name}")
def download(name: str):
safe_name = quote(name)
headers = {"Content-Disposition": f"attachment; filename*=UTF-8''{safe_name}"}
return FileResponse(path=f"uploads/{name}", headers=headers,
media_type="application/octet-stream")
常见误区
- 中文名直接写进
filename:部分浏览器乱码,需编码为filename*。 - 用
open().read()把文件载入内存再返回:大文件内存峰值高,应走FileResponse。
追问
- 怎么限制路径穿越?答:对文件名做白名单/规范化,禁止
..与绝对路径拼接。 - 文件不存在返回什么?答:捕获
FileNotFoundError抛 404,避免 500 堆栈。
04.7.15.3-047 流式生成器抛异常时响应状态与行为是什么?
一句话结论
响应头(start 消息)一旦发出,状态码与头已无法更改;生成器在首块之后抛错,客户端收到的是被中断的响应体,无法再换成完整错误 JSON。因此流式端点要在开始流式输出前完成所有校验,流式过程中的错误通过错误消息块、状态通道或事后查询任务 ID 表达。
概念解释
- HTTP 响应先发送 start(状态码+头),再逐块发 body;start 之后状态码冻结。
- 异常会中断生成器迭代,连接被关闭,客户端解析到不完整 body。
原理流程
- 端点先完成鉴权、参数校验与资源准备。
- 校验通过才返回流式响应并发出 start。
- 流式过程出错:生成器抛错,body 截断。
- 错误信息需在流式协议内另设错误块,或由任务状态接口兜底。
代码或图示
@app.get("/stream")
async def stream():
# 流式开始前完成校验
await authorize()
validate_input()
async def gen():
try:
async for item in source():
yield item
except Exception as e:
yield f'data: {{"error": "{type(e).__name__}"}}\n\n'
return StreamingResponse(gen(), media_type="text/event-stream")
常见误区
- 首块之后才发现鉴权失败:此时无法回退为 401 JSON 响应。
- 流式异常只在服务端记日志,不通知客户端:前端表现为连接静默中断。
追问
- 流式前的校验异常走不走异常处理器?答:走,端点返回流式响应之前抛出的异常仍由处理器生成正常错误响应。
- 怎么给流式响应加错误边界?答:生成器内 try/except,把错误编码成协议内消息块。
04.7.15.3-048 背压与客户端断开对流式生成器有什么影响?
一句话结论
客户端断开后,继续向连接写数据会触发发送异常;生成器应感知取消并停止产出、释放订阅与资源。背压方面,下游消费慢会让生成队列堆积,需用有界队列与流量控制,避免内存被慢客户端拖垮。
概念解释
- ASGI 连接断开后,
send/迭代会收到取消或连接关闭异常。 - 慢客户端导致的积压是服务端内存风险,要限制缓冲深度。
原理流程
- 客户端断开,服务器向端点协程发出取消。
- 生成器在下一次
yield/await 处收到CancelledError。 finally段取消订阅、关闭队列、释放资源。- 消费慢时由有界队列反压生产者,超出容量则丢弃或降级。
代码或图示
async def gen():
try:
async for item in source():
yield item
finally:
await source.unsubscribe(request_id)
常见误区
- 用无界队列缓存推送消息:慢客户端把服务端内存吃满。
- 断连后不取消上游订阅:后台任务继续消费并推送,资源长期泄漏。
追问
- 怎么检测连接是否还活着?答:观察发送是否抛错/取消信号,WebSocket 用心跳与 close 帧辅助判断。
- 背压策略有哪些?答:有界队列、拒绝新消息、降采样、按客户端分组限流。
04.7.15.3-049 WebSocket 端点的握手与消息循环怎么写?
一句话结论
WebSocket 端点声明为 async def ws(websocket: WebSocket),先 await websocket.accept() 完成握手,再进入 receive_text()/receive_json() 与 send_text()/send_json() 循环;循环在收到断开消息或异常后退出,最后关闭连接。
概念解释
- WebSocket 是长连接双向通道,握手经 HTTP
Upgrade完成。 - 消息分文本、二进制与关闭帧;接收调用阻塞等待下一帧。
原理流程
- 路由匹配到 WebSocket 端点,构造
WebSocket对象。 - 端点调用
accept()完成握手,服务端返回 101 切换协议。 - 循环接收消息,处理后回写响应。
- 断开或异常时退出循环,
close()并清理上下文。
代码或图示
from fastapi import WebSocket
@app.websocket("/ws/{room}")
async def ws_endpoint(websocket: WebSocket, room: str):
await websocket.accept()
try:
while True:
data = await websocket.receive_json()
await websocket.send_json({"echo": data})
except WebSocketDisconnect:
pass
finally:
await websocket.close()
常见误区
- 没
accept()就读写:未握手的连接不能收发消息。 - 循环内做同步阻塞重计算:卡住整个循环线程,影响其他 WebSocket 连接。
追问
WebSocketDisconnect什么时候抛出?答:收到关闭帧或连接断开,receive_*抛出该异常。- 二进制消息怎么收?答:
receive_bytes()/receive()按消息类型判断。
04.7.15.3-050 WebSocket 连接如何做集中登记与广播?
一句话结论
维护进程内连接登记表(如 dict[room_id, set[WebSocket]]),握手成功后加入、断开后移除;广播时遍历房间连接逐个发送,发送失败的连接就地摘除。多进程部署需借助 Redis pub/sub 等外部通道跨进程转发。
概念解释
- 登记表是进程内状态,多 worker 之间互不可见。
- 发送失败要容错:单条坏连接不能中断整组广播。
原理流程
- 握手成功,把连接按房间/用户 ID 加入登记表。
- 收到消息后查表,向目标连接集合推送。
- 发送抛错则从集合移除该连接。
- 断连退出循环时兜底移除,防止残留。
代码或图示
from collections import defaultdict
rooms: dict[str, set[WebSocket]] = defaultdict(set)
@app.websocket("/ws/{room}")
async def ws(websocket: WebSocket, room: str):
await websocket.accept()
rooms[room].add(websocket)
try:
while True:
msg = await websocket.receive_json()
for conn in list(rooms[room]):
try:
await conn.send_json(msg)
except Exception:
rooms[room].discard(conn)
finally:
rooms[room].discard(websocket)
常见误区
- 多 worker 下只维护进程内表:跨房间消息发不到其他进程的连接。
- 遍历集合时直接增删:迭代中修改集合报错,先复制快照再处理。
追问
- 跨进程广播怎么做?答:连接登记到外部映射,消息经 Redis pub/sub 分发给各进程后本地投递。
- 并发写登记表需要锁吗?答:单事件循环下协程切换点少,但多线程/线程池访问要加锁保护。
04.7.15.3-051 WebSocket 鉴权在握手阶段如何完成?
一句话结论
握手阶段从查询参数、请求头或 Cookie 提取凭证,在 accept() 前校验;失败则 close(code=4010) 或按协议拒绝握手。WebSocket 端点同样可用依赖注入,但浏览器原生 WebSocket 不能自定义请求头,常见做法是 query 参数带 token 或握手 Cookie。
概念解释
- 握手仍是 HTTP 请求,
websocket.headers、websocket.cookies可读。 - 鉴权通过后再
accept(),避免未授权连接占用长连接资源。
原理流程
- 连接到达 WebSocket 端点,读取凭证来源。
- 校验 token/会话,失败则关闭连接。
- 校验通过
accept(),进入消息循环。 - 后续消息可结合用户 ID 做权限校验。
代码或图示
@app.websocket("/ws")
async def ws(websocket: WebSocket, token: str | None = None):
user = await authenticate(token) if token else None
if user is None:
await websocket.close(code=4010)
return
await websocket.accept()
# 消息循环……
常见误区
- 先
accept()再鉴权:未授权连接已握手,占用连接且日志表现为正常建立。 - 把长期 token 放 URL 查询参数:易进访问日志,建议短期一次性票据或 Cookie。
追问
- 浏览器 WebSocket 能带 Authorization 头吗?答:原生 API 不支持自定义头,需借助子协议、Cookie 或 query 票据。
- 鉴权失败状态码怎么约定?答:自定义 WebSocket close code(如 4010),并在握手层返回 HTTP 拒绝也可。
04.7.15.3-052 WebSocket 断连、重连与心跳如何处理?
一句话结论
服务端在消息循环退出时清理登记表;客户端按指数退避重连;服务端定期发心跳 ping/pong,长时间无响应判定死连接并关闭。代理层有空闲超时,心跳间隔要小于代理超时阈值。
概念解释
- 网络中断不一定触发服务端立刻感知,半开连接靠心跳探测。
- 重连后需要恢复订阅状态(房间、最后消息位置)。
原理流程
- 服务端定时 ping,等待 pong;超时未收到则关闭连接。
- 连接断开,清理本地登记与订阅。
- 客户端检测断开,退避重连并重新握手、恢复状态。
- 消息断点靠消息 ID/offset 补齐。
代码或图示
import asyncio
async def heartbeat(websocket: WebSocket):
while True:
await asyncio.sleep(15)
await websocket.send_json({"type": "ping"})
常见误区
- 心跳间隔大于 Nginx/网关空闲超时:连接被代理先切断,表现为随机掉线。
- 重连不恢复订阅:用户重连后收不到房间消息。
追问
- ping/pong 帧与应用层心跳选哪个?答:协议层 ping/pong 由实现支持,应用层心跳更直观,注意间隔统一。
- 死连接怎么回收?答:心跳超时关闭,登记表兜底移除。
04.7.15.3-053 如何限制请求体大小?超大上传怎么兜底?
一句话结论
FastAPI/Starlette 框架本身不内置全局请求体大小开关,需要在接入层(Nginx client_max_body_size、API 网关)限制,或在应用内读取 body 时按字节计数截断;大文件走分片上传、对象存储直传或流式落盘,不在内存中攒全量。
概念解释
- 大小限制应在最外层先挡一层,应用内再做业务校验。
- 上传内存消耗取决于读取方式:临时文件落盘比整包读入内存可控。
原理流程
- 代理层配置请求体上限,超限直接拒绝。
- 应用内读取上传时按大小累计,超限抛 413。
- 大文件流式写入临时文件/对象存储,分片可续传。
- 校验通过后归档,清理临时文件。
代码或图示
client_max_body_size 20m;
@app.post("/upload")
async def upload(file: UploadFile):
if file.size and file.size > MAX_SIZE:
raise HTTPException(status_code=413, detail="文件过大")
常见误区
- 只在应用层校验大小:超大 body 已占用内存/带宽才被拒绝,代理层才是第一道防线。
- 大文件整包读入内存:并发上传时内存峰值叠加,易触发 OOM。
追问
- 413 状态码含义?答:Payload Too Large,表示请求体超过服务端允许大小。
- 分片上传怎么设计?答:客户端分块编号上传,服务端合并校验哈希,支持断点续传与失败重传。
04.7.15.3-054 请求体超限触发什么异常,默认限制是多少?
一句话结论
Starlette 读取 body 本身没有公开的默认大小常量;超限行为取决于代理层配置与应用读取方式。业务层可用 Request.headers.get("content-length") 预检,读取过程中累计字节并在超限时抛 HTTPException(413)。框架没有“默认拒绝 N MB”的内置开关(待确认:验证点:所用 Starlette 0.4x 版本是否提供 body 大小限制参数)。
概念解释
content-length可被伪造或缺失(分块传输),预检只能作为初筛。- 真正兜底要在流式读取时计数。
原理流程
- 读取
content-length头做快速预检。 - 分块读取 body,累计已读字节。
- 超过阈值即停止读取并抛 413。
- 响应经异常处理器统一返回。
代码或图示
MAX_BODY = 10 * 1024 * 1024
@app.middleware("http")
async def body_limit(request: Request, call_next):
length = request.headers.get("content-length")
if length and int(length) > MAX_BODY:
return JSONResponse(status_code=413, content={"detail": "body too large"})
return await call_next(request)
常见误区
- 假设
content-length必然存在且可信:分块传输或伪造头会绕过预检。 - 超限后不中断读取:连接继续接收全量 body,浪费带宽与内存。
追问
- 怎么读流时计数?答:
request.stream()逐块读取,累加len(chunk),超限 break 并抛错。 - 框架层面有没有现成中间件?答:可自行实现纯 ASGI/中间件计数,或依赖网关与代理限制。
04.7.15.3-055 文件上传的内存与磁盘临时文件策略怎么选?
一句话结论
UploadFile 小文件先留在内存,超过阈值后写入磁盘临时文件;应用应按业务限制大小、类型与数量,流式落盘到受控目录,处理完删除临时文件;大文件与高并发上传优先对象存储直传或分片,避免应用节点磁盘与内存成为瓶颈。
概念解释
- 临时文件路径与阈值由底层实现决定,不要把临时目录当长期存储。
- 文件类型校验不能只信扩展名,要校验内容魔数与声明类型。
原理流程
- 上传解析成
UploadFile,读取文件名、大小、类型。 - 校验大小、扩展名/魔数、业务权限。
- 读取临时文件,转存到持久化存储(本地目录/对象存储)。
- 处理结束清理临时文件,记录元数据。
代码或图示
@app.post("/avatar")
async def avatar(file: UploadFile = File(...)):
if file.size and file.size > 2 * 1024 * 1024:
raise HTTPException(413, "头像不超过 2MB")
content = await file.read()
await save_to_storage(content, file.filename)
return {"ok": True}
常见误区
- 信任客户端传入的文件名:直接拼路径会导致路径穿越,需重命名存储键。
- 只校验扩展名:改后缀的可执行文件/脚本会被放过。
追问
- 临时文件什么时候清理?答:请求结束后由框架/系统回收,重要文件应尽早转存并删除临时副本。
- 并发上传磁盘满怎么办?答:限制并发上传数、监控磁盘水位、大文件走外部对象存储。
04.7.15.3-056 用 asyncio.Semaphore 限制并发下游调用怎么写?
一句话结论
创建 asyncio.Semaphore(n) 作为共享实例,每个下游调用前 async with semaphore: 申请许可,退出时释放;信号量限制同时在途的协程数,防止下游被突发并发打满。信号量在 lifespan 或模块级创建,不要每请求新建。
概念解释
- 信号量计数可用许可,获取减一、释放加一;为零后新协程排队等待。
- 与线程池限额配合:应用层并发上限不能超过下游承载能力。
原理流程
- 按下游容量创建信号量(n 为最大并发)。
- 调用方进入
async with semaphore,拿到许可才发请求。 - 下游响应或异常退出块,许可释放。
- 排队协程依次获取许可。
代码或图示
import asyncio
downstream_sem = asyncio.Semaphore(20)
async def call_downstream(item):
async with downstream_sem:
async with httpx.AsyncClient() as client:
return await client.get(f"https://api/{item}")
常见误区
- 在请求处理函数内
Semaphore(n):每次新建互不约束,起不到限流作用。 - 信号量许可数大于下游连接/线程上限:保护失效,下游先被压垮。
追问
- 信号量等待要设超时吗?答:要,
asyncio.timeout包裹等待段,避免协程无限排队。 - 多个下游各自用什么?答:每个下游独立信号量,按其容量分别配置。
04.7.15.3-057 全局限流(按用户/IP)与信号量限流有何区别?
一句话结论
信号量限制“同时在途并发数”,是资源保护;按用户/IP 的限流限制“单位时间请求速率”(如令牌桶/漏桶),是访问频率治理。两者维度不同,常同时使用:速率限流挡突发高频,并发信号量保护下游与线程池。
概念解释
- 速率算法:固定窗口、滑动窗口、令牌桶、漏桶;可按用户、IP、接口维度分组。
- 分布式限流需要外部存储(Redis)计数,单机限流只保护本进程。
原理流程
- 入口识别主体(用户 ID/IP/路由)。
- 速率限流检查窗口配额,超限返回 429。
- 进入处理后,并发信号量控制在途下游调用数。
- 计数与许可在请求结束后更新/释放。
代码或图示
from collections import defaultdict, deque
import time
buckets: dict[str, deque] = defaultdict(deque)
def rate_limit(key: str, limit: int, window: float):
now = time.monotonic()
q = buckets[key]
while q and now - q[0] > window:
q.popleft()
if len(q) >= limit:
return False
q.append(now)
return True
常见误区
- 用信号量做“每分钟请求数”:语义不符,信号量不按时间窗口计数。
- 多进程各自计数:分布式下配额被放大 N 倍,需 Redis 集中计数。
追问
- 429 响应要带什么头?答:
Retry-After与剩余配额提示,便于客户端退避。 - 单机限流够不够?答:单进程部署可起步,多实例必须集中存储配额。
04.7.15.3-058 信号量与连接池上限、数据库连接数如何对齐?
一句话结论
并发上限链路:入口在途请求数 → 下游调用信号量 → 客户端连接池 → 数据库连接池 → 数据库最大连接数,逐层不能倒挂;总连接数按 worker 进程数折算,任一上层上限都不应超过下层承载。
概念解释
- 每个 worker 进程一份池,数据库连接总数 = worker 数 × 每进程池大小。
- 信号量要小于等于对应池容量,避免排队等待连接。
原理流程
- 统计部署 worker 数与每进程池配置。
- 计算下游/数据库可承受的每进程并发。
- 信号量取值不超过池可用余量,留出备用连接。
- 压测验证各层水位与等待队列长度。
代码或图示
在途请求 → 信号量(n) → HTTP/DB 连接池(size+overflow) → DB max_connections
约束:worker × (size+overflow) ≤ DB max_connections
常见误区
- 信号量开得比连接池大:协程排队等连接,延迟抬升但不会立刻报错。
- 忘记乘 worker 数:按单进程估算,多实例把数据库连接打满。
追问
- 连接池等待超时怎么配?答:获取连接设短超时,快速失败而不是长期挂起。
- 怎么观测对齐是否合理?答:看池等待数、连接占用率、下游拒绝率与 P99 延迟。
04.7.15.3-059 客户端断开后服务端协程如何感知与取消传播?
一句话结论
客户端断开后,ASGI 服务器会向在途端点协程发出取消;协程在下次 await 处收到 CancelledError,沿调用栈展开。未完成的下游调用、后台任务与订阅需要在取消路径上一并清理,避免“客户端早走、服务端还在跑”。
概念解释
- 取消是协作式的:协程在 await 点响应,纯 CPU 段不会被立即打断。
- 后台任务(
BackgroundTasks/任务组子任务)随父任务取消传播。
原理流程
- 连接关闭,服务器触发端点协程取消。
- 取消沿调用栈进入各 await 点,子任务一并收到取消。
- 各层
finally释放连接、关闭订阅、归还资源。 - 协程结束,连接资源回收。
代码或图示
@app.get("/slow")
async def slow():
try:
async with asyncio.timeout(30):
return await long_running_task()
except asyncio.CancelledError:
await cleanup_partial_work()
raise # 取消必须继续向上传播
常见误区
- 以为客户端断开服务端立刻停止:取消只在 await 点生效,长 CPU 段需自行检查取消标志。
- 后台任务与请求解绑不彻底:请求结束后任务仍持有连接与内存。
追问
- 怎么在端点内判断是否被取消?答:捕获
CancelledError做清理,或检查任务取消状态。 - 已发出的副作用要回滚吗?答:按业务幂等与事务边界处理,取消不等于自动回滚数据库事务。
04.7.15.3-060 CancelledError 为什么不能吞掉,清理逻辑放哪里?
一句话结论
吞掉 CancelledError 会让取消无法传播:任务看似结束但调用方以为已取消,资源与状态悬挂;清理逻辑放在 finally、上下文管理器退出段与 yield 依赖退出段,清理完必须重新抛出取消,不把它转成普通返回或 Exception。
概念解释
- Python 3.8+
CancelledError继承BaseException,except Exception不会捕获它。 - 清理段要避免再阻塞或抛新异常,否则取消链被二次打断。
原理流程
- 取消进入协程,
CancelledError在当前 await 点抛出。 try/finally与async with退出段执行资源释放。- 清理完成后
raise重新抛出,取消继续向上传播。 - 任务组/服务器收到取消,回收协程与连接。
代码或图示
async def worker():
session = acquire()
try:
await do_work(session)
except asyncio.CancelledError:
await session.rollback()
raise
finally:
release(session)
常见误区
except BaseException后不重抛:取消被吃掉,任务悬挂在事件循环里。- 清理段 await 无超时操作:清理自身被挂住,取消流程卡死。
追问
- 为什么
except Exception抓不到CancelledError?答:它继承BaseException,与普通业务异常区分开。 - 后台任务如何保证不被误取消?答:用独立任务组/外部队列托管,与请求生命周期解绑。
本节高频题
async def与def端点调度差异(001、002)- AnyIO 线程池容量与排队(004、007)
- 同步端点与同步依赖调度位置(006、008)
- 阻塞调用拖垮事件循环的机理与识别(010、011、012)
- 阻塞库清单与安全迁移(014、015、018)
anyio/uvloop/asyncio.timeout(019、020、021)- 超时与取消时的资源释放(022、059、060)
- 中间件执行顺序与
BaseHTTPMiddleware开销(024、025、027) - 纯 ASGI 中间件写法与
receive/send包装(028、030) HTTPException与统一错误响应(033、034、035、037)- 中间件异常绕过处理器(032、038)
lifespan资源初始化与释放(039、040、041)StreamingResponse与 SSE(044、045、047)- WebSocket 握手、登记广播与鉴权(049、050、051)
- 请求体大小限制与上传策略(053、054、055)
- 信号量限流与连接数对齐(056、057、058)