罗罗编程学习记录
本页内容 展开查看

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 小任务。

原理流程

  1. 路由处理器解析参数与依赖后,调用 fastapi.routing.run_endpoint_function。
  2. 函数对象是协程函数(iscoroutinefunction 为真)时直接 await,运行在事件循环线程。
  3. 否则经 starlette.concurrency.run_in_threadpool 进入 anyio.to_thread.run_sync,由 AnyIO 线程池承载。
  4. 线程内返回值再交回事件循环做响应模型序列化。

代码或图示

@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 中:端点、路径参数、依赖、安全校验函数各自被独立判定。
  • 被装饰器包装的函数要保证协程标记正确透传,否则可能被误判进线程池。

原理流程

  1. 请求进入路由后,先解析依赖树,逐个收集可调用对象。
  2. 每个可调用对象经协程判定:是协程函数则直接 await,否则进线程池。
  3. 端点同样按上述规则执行。
  4. 所有结果汇总后进入响应模型校验与序列化。

代码或图示

# 判定口径(框架内部等价逻辑)
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 对象不能跨线程长期持有,请求结束后上下文失效。

原理流程

  1. 路由层发现端点是普通函数,调用 run_in_threadpool。
  2. anyio.to_thread.run_sync 从线程池取工作线程执行函数。
  3. 阻塞期间事件循环不被占用,可接受新连接、处理其他协程。
  4. 函数返回后 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 与下游连接数约束。

原理流程

  1. 每次 run_in_threadpool 先申请一个令牌。
  2. 有空闲令牌则创建/复用工作线程执行;无令牌则协程挂起排队。
  3. 函数结束归还令牌,唤醒排队请求。
  4. 线程复用由 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 提交线程时会复制当前上下文变量,线程内可读,但线程内修改不会回写协程侧。

原理流程

  1. 应用启动时创建的连接池、配置对象挂在进程内存中,各线程/协程共享引用。
  2. 请求进入时依赖解析产生请求级对象,通过函数参数传入端点。
  3. 线程执行期间读取复制过来的上下文变量;写操作留在线程内。
  4. 请求结束,请求级对象随垃圾回收失效。

代码或图示

# 共享:进程级连接池
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 项独立判定协程性。
  • 同步依赖返回的值会被原样传给下游依赖或端点。

原理流程

  1. 解析依赖树,收集所有依赖可调用对象。
  2. 协程依赖在事件循环内 await;普通依赖经线程池执行。
  3. 依赖结果按声明顺序注入,供后续依赖与端点使用。
  4. 任一依赖抛错即中断链路并进入异常处理。

代码或图示

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 密集”。
  • 两者都属于把阻塞工作移出事件循环,但承担的瓶颈类型不同。

原理流程

  1. 识别代码是 IO 阻塞还是 CPU 密集。
  2. IO 阻塞(驱动调用、序列化小任务)用线程池。
  3. CPU 密集(大计算、图像/密码批量哈希)考虑进程池或独立任务队列。
  4. 在线程/进程内执行完毕后把结果交回协程。

代码或图示

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”不会把它的同步依赖也拉进事件循环。

概念解释

  • 调度判定发生在每个可调用对象上,签名决定执行位置。
  • 依赖生成器的退出清理段跟随其被调度的同一位置执行。

原理流程

  1. 依赖解析先跑同步依赖:进线程池得到 session。
  2. 结果传回事件循环,注入异步端点参数。
  3. 端点 await 异步 IO。
  4. 响应生成后,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 端点,等待时挂起协程。

原理流程

  1. 同步驱动建立 TCP 连接,查询后阻塞读响应。
  2. def 端点把这段阻塞隔离在工作线程。
  3. 事件循环同时调度其他协程,连接等待不占循环。
  4. 驱动响应到达工作线程,查询结果返回路由层。

代码或图示

# 同步驱动:端点用 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 让出点的阻塞都会冻结调度。
  • 症状与“下游数据库慢”相似,但根因是本机循环被占,下游指标可能并不高。

原理流程

  1. 协程进入阻塞调用(同步 HTTP、time.sleep、大哈希、同步 IO)。
  2. 阻塞期间循环无法处理就绪协程、定时器与新连接事件。
  3. 其他请求的响应推迟到阻塞返回后才被调度。
  4. 积压连接占满服务端与下游连接池,连锁超时。

