一、问题背景

事情是这样的。我们有个商品详情聚合接口 /api/v1/product/{id},逻辑很简单:拿到商品ID后,依次调用三个下游服务——商品基础信息、库存服务、价格服务,然后把结果拼起来返回。代码大概长这样:

@app.get("/api/v1/product/{pid}")
def get_product(pid: int):
    base = requests.get(f"{BASE_URL}/product/{pid}", timeout=2).json()
    stock = requests.get(f"{STOCK_URL}/stock/{pid}", timeout=2).json()
    price = requests.get(f"{PRICE_URL}/price/{pid}", timeout=2).json()
    return {"base": base, "stock": stock, "price": price}

单看逻辑没毛病,三个下游各自响应时间在 80~150ms 之间,串行加起来 300ms 左右,感觉"还行"。但上线后压测直接暴雷:QPS 卡在 320 上不去,P99 延迟 1.8s,CPU 利用率却只有 15%。原因也很典型——requests 是同步阻塞的,FastAPI 虽然支持 def 路由跑在线程池里,但线程池默认只有 40 个 worker,每个请求要占住一个线程等三次网络 IO,线程池瞬间被打满,后面的请求全在排队。

这篇文章就是记录我怎么用 asyncio 把这个接口救回来的。

二、环境与版本

先交代下环境,避免版本差异导致的坑:

  • Python 3.11.6
  • FastAPI 0.109.2
  • uvicorn 0.27.1(--workers 4,--loop uvloop)
  • httpx 0.26.0
  • uvloop 0.19.0
  • 压测工具:wrk 4.2.0,wrk -t8 -c200 -d60s
  • 机器:4C8G 容器,下游服务为同集群 mock 服务,固定 100ms 延迟

注意 uvicorn --loop uvloop 这个参数,在 Linux 上能把事件循环性能再拉一截,后面数据对比会提到。

三、方案设计

改造思路分三层:

第一层,把阻塞 IO 换成异步 IO。 requests 换成 httpx.AsyncClient,路由从 def 改成 async def,让请求真正跑在事件循环上而不是线程池里。

第二层,把串行变并发。 三个下游服务之间没有依赖关系,完全可以并发调用,用 asyncio.gather 一把发出去。这一步理论上能把 300ms 的串行耗时压到 150ms 左右(取最慢的那个)。

第三层,控制并发度。 全并发不是没有代价的,200 并发压进来,每个请求发 3 个下游调用,瞬间就是 600 个连接打向下游。所以要用 Semaphore 限制同时在途的下游请求数,配合 httpx 的连接池参数,避免把下游打挂也避免本地 fd 耗尽。

四、核心实现

先看改造后的完整代码:

import asyncio
import httpx
from fastapi import FastAPI, HTTPException

app = FastAPI()

# 全局单例 client,复用连接池
client: httpx.AsyncClient | None = None

# 限制同时在途的下游请求数,保护下游
downstream_sem = asyncio.Semaphore(100)

@app.on_event("startup")
async def startup():
    global client
    client = httpx.AsyncClient(
        timeout=httpx.Timeout(2.0, connect=0.5),
        limits=httpx.Limits(
            max_connections=200,
            max_keepalive_connections=100,
            keepalive_expiry=30.0,
        ),
    )

@app.on_event("shutdown")
async def shutdown():
    await client.aclose()

async def fetch(url: str) -> dict:
    async with downstream_sem:
        resp = await client.get(url)
        resp.raise_for_status()
        return resp.json()

@app.get("/api/v1/product/{pid}")
async def get_product(pid: int):
    try:
        base, stock, price = await asyncio.gather(
            fetch(f"{BASE_URL}/product/{pid}"),
            fetch(f"{STOCK_URL}/stock/{pid}"),
            fetch(f"{PRICE_URL}/price/{pid}"),
        )
    except httpx.HTTPError as e:
        raise HTTPException(status_code=502, detail=f"downstream error: {e}")
    return {"base": base, "stock": stock, "price": price}

