两条路由,各取一个依赖,各自用 FastAPI 新出的 max_concurrency 把并发卡到 1。一条先要资源 A 再要 B,另一条先要 B 再要 A。同时各发一个请求,两边都没回来。不是慢,我让它跑了八秒,它本来能一直坐下去。
FastAPI 0.163.0 在 2026 年 11 月 14 日发布,只带了一个特性:Depends(dependency, max_concurrency=N),给单个依赖设并发上限。我在它进 PyPI 那天就装上了(现在跑的是三天后发的 0.163.2),一上午都在试着把它弄坏,而不是只读文档里那新增的一段。
它到底做了什么
max_concurrency 把一个依赖包进信号量。同时调用这个依赖的次数超过上限,多出来的调用就等着,不占工作线程,也不让事件循环任务空转。
我搭了个 FastAPI 应用,一个异步依赖睡 0.2 秒,用 httpx.AsyncClient 直接打 ASGI 应用并发发 20 个请求(不走网络,所以数字反映的是依赖自身的并发,不是套接字噪声)。0.829 秒差不多正好是四批 0.2 秒——20 个请求过一道 5 的闸门,排成四波。我重跑了三次,墙钟时间没跑出 0.82–0.84 秒。这个上限说到做到。
同步依赖(def,不是 async def)表现一样。FastAPI 把它们放进线程池跑,信号量是在调用交给线程池之前拿的,不是之后——所以一个 max_concurrency=5 的同步依赖,面对同样 20 个请求,峰值也是 5 个并发线程,同样约 0.83 秒,尽管 Starlette 自己的线程池本来乐意一次跑满 20 个。
上限属于 Depends() 调用,不属于函数
文档直接写了这一点,就一行,第一遍读我大概会跳过:“一个新的 Depends() 对象会创建一个独立的上限,即使依赖函数相同。”我想要这句话背后的数字。
我把同一个依赖、同一个 max_concurrency=5,写在两条写法完全相同的路由上。同时各发 10 个并发请求,一共 20 个:结果是十,不是五。同样的调用敲两遍,你得到的是两道独立的、各为五的闸门,不是一道共享的五。想要一道闸门,唯一的办法是把 Depends() 对象建一次然后复用——赋给一个变量或 Annotated 别名,在所有需要这个上限的地方导入它。如果你在给数据库连接之类的东西设上限,却在每条碰数据库的路由上内联写这个限制,那你什么都没限住,你把上限乘以了路由数量。
它拒绝什么
- max_concurrency=0 → ValueError: max_concurrency must be a positive integer or None
- max_concurrency=-1 → 同上
- max_concurrency=2.5 → 同上
- max_concurrency="5" → 同上
- max_concurrency=True → 同上
最后一个让我意外。True 在 Python 里等于 1,本来是个完全合理的上限,但检查写的是 type(self.max_concurrency) is not int,而 type(True) 是 bool,不是 int。FastAPI 拒绝它,尽管 bool 是 int 的子类、1 == True。max_concurrency=None 是唯一退出限制的方式,它也是默认值——不写这个参数就完全不设限,悄无声息。
这是每进程上限,不是每应用上限
文档也标了这一点:“每个工作进程各自应用自己的上限。”我用 uvicorn --workers 2、max_concurrency=4 跑,对真实套接字发 20 个真实 HTTP 请求,把两个工作进程的起止时间记到同一个文件里,好看清实际的重叠:requests=20,命中的不同工作进程 pid=2,每 pid 计数={1078: 16, 1077: 4},跨所有进程的峰值并发=8。
八,对着配置的四,因为两个工作进程各跑自己的 Python 解释器、各有自己的信号量,互相不知道对方存在。如果你保护的是外部、跨进程共享的资源——比如数据库服务器上的连接池——4 个进程配 4 的上限,实际就是 16。我还注意到 uvicorn 没把 20 个请求平均分给两个进程(16 对 4),这本身是个小意外,但不是这个版本该负责的。
失败不会漏掉槽位
我做了个总是抛异常的依赖,上限 3,并发发 12 个请求。12 个全抛了,符合预期。然后我立刻对同一个仍在上限内、仍在失败的依赖再发 3 个,担心某个协程是通过异常而不是正常返回退出的,槽位可能被一直占着。它们 0.052 秒就回来了——大约一个依赖超时的量,三个并行跑完。没漏,没有越积越长的永久卡死队列。
死锁
回到开头。两个依赖 A 和 B,都是 yield 生成器(所以 FastAPI 在整个请求生命周期里持有它们的槽位,不只是函数执行那一刻),都卡在 max_concurrency=1。同时给 /ab 和 /ba 各发一个请求。/ab 抓住 A,/ba 抓住 B——两者相差不到 10 毫秒。然后 /ab 等 B,B 被 /ba 占着;/ba 等 A,A 被 /ab 占着。谁都不放,直到拿到对方。我让它对着超时跑了八秒,从没解开;没有内部死锁检测,所以生产里这就是两个挂住的请求(而且取决于你服务器自己的超时设置,是两个线程或任务卡着,直到外部有东西掐断连接)。
这正是 FastAPI 自己的文档从“需要不止一个资源的依赖”那个链接指向的场景,只是没明说它是一个两行就能复现的真实死锁。如果你有两条路由需要同样的两个受限资源,在所有地方按同样的顺序获取,或者别在一条请求路径上给超过一个共享资源设上限。
没人排队时它也要花钱
我把 max_concurrency 设成 1000——测试里永远够不到的数——然后给 3000 次廉价空操作依赖调用计时,每批 50 个,对比完全不设限的同样调用:每次调用大约多 45 微秒,或者说多出约五分之一,纯粹是信号量的记账开销,哪怕它从没真正限过任何东西。对数据库调用无所谓,但如果你想把某个本来就在个位数微秒里跑完的东西包起来,可能值得知道。
从外面看它
没有公开指标告诉你一道 max_concurrency 闸门有多满。也没什么拦着你读一个:上限作为私有 _concurrency 属性挂在 Depends() 对象上,通过 .get_semaphore() 暴露一个 AnyIO 信号量。.value 给空闲槽位,.statistics().tasks_waiting 给队列深度。加载前:free_slots=3 tasks_waiting=0;加载中,6 个请求:free_slots=0 tasks_waiting=3。这是个没有兼容性保证的私有属性,所以我不会基于它上线仪表盘,除非接受它可能在下一个 FastAPI 版本坏掉。压测时本地调试,它准确告诉了我想要的东西。
我中途搞错的地方
我第一版“失败会不会漏槽位”的测试,把后续请求发给了另一个健康的依赖,而不是同一个失败的依赖。就算失败依赖自己的信号量永久卡死,它也会报成功,因为我查的是一个跟我要找的 bug 毫无关系的资源。我是在跑之前重读脚本时发现的,不是跑出错误结果之后——但正是这类错误,会产出一个干净、有说服力、完全错误的“没发现泄漏”。
自己跑一遍
建虚拟环境,装 fastapi==0.163.2、uvicorn[standard]、httpx,存成 app.py,用单 worker 跑(两个 worker 会各给各的信号量,把 bug 藏起来)。两个依赖各睡 0.2 秒代表真实的连接/初始化成本,都 yield,都卡 1。用两个终端同时 curl /ab 和 /ba,看两边都不回来。我在真实套接字上确认过,不只是进程内:两个 curl 都撞上 6 秒超时,退出码 124。如果两个依赖里没有那 0.2 秒延迟,竞态窗口太窄,两个独立的 curl 进程落不进去——死锁需要真正的重叠,不只是倒霉的请求顺序。
拿它怎么办
在把它加进任何碰真实连接池的东西之前,我会回头翻每条用到它的路由,grep 那个依赖上的 Depends(。两处以上命中就意味着两个以上上限,不是一个——我会把它抽成一个模块级对象再导入,就像 FastAPI 自己文档里的 DBDep 例子那样;要不是我先把它弄坏了,我大概会纳闷那个例子干嘛费劲起个命名别名。
工作进程数的除法同样重要,而且容易漏,因为 API 在你设数字的地方什么都不警告:四个 worker 把 max_concurrency=5 变成对面真实的天花板二十。
真正让我睡不着的,是那个顺序相反的死锁,因为代码评审看不出来,一个用户测正常路径也看不出来。它第一次出现,是生产里两个碰同样两个资源的请求落得足够近的时候,从外面看就像服务器无缘无故挂了。如果一条路由需要两个受限资源,我会在发布任何一条之前,把所有路由的获取顺序写下来一次。
热门跟贴