一、为什么一个函数声明方式就能影响性能
很多刚接触FastAPI的同学都会遇到一个很微妙的问题:在写路由的时候,到底是该用async def还是普通的def?
有人觉得无所谓,反正都能跑。有人听说async def性能好,于是所有接口一律用异步写法。还有人看到官方文档里说“如果你用的是def,FastAPI会自动把它放到线程池里运行”,于是觉得同步写法也没问题。
但实际情况是,这两个看似差不多的写法,背后运行的机制完全不一样。选错了,可能不会立刻报错,而是在某个高并发场景下,你的服务突然变得很慢,甚至卡死。而且这种问题往往很难排查,因为它不崩溃、不报错,只是响应时间悄悄变长了。
要弄明白这个问题,我们先从最基础的地方开始。
二、先搞清楚一个核心概念:同步和异步
在Python的世界里,有两种代码执行方式。
第一种是同步执行。代码一行接一行地跑,上一行没跑完,下一行绝对不开始。比如你写了一个time.sleep(5),那这5秒钟里,整个程序就停在这里,什么都干不了。
第二种是异步执行。你写了一个await asyncio.sleep(5),这5秒钟里,程序不会干等着,它会把控制权交出去,让事件循环去处理其他任务。等5秒到了,再回来继续往下跑。
这个“把控制权交出去”的动作,就是异步的核心。只有真正支持异步操作的任务,比如网络请求、文件读写、数据库查询,才能享受到这种“不等待”的好处。
那FastAPI的async def和def,到底和这个有什么关系?
三、FastAPI里async def和def的真实运行方式
先看一个最简单的例子。
# 技术栈:FastAPI + Uvicorn
from fastapi import FastAPI
import asyncio
app = FastAPI()
# 写法一:async def
@app.get("/async-hello")
async def async_hello():
await asyncio.sleep(1)
return {"message": "async hello"}
# 写法二:def
@app.get("/sync-hello")
def sync_hello():
import time
time.sleep(1)
return {"message": "sync hello"}
这两段代码看起来差不多,但执行方式完全不同。
对于async def,FastAPI会直接把它注册到事件循环里。当这个路由被调用时,FastAPI会像正常异步函数一样去await它。上面的await asyncio.sleep(1),意味着这1秒里,事件循环是自由的,可以同时处理其他请求。
而对于普通的def,FastAPI会在事件循环之外,把它丢给一个线程池去执行。也就是说,FastAPI拿一个工作线程去跑这个函数,等线程跑完了,再把结果返回给客户端。这个过程中,主事件循环并没有被阻塞。
那问题来了:既然同步函数也能被放到线程池里,不会阻塞事件循环,那性能是不是就差不多?
这个问题的答案,要看你的接口里到底做了什么操作。
四、线程池不是万能的:它也有上限和调度成本
FastAPI默认使用AnyIO的线程池,默认容量是40个线程。也就是说,当你把同步函数丢进线程池时,最多同时有40个线程在跑这些同步任务。
如果你有50个请求同时打到某个def路由上,每个请求都要执行一个耗时2秒的同步操作,那么前40个请求会立刻拿到线程开始执行,剩下10个请求就只能排队等。等到有线程空出来,才能继续执行。
这就出现了一个很现实的问题:当你的并发请求数量超过线程池容量时,超出部分就会排队等待。而这些等待,是实实在在的响应延迟。
再看异步版本。如果你用async def,并且里面的操作是真正的异步操作(比如await asyncio.sleep或await httpx.AsyncClient),那么100个请求同时进来,事件循环会同时“挂着”这100个任务。每个任务都在等自己的I/O完成,没有谁在傻等,也没有线程池的限制。所以100个请求的耗时,基本等于最慢的那一个请求的耗时。
这就是性能差距的来源。
五、混用不当带来的隐形陷阱
这里有个很常见也很容易踩的坑:在async def里面写了同步的阻塞操作。
比如这样:
# 技术栈:FastAPI + Uvicorn
from fastapi import FastAPI
import time
app = FastAPI()
@app.get("/bad-case")
async def bad_case():
# 这行代码是同步阻塞操作,会卡住整个事件循环
time.sleep(3)
return {"message": "done"}
表面上,这是一个async def,看起来是异步的。但里面用了time.sleep(3),这是一个同步阻塞操作。这个操作发生时,事件循环没法做别的事,因为它不是异步的,不会交出控制权。于是这3秒里,你整个服务的所有请求全部暂停响应。如果并发量再大一点,后面的请求就会排队,形成雪崩效应。
这个坑之所以隐蔽,是因为从代码上看,你已经用了async def,觉得“我已经做了异步处理”。但实际上,异步的关键不在于函数声明,而在于函数内部的操作是否真的支持异步。
反过来,在def里面写异步代码,同样会出问题。
# 技术栈:FastAPI + Uvicorn
from fastapi import FastAPI
import asyncio
app = FastAPI()
@app.get("/bad-case-2")
def bad_case_2():
# 这里在同步函数里使用异步操作,不会真正异步执行
asyncio.run(some_async_operation())
return {"message": "done"}
asyncio.run()会创建一个新的事件循环并运行异步操作,然后关闭它。这样做不仅没有任何并发优势,反而因为每次都要新建和销毁事件循环,带来额外的开销。而且如果这个函数被多个线程同时调用,每个线程都会创建自己的事件循环,资源消耗会非常严重。
六、用具体示例看看性能差异到底有多大
为了更直观地理解,我们写一个简单的基准测试。这里用一个模拟的耗时操作来对比。
# 技术栈:FastAPI + Uvicorn
from fastapi import FastAPI
import asyncio
import time
import httpx
app = FastAPI()
# 模拟一个耗时的外部调用,比如访问数据库或第三方API
async def mock_io_async():
await asyncio.sleep(2) # 模拟I/O等待2秒
def mock_io_sync():
time.sleep(2) # 模拟I/O等待2秒,但这是同步阻塞
@app.get("/async-io")
async def async_io():
await mock_io_async()
return {"status": "ok"}
@app.get("/sync-io")
def sync_io():
mock_io_sync()
return {"status": "ok"}
现在假设我们用测试工具并发发送20个请求到这两个接口。
对于/async-io,20个请求几乎同时进入事件循环。每个请求都在await asyncio.sleep(2)处挂起,事件循环继续处理下一个请求。所以20个请求全部完成,总耗时大约就是2秒多一点。
对于/sync-io,20个请求进来,FastAPI把它们丢进线程池。线程池默认最多40个线程,所以20个请求都能立刻获得线程。每个线程独立执行time.sleep(2)。因为线程是并行运行的,所以总耗时大约也是2秒多一点。
那如果并发数量变成50个呢?
对于/async-io,50个请求同时挂起,依然在2秒左右全部完成。
对于/sync-io,50个请求同时进来,但线程池只有40个线程。前40个请求立刻拿到线程开始执行,剩下10个请求在队列里等待。等到有线程空出来,这10个请求才能开始。所以总耗时大约是:第一批40个线程跑完(2秒),然后第二批10个线程再跑(2秒),总共约4秒。
这就是区别。当并发量超过线程池容量时,同步路由的响应时间会呈线性增长,而异步路由则不会。
七、那到底应该怎么选?一个实用的判断标准
看到这里,你可能已经明白了一些。但具体到实际开发中,该怎么决定用哪个?
这里给你一个非常简单的判断方法。
第一,如果你的路由函数内部,包含任何I/O操作,比如读文件、写数据库、调外部API、访问缓存,而且这个操作有异步版本(比如httpx.AsyncClient、asyncpg、aiofiles),那么请用async def。
第二,如果你的路由函数内部,全部都是CPU密集型的计算,比如循环求和、图像处理、加解密运算,那么用def更合适。因为CPU计算无法被异步化,你在async def里做CPU计算,反而会阻塞事件循环,影响其他请求。
第三,如果你的路由函数内部,既没有I/O操作,也没有复杂的CPU计算,只是一个简单的逻辑判断、参数校验、返回固定数据,那么用def就挺好。这种操作执行速度极快,放在线程池里也不会造成问题。
我们来看一个比较典型的混合场景。
# 技术栈:FastAPI + Uvicorn
from fastapi import FastAPI
import asyncio
import time
app = FastAPI()
# 正确的异步写法:I/O操作使用异步版本
@app.get("/correct-async")
async def correct_async():
# 模拟数据库查询,使用异步方式
data = await fake_db_query_async()
return {"data": data}
# 正确的同步写法:CPU计算使用同步方式
@app.get("/correct-sync")
def correct_sync():
# 模拟CPU密集型计算
result = heavy_cpu_task()
return {"result": result}
# 模拟异步数据库查询
async def fake_db_query_async():
await asyncio.sleep(1)
return [1, 2, 3]
# 模拟CPU密集型计算
def heavy_cpu_task():
# 一个比较耗时的计算过程
total = 0
for i in range(1_000_000):
total += i
return total
在这个示例中,/correct-async用了异步I/O,/correct-sync用了同步CPU计算,两条路径都处理得很妥当。
八、FastAPI官方是怎么解释这个机制的
你可能注意到,FastAPI官方文档里有一句话:“如果你在路径操作函数中使用了普通的def,FastAPI会把它放到线程池中运行,这样不会阻塞事件循环。”
这句话本身没错,但它容易让人产生一种误解:好像def和async def性能差不多。实际上,def虽然不会阻塞事件循环,但线程池是有容量限制的。而且,如果你在def里做的是I/O操作,那每个线程都在等待I/O完成,这其实是在浪费线程资源。因为你花了40个线程,却只做了40个并发的I/O等待,而异步方式只需要一个事件循环,就能管理数千个并发的I/O等待。
所以,官方的说明是在解释“不会卡死事件循环”,而不是在说“性能一样好”。
九、几个实际开发中的注意事项
第一个注意事项:不要在async def里用time.sleep。如果你非要延迟,用await asyncio.sleep。这个区别,就是整个服务卡死和正常运转的区别。
第二个注意事项:不要在def里用asyncio.run。这个写法不仅没有意义,还会带来额外的线程和事件循环创建开销。如果你有异步函数要在同步上下文里调用,用asyncio.run确实可以,但只适用于那些不会被并发调用的场景。在路由里,这不是好主意。
第三个注意事项:如果你的项目里既有同步的数据库驱动(比如psycopg2),又有异步的接口,那要小心了。同步数据库调用会阻塞线程,而异步接口期望的是非阻塞操作。这时候你可能需要把同步数据库操作封装成def路由,或者使用异步驱动(比如asyncpg)。
第四个注意事项:混合使用async def和def是完全没有问题的,只要各自的函数内部逻辑符合对应模式。FastAPI本身对此没有限制。真正的问题是,你在一个异步函数里做了同步操作,或者在同步函数里做了异步操作。
十、一个完整的示例:混合路由的调度演示
我们来写一个稍微完整一点的示例,展示一个服务中同时存在两种路由的情况。
# 技术栈:FastAPI + Uvicorn
from fastapi import FastAPI
import asyncio
import time
from concurrent.futures import ThreadPoolExecutor
app = FastAPI()
# 模拟一个外部I/O服务,用异步方式
async def external_io_async(seconds: int):
await asyncio.sleep(seconds)
return f"async io done in {seconds}s"
# 模拟一个外部I/O服务,用同步方式
def external_io_sync(seconds: int):
time.sleep(seconds)
return f"sync io done in {seconds}s"
# 异步路由:适合I/O密集型场景
@app.get("/async-io")
async def async_io(seconds: int = 2):
result = await external_io_async(seconds)
return {"message": result}
# 同步路由:适合CPU密集型场景
@app.get("/sync-cpu")
def sync_cpu(n: int = 1000000):
start = time.time()
total = sum(range(n))
cost = time.time() - start
return {"message": f"cpu done in {cost:.4f}s", "total": total}
# 同步路由:如果非要处理I/O,也可以放线程池,但要接受并发上限
@app.get("/sync-io")
def sync_io(seconds: int = 2):
result = external_io_sync(seconds)
return {"message": result}
这个示例中,/async-io适合高并发的I/O操作,/sync-cpu适合耗时的计算任务,/sync-io虽然能跑,但并发能力受限于线程池大小。
十一、为什么说选型本质上是识别“阻塞点”
其实整个问题的核心,归结到一个概念:阻塞点。
所谓阻塞点,就是代码中会让当前执行环境停下来等待的操作。比如time.sleep、requests.get、file.read(),这些都是阻塞点。当事件循环遇到阻塞点时,它会停下来,等阻塞点完成才能继续。
而异步操作不会产生阻塞点。await asyncio.sleep会让出控制权,await httpx.AsyncClient.get也会让出控制权。这些操作在等待期间,事件循环可以继续处理其他事情。
所以,你在写路由时,真正要问自己的是:这个函数里有没有阻塞点?
如果有,而且你用了async def,那么这个阻塞点就会卡住事件循环,影响所有请求。这时候你应该用def,让FastAPI把它丢到线程池,隔离这个阻塞点。
如果没有阻塞点,也就是你的函数完全由异步I/O和轻量级计算组成,那么用async def,能获得最好的并发性能。
十二、文章总结
FastAPI中async def和def的选型,本质上是对阻塞点的管理。
async def适合那些内部全部都是异步I/O操作的函数,它们不会阻塞事件循环,能支持非常高的并发量。代价是,如果你不小心在里面混入了同步阻塞操作,整个服务都会被拖垮。
def适合那些内部包含同步阻塞操作(比如CPU计算、同步I/O)的函数。FastAPI会把它放到线程池里执行,避免阻塞事件循环。但线程池容量有限,当并发请求超过容量时,多余请求会排队等待,响应时间会变长。
正确的做法是:I/O密集型用async def,CPU密集型用def,不要在异步函数里写同步阻塞代码,也不要在同步函数里强行跑异步逻辑。
把这个原则记在心里,你在写FastAPI路由时,就不会再纠结了。
评论
围绕“FastAPI路由里async def与def究竟该如何选型?讲透框架背后线程池调度的运行机制,避开混用不当引发的性能倒退与隐性调度陷阱”参与讨论