代码或图示

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 监听,协程挂起。
  • 阻塞调用没有让出点,循环的下一步就绪协程要等当前函数返回后才可见。

原理流程

  1. 循环从就绪队列取协程执行。
  2. 协程进入同步阻塞:线程在内核态/用户态等待,不返回循环。
  3. 新连接、socket 可读、定时器到期等事件堆积在循环层未处理。
  4. 阻塞返回后循环批量处理积压请求,延迟呈突刺。

代码或图示

正常:协程 await IO → 让出循环 → 调度其他协程 → IO 就绪后唤醒
阻塞:协程进入同步等待 → 循环停住 → 其他请求全部排队 → 阻塞返回后批量补发

常见误区

  • 以为有 GIL 就一定多线程并行:事件循环自身是单线程调度,阻塞即停摆。
  • 把阻塞误判成“下游慢”:本机循环阻塞时,下游 RTT 与错误率可能正常。

追问

  • 为什么协程等待 IO 不会阻塞循环?答:等待挂起并把控制权交回循环,事件由循环统一监听唤醒。
  • 阻塞 100ms 影响多大?答:并发量越高,积压请求越多,延迟按排队长度放大。

04.7.15.3-012 如何识别事件循环被阻塞(症状与监控指标)?

一句话结论

典型症状:单 worker 下所有接口同时变慢、CPU 未必打满、下游无明显慢查询;可观测指标看事件循环延迟(loop lag)、请求 P99 突刺、挂起协程数与线程池队列长度,配合 py-spy/tracemalloc/循环延迟探针定位阻塞点。

概念解释

  • 循环延迟:定时器被推迟执行的时长,是判断阻塞最直接的信号。
  • 线程池排队与事件循环阻塞是两类问题,要分别看队列长度与 loop lag。

原理流程

  1. 接入 loop lag 探针:周期调度 loop.call_later,测量回调实际延迟。
  2. 监控 P50/P95/P99 与并发在途请求数,对比下游耗时。
  3. 阻塞时段抓取进程栈(py-spy dump),定位停留在同步库帧的协程。
  4. 按库与路径归类,决定换异步实现或卸载线程池/进程池。

代码或图示

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 等待,不在计算并行。

原理流程

  1. 端点收到请求,识别任务为 CPU 密集(大循环、图像、压缩、批量哈希)。
  2. 不在循环线程内执行;提交进程池或任务队列。
  3. 队列 worker 独立进程消费,释放 GIL 竞争。
  4. 结果通过回调、轮询或消息通知前端。

代码或图示

# 不推荐:在请求线程里同步重算
@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 常只提供同步客户端,接入前要确认有无异步实现。

原理流程

  1. 审查端点与依赖体内的库调用。
  2. 标注同步 HTTP/驱动/客户端与重计算函数。
  3. IO 阻塞替换异步客户端或包线程池;CPU 密集拆进程/队列。
  4. 上线后用 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 密集经进程池或后台队列;卸载后仍要控制并发限额与超时,避免下游被打满。

概念解释

  • 卸载要在调用边界做,保留类型与异常透传。
  • 线程内对象不要跨请求共享,注意关闭资源。

原理流程

  1. 判定阻塞类型(IO 等待 / CPU 计算)。
  2. IO:优先异步客户端;无异步实现则线程池包裹。
  3. CPU:进程池或任务队列异步化。
  4. 设置超时与并发上限,捕获异常并记录,结果交回协程返回。

代码或图示

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 注册定时器事件,协程挂起,循环继续跑别的就绪任务。

原理流程

  1. 调用 asyncio.sleep(n):协程向循环注册定时器后挂起。
  2. 循环处理其他就绪协程与网络事件。
  3. 定时器到期,协程进入就绪队列被唤醒。
  4. 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 阻塞导致的超时与连接堆积链路是怎样的?

一句话结论

循环阻塞 → 在途请求无法被调度 → 客户端/上游网关超时重试 → 新连接持续进入 → 服务端连接表、线程池、下游连接池被占满 → 健康检查失败、整服务雪崩。阻塞是单点,堆积是链式放大。

概念解释

  • 每个在途请求占服务端一条连接、一份内存、可能一个下游连接。
  • 重试会把一次慢请求变成多次流量,放大下游压力。

原理流程

  1. 某端点进入阻塞调用,循环延迟抬升。
  2. 其他请求排队等待,响应时间拉长。
  3. 上游网关/客户端超时后重试,重复请求叠加。
  4. 连接与池位耗尽,健康探针超时,编排层摘除实例。

