一、为什么一个函数声明方式就能影响性能

很多刚接触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路由时,就不会再纠结了。