几个关键点解释一下:

  1. AsyncClient 必须是全局单例。 千万不要在每个请求里 async with httpx.AsyncClient() 新建,那样连接池复用完全失效,每次都要重新建 TCP 连接,性能比同步还差。这是最常见的坑。

  2. limits 参数要认真配。 max_connections=200 是总连接上限,max_keepalive_connections=100 是空闲保活连接数。压测 200 并发、每请求 3 个下游调用,理论上峰值需要 600 连接,我们故意配成 200 让连接排队复用,实测反而更稳——因为下游 mock 服务本身也扛不住 600 并发。

  3. Semaphore(100) 是第二道闸。 连接池限制的是"连接数",Semaphore 限制的是"同时在途请求数",两者配合才能既保护下游又不让请求无限堆积。这个值我们压测调过 50/100/200,100 是吞吐和延迟的平衡点。

  4. 超时要分层。 connect=0.5 秒是建连超时,总超时 2 秒。下游服务正常 100ms,建连超过 500ms 基本就是网络问题了,早点失败早点释放资源。

五、踩坑与优化

改造过程中踩了几个坑,值得单独说。

坑一:asyncio.gather 默认不会取消其他任务。 如果三个调用里有一个抛异常,gather 默认会把异常往上抛,但另外两个协程还在跑,不会自动取消。生产环境里这意味着异常请求会继续占着连接。后来改成 gather(..., return_exceptions=True) 再统一处理,或者用 asyncio.TaskGroup(3.11+ 支持,异常时会自动取消同组任务)。我们最终用了 TaskGroup:

async def get_product(pid: int):
    try:
        async with asyncio.TaskGroup() as tg:
            t1 = tg.create_task(fetch(f"{BASE_URL}/product/{pid}"))
            t2 = tg.create_task(fetch(f"{STOCK_URL}/stock/{pid}"))
            t3 = tg.create_task(fetch(f"{PRICE_URL}/price/{pid}"))
        return {"base": t1.result(), "stock": t2.result(), "price": t3.result()}
    except* httpx.HTTPError as eg:
        raise HTTPException(status_code=502, detail=str(eg.exceptions[0]))

坑二:on_event 已被标记废弃。 FastAPI 0.109 里 @app.on_event("startup") 还能用但会告警,官方推荐换成 lifespan。我们项目里暂时没改,新项目建议直接用 lifespan 上下文管理器。

坑三:uvloop 的收益比想象中大。 一开始没加 --loop uvloop,QPS 是 1650;加上之后跑到 2100,提升 27%。这个参数几乎零成本,Linux 环境强烈建议加上。

坑四:日志里的 await 陷阱。 有同事在 fetch 里加了同步的 logging.info 写文件,结果高并发下日志锁成了新瓶颈。异步环境里要么用 logging 的 QueueHandler,要么干脆别在热路径打日志。

六、效果数据

同一台机器、同样 200 并发、60 秒压测,before/after 对比如下:

指标 同步版(requests) 异步版(httpx+uvloop) 提升
QPS 320 2100 6.5x
P50 延迟 620ms 95ms -85%
P99 延迟 1800ms 240ms -87%
CPU 利用率 15% 68% -
线程数 ~45(线程池打满) 1(事件循环) -

补充一组消融数据,方便看每一步的贡献:仅把 requests 换成 httpx 同步调用(不改 async),QPS 到 380;改成 async def + 串行 await,QPS 到 720;加 asyncio.gather 并发,QPS 到 1650;最后加 uvloop,QPS 到 2100。也就是说并发编排贡献了最大的一块,uvloop 是锦上添花。

七、总结

这次改造的核心其实就三句话:把阻塞 IO 换成异步 IO、把无依赖的串行调用改成并发、用信号量和连接池两道闸控制下游压力。asyncio 不是银弹,它解决的是 IO 密集型场景下的线程浪费问题,如果下游是 CPU 密集或者有同步阻塞库(比如某些老 SDK),该用线程池还是得用 run_in_executor 包一层。

另外提醒一句:异步化之后一定要重新压测下游。我们同步版 QPS 320 的时候下游毫无压力,异步版 QPS 2100 意味着下游要扛 6300 QPS 的调用量,如果下游没做限流和扩容,你只是把瓶颈从自己这挪到了别人那。Semaphore 那个 100 就是这么定下来的——不是拍脑袋,是根据下游实测承载能力反推的。