代码或图示

阻塞调用 → 循环停摆 → 请求排队 → 客户端超时重试 → 连接/池位耗尽 → 健康检查失败 → 实例下线

常见误区

  • 只给端点设业务超时,不限制整体在途并发:阻塞期新请求仍持续接入。
  • 重试次数无上限:雪崩期间重试把下游彻底打穿。

追问

  • 怎么打断这条链路?答:入口限流、连接与线程池上限、下游超时、重试退避与熔断、健康检查联动。
  • 阻塞恢复后堆积会自动消化吗?答:会逐步消化,但积压期超时请求已经流失,需观测尾延迟。

04.7.15.3-018 大 JSON 序列化与加密计算算阻塞吗,怎么拆?

一句话结论

算。大对象遍历、json.dumps、json.loads、批量密码哈希、压缩解压、正则回溯都占住 CPU,在循环线程内执行即阻塞;小任务可在线程池跑,大计算量拆到进程池或后台队列,并控制单次数据规模。

概念解释

  • 序列化是 CPU + 内存操作,响应模型校验也会遍历字段。
  • Pydantic 模型构造与校验同样有 CPU 成本,大 payload 时不可忽略。

原理流程

  1. 定位热点:按接口测量序列化与校验耗时占比。
  2. 小规模重计算用线程池卸载;大规模计算走进程池/任务队列。
  3. 限制单次入参/出参规模,分页或流式返回。
  4. 选择更快的序列化路径(按需 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)用于并发管理子任务的启动与取消传播。

原理流程

  1. ASGI 服务器选定事件循环后端,AnyIO 适配该后端。
  2. 同步端点/依赖经 anyio.to_thread 进线程池。
  3. 需要并发子任务时用 anyio.create_task_group()。
  4. 超时、锁、信号量等原语由 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 开发不一定启用。

原理流程

  1. uvicorn 按 loop 配置选择事件循环实现。
  2. 选用 uvloop 后,socket 注册、定时器、连接事件由 libuv 处理。
  3. 协程调度与回调路径更短,IO 密集 QPS 与延迟改善。
  4. 依赖若假定默认循环实现(如私有访问循环内部对象),可能不兼容。

代码或图示

# 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() 与嵌套超时计算剩余时间。

原理流程

  1. 在需要限制的调用段进入超时上下文。
  2. 内部等待事件超过剩余时限即触发超时异常。
  3. 超时向上传播,触发取消与资源清理。
  4. 下游 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 可能被二次取消,清理动作要短而稳。

原理流程

  1. 超时或断连触发取消,协程收到 CancelledError。
  2. 沿调用栈展开,执行各层 finally 与上下文退出。
  3. yield 依赖在响应/取消后逆序执行清理。
  4. 清理完成后取消继续向上传播;客户端侧不再等待响应。

代码或图示

@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,但对象不能直接共享。

原理流程

  1. 分析热点属于 IO 等待还是 CPU 占用。
  2. IO 阻塞选 to_thread,注意线程池限额。
  3. CPU 密集选 to_process 或外部任务队列,评估序列化与进程数。
  4. 结果返回协程,异常随调用边界重新抛出。

代码或图示

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、认证、日志等横切关注点都在链上。

原理流程

  1. 应用初始化时中间件被组装成嵌套调用链。
  2. 请求进入:从最外层依次向内,经过各中间件 dispatch/ASGI 段。
  3. 到达路由执行端点,生成响应。
  4. 响应回程:从内向外依次经过中间件 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 层与高阶层之间流转。

原理流程

  1. 请求到达,中间件构造 Request(scope, receive)。
  2. dispatch 执行前置逻辑(鉴权、日志、头处理)。
  3. 调用 call_next(request),内层链路在独立任务中执行,响应被收集成 Response。
  4. 中间件做后置改写后把响应发回外层。

代码或图示

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 流式行为的最新表述)。

原理流程

  1. 内层生成器逐块 send 响应消息。
  2. BaseHTTPMiddleware 桥接层经队列传递这些消息。
  3. 缓冲与任务调度引入延迟,首字节时间与推送节奏受影响。
  4. 纯 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 写法更省。

原理流程

  1. 请求进入基类 __call__,建立队列与任务组。
  2. 内层应用在任务中运行,消息经队列双向传递。
  3. 响应被组装成高阶对象后再转回 ASGI 消息发出。
  4. 每步都有协程切换与对象分配,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 与参数,内层处理单次连接。

原理流程

  1. 工厂构造中间件实例,保存 app 与配置。
  2. 连接到达,ASGI 服务器调用中间件 __call__(scope, receive, send)。
  3. 前置检查通过后转发给内层 app;包装 send 以观测/改写响应头。
  4. 按 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。
  • 重复同名头需要保留多个元组,不能简单覆盖。

原理流程

  1. 读取:从 scope headers 解析或用 Request(scope, receive).headers。
  2. 前置校验:校验不通过直接返回响应,不进内层。
  3. 改写响应:高阶层改 resp.headers;ASGI 层在 send_wrapper 中改 start 消息。
  4. 转发内层应用并回程发送。

代码或图示

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 分多块,末块带结束标志。

原理流程

  1. 包装 receive:拦截消息后要么直接转发,要么缓存并在重放时按原顺序返回。
  2. 包装 send:观测消息类型与头,追加逻辑后调用原始 send。
  3. 保证消息不丢、不改类型、不破坏 more_body 语义。
  4. 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 在协程与线程边界复制,适合承载请求级标识。

原理流程

  1. 最外层中间件进入时解析或生成请求 ID。
  2. 写入上下文变量,下游日志与依赖读取该变量。
  3. 响应头追加 X-Request-ID 返回客户端/上游。
  4. 请求结束上下文随请求销毁,不跨请求残留。

代码或图示

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 服务器。

原理流程

  1. 端点/依赖抛错 → 路由层按异常类型查找处理器。
  2. 处理器生成统一响应,沿中间件链回程。
  3. 中间件前置段抛错 → 跳过内层链路,直接向上冒泡。
  4. 未被捕获的异常由服务器转成 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 是主动抛出的受控错误。

原理流程

  1. 端点/依赖抛出 HTTPException。
  2. 路由层匹配到内置 http_exception_handler。
  3. 构造 JSONResponse({"detail": detail}),写入状态码与附加头。
  4. 响应沿链路回程。

代码或图示

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 作为最后兜底。
  • 处理器内可访问请求对象,记录上下文并生成统一结构响应。

原理流程

  1. 定义处理器:接收 Request 与异常实例。
  2. 提取错误信息,构造统一响应模型与状态码。
  3. 用装饰器或 add_exception_handler 绑定异常类型。
  4. 路由层抛错后查表调用对应处理器。

代码或图示

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 可能含敏感输入,回传前需筛选字段。

原理流程

  1. 请求参数解析/Pydantic 校验失败,抛出 RequestValidationError。
  2. 路由层调用注册的校验异常处理器。
  3. 遍历 exc.errors(),把 loc、msg、type 映射成统一字段。
  4. 返回 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 状态码、可选消息),注册对应处理器把它映射成统一响应;端点与服务层只抛业务异常,不在每层重复写响应格式。

概念解释

  • 业务异常分层:参数错误、鉴权失败、资源不存在、依赖故障等可各成类型。
  • 处理器集中做日志、错误码翻译与响应封装。

原理流程

  1. 定义 BizError(Exception),字段含 code、status_code、message。
  2. 服务/端点抛出具体业务异常。
  3. 处理器查表生成统一 JSON 响应。
  4. 未匹配的异常落到 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 类未预期异常对外只给通用提示,细节落日志。

原理流程

  1. 异常处理器按类型选择对外消息模板。
  2. 附加请求 ID 与字段问题(如有)。
  3. 服务端记录完整 traceback、异常链与请求上下文。
  4. 响应体过滤内部字段后发出。

代码或图示

{
  "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,或再包一层兜底中间件。

概念解释

  • 链路嵌套顺序:服务器 → 外层中间件 → 异常处理器注册点 → 内层中间件 → 路由。
  • 异常只在包裹范围内被对应层级捕获。

原理流程

  1. 请求穿过外层中间件进入应用。
  2. 应用内部异常由注册处理器接管并生成响应。
  3. 外层中间件自身代码抛错时,内层处理器尚未在调用栈上。
  4. 异常继续向上到服务器,转成默认 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 之后是关闭段,资源对象可在两段间共享。

原理流程

  1. 服务器启动,触发 ASGI lifespan 事件。
  2. 执行 lifespan 函数 yield 之前代码:建池、加载配置、预热。
  3. yield 挂起,应用开始接收请求。
  4. 收到关闭信号后恢复执行 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 是应用级共享命名空间,挂载单例资源供依赖读取。
  • 资源关闭顺序与初始化相反,避免先关被依赖的连接。

原理流程

  1. 定义上下文管理器函数,接收 app。
  2. 启动段创建资源,挂 app.state。
  3. yield 让出,应用服务请求。
  4. 关闭段逆序释放资源,异常记录后继续清理。

代码或图示

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 连接,减少握手与认证开销;客户端实例线程/协程安全才可共享。
  • 释放时先停接收新任务,再排空在途请求,最后关连接。

原理流程

  1. 启动段:按配置创建异步 DB 引擎/会话工厂、Redis 客户端、HTTP 客户端。
  2. 挂 app.state,依赖工厂从状态取实例。
  3. 服务期间各请求复用池内连接。
  4. 关闭段:先关闭缓存/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)优于带病启动:避免接流量后批量报错。
  • 启动检查要设超时,防止依赖宕机时应用无限挂起。

原理流程

  1. 服务器进入 lifespan,执行启动段。
  2. 初始化资源并做连通性探活,带超时。
  3. 任一致命依赖不可用则抛错,启动中止。
  4. 关闭段逐资源释放,异常记录后继续后续清理。

代码或图示

@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 沿挂载链逐层进入与退出,顺序与请求中间件类似但独立。
  • 父应用状态与子应用状态互不共享,跨应用资源需在外部构造后注入。

原理流程

  1. 服务器触发父应用 lifespan 启动段。
  2. 父应用初始化共享资源后,子应用 lifespan 依次进入。
  3. 服务请求期间各应用独立运行。
  4. 关闭时子应用先退出清理,父应用最后释放共享资源。

代码或图示

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 消息分块发送。

原理流程

  1. 端点返回 StreamingResponse(content_iterable, media_type=...)。
  2. 路由层不再套用响应模型序列化,直接迭代内容。
  3. 每块就绪即 send body 消息,不等全部完成。
  4. 迭代结束发送结束标志,关闭连接。

代码或图示

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、重试间隔可按协议字段设置。

原理流程

  1. 端点返回流式响应,声明 event-stream 类型。
  2. 生成器循环读取事件源(队列、Redis pub/sub、数据库轮询)。
  3. 按 data: {payload}\n\n 格式 yield,中间穿插心跳注释行。
  4. 客户端断开或生成器结束,连接关闭并清理订阅。

代码或图示

@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)区别在于浏览器是展示还是下载。

原理流程

  1. 校验文件存在与访问权限。
  2. 构造 FileResponse(path, filename=..., media_type=...)。
  3. 响应头写入 Content-Disposition 与长度。
  4. 服务器流式发送文件块,结束后关闭连接。

代码或图示

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。

原理流程

  1. 端点先完成鉴权、参数校验与资源准备。
  2. 校验通过才返回流式响应并发出 start。
  3. 流式过程出错:生成器抛错,body 截断。
  4. 错误信息需在流式协议内另设错误块,或由任务状态接口兜底。

代码或图示

@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/迭代会收到取消或连接关闭异常。
  • 慢客户端导致的积压是服务端内存风险,要限制缓冲深度。

原理流程

  1. 客户端断开,服务器向端点协程发出取消。
  2. 生成器在下一次 yield/await 处收到 CancelledError。
  3. finally 段取消订阅、关闭队列、释放资源。
  4. 消费慢时由有界队列反压生产者,超出容量则丢弃或降级。

代码或图示

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 完成。
  • 消息分文本、二进制与关闭帧;接收调用阻塞等待下一帧。

原理流程

  1. 路由匹配到 WebSocket 端点,构造 WebSocket 对象。
  2. 端点调用 accept() 完成握手,服务端返回 101 切换协议。
  3. 循环接收消息,处理后回写响应。
  4. 断开或异常时退出循环,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 之间互不可见。
  • 发送失败要容错:单条坏连接不能中断整组广播。

原理流程

  1. 握手成功,把连接按房间/用户 ID 加入登记表。
  2. 收到消息后查表,向目标连接集合推送。
  3. 发送抛错则从集合移除该连接。
  4. 断连退出循环时兜底移除,防止残留。

代码或图示

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(),避免未授权连接占用长连接资源。

原理流程

  1. 连接到达 WebSocket 端点,读取凭证来源。
  2. 校验 token/会话,失败则关闭连接。
  3. 校验通过 accept(),进入消息循环。
  4. 后续消息可结合用户 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,长时间无响应判定死连接并关闭。代理层有空闲超时,心跳间隔要小于代理超时阈值。

概念解释

  • 网络中断不一定触发服务端立刻感知,半开连接靠心跳探测。
  • 重连后需要恢复订阅状态(房间、最后消息位置)。

原理流程

  1. 服务端定时 ping,等待 pong;超时未收到则关闭连接。
  2. 连接断开,清理本地登记与订阅。
  3. 客户端检测断开,退避重连并重新握手、恢复状态。
  4. 消息断点靠消息 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 时按字节计数截断;大文件走分片上传、对象存储直传或流式落盘,不在内存中攒全量。

概念解释

  • 大小限制应在最外层先挡一层,应用内再做业务校验。
  • 上传内存消耗取决于读取方式:临时文件落盘比整包读入内存可控。

原理流程

  1. 代理层配置请求体上限,超限直接拒绝。
  2. 应用内读取上传时按大小累计,超限抛 413。
  3. 大文件流式写入临时文件/对象存储,分片可续传。
  4. 校验通过后归档,清理临时文件。

代码或图示

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 可被伪造或缺失(分块传输),预检只能作为初筛。
  • 真正兜底要在流式读取时计数。

原理流程

  1. 读取 content-length 头做快速预检。
  2. 分块读取 body,累计已读字节。
  3. 超过阈值即停止读取并抛 413。
  4. 响应经异常处理器统一返回。

代码或图示

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 小文件先留在内存,超过阈值后写入磁盘临时文件;应用应按业务限制大小、类型与数量,流式落盘到受控目录,处理完删除临时文件;大文件与高并发上传优先对象存储直传或分片,避免应用节点磁盘与内存成为瓶颈。

概念解释

  • 临时文件路径与阈值由底层实现决定,不要把临时目录当长期存储。
  • 文件类型校验不能只信扩展名,要校验内容魔数与声明类型。

原理流程

  1. 上传解析成 UploadFile,读取文件名、大小、类型。
  2. 校验大小、扩展名/魔数、业务权限。
  3. 读取临时文件,转存到持久化存储(本地目录/对象存储)。
  4. 处理结束清理临时文件,记录元数据。

代码或图示

@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 或模块级创建,不要每请求新建。

概念解释

  • 信号量计数可用许可,获取减一、释放加一;为零后新协程排队等待。
  • 与线程池限额配合:应用层并发上限不能超过下游承载能力。

原理流程

  1. 按下游容量创建信号量(n 为最大并发)。
  2. 调用方进入 async with semaphore,拿到许可才发请求。
  3. 下游响应或异常退出块,许可释放。
  4. 排队协程依次获取许可。

代码或图示

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)计数,单机限流只保护本进程。

原理流程

  1. 入口识别主体(用户 ID/IP/路由)。
  2. 速率限流检查窗口配额,超限返回 429。
  3. 进入处理后,并发信号量控制在途下游调用数。
  4. 计数与许可在请求结束后更新/释放。

代码或图示

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 数 × 每进程池大小。
  • 信号量要小于等于对应池容量,避免排队等待连接。

原理流程

  1. 统计部署 worker 数与每进程池配置。
  2. 计算下游/数据库可承受的每进程并发。
  3. 信号量取值不超过池可用余量,留出备用连接。
  4. 压测验证各层水位与等待队列长度。

代码或图示

在途请求 → 信号量(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/任务组子任务)随父任务取消传播。

原理流程

  1. 连接关闭,服务器触发端点协程取消。
  2. 取消沿调用栈进入各 await 点,子任务一并收到取消。
  3. 各层 finally 释放连接、关闭订阅、归还资源。
  4. 协程结束,连接资源回收。

代码或图示

@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 不会捕获它。
  • 清理段要避免再阻塞或抛新异常,否则取消链被二次打断。

原理流程

  1. 取消进入协程,CancelledError 在当前 await 点抛出。
  2. try/finally 与 async with 退出段执行资源释放。
  3. 清理完成后 raise 重新抛出,取消继续向上传播。
  4. 任务组/服务器收到取消,回收协程与连接。

代码或图示

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)