FastAPI异步编程怎么学?按5个阶段从基础到实战
简答:FastAPI异步编程不要一开始就堆数据库、任务队列和性能优化,建议先掌握Python的协程、await、Task和并发,再用FastAPI完成异步接口,最后补齐异步HTTP、数据库、测试与部署排查。最短主线是:能解释同步与异步的区别,能写一个可等待的接口,能避免阻塞调用,并能用异步测试验证结果。
定义:FastAPI异步编程,是在FastAPI接口中使用Python的async/await协程模型处理网络、数据库和文件等等待型操作,让程序在等待I/O时处理其他任务。
先看学习顺序:5个阶段对应5个可交付结果
如果你只想知道从哪里开始,可以按下面的顺序学习。FastAPI官方教程本身也是逐步构建接口,再进入高级用法;异步部分则重点解释async、await、协程以及def和async def的选择。
FastAPI官方教程适合建立接口基础;FastAPI并发与async/await文档适合解决异步函数选择问题。
| 阶段 | 重点 | 练习结果 | 通过标准 |
|---|---|---|---|
| 1 | Python异步基础 | 用asyncio运行多个等待任务 | 能解释协程、Task、await和并发 |
| 2 | FastAPI异步接口 | 完成一个查询接口 | 知道何时使用async def和def |
| 3 | 异步HTTP与数据库 | 聚合两个外部接口或查询数据库 | 不在异步函数中直接调用阻塞库 |
| 4 | 异步测试与异常处理 | 测试状态码、返回值和超时 | 能复现失败并定位等待环节 |
| 5 | 生产排查 | 记录耗时、超时、重试和连接池 | 能区分代码、依赖服务和网络线索 |
第一阶段:先弄懂async、await、协程和并发
Python官方将asyncio定义为使用async/await语法编写并发代码的标准库,常用于网络服务、数据库连接和任务队列等场景。这里的“异步”不等于“并行”:异步主要解决等待期间如何继续安排其他任务,并不自动让CPU计算同时运行。
先写一个最小练习,不要直接接入数据库:
import asyncio
async def work(name, delay):
await asyncio.sleep(delay)
return name
async def main():
tasks = [asyncio.create_task(work("A", 1)), asyncio.create_task(work("B", 1))]
print(await asyncio.gather(*tasks))
asyncio.run(main())
观察重点不是单次运行用了多少秒,而是理解三个动作:协程函数用async def声明;await等待一个可等待对象;Task把协程交给事件循环调度。练习成功的判据是,你能说明为什么两个等待任务可以交错执行,以及为什么普通CPU循环不会因为加上async就自动变快。
失败分支:如果你还分不清协程和Task,先不要学习数据库连接池。回到一个任务、两个任务、异常和取消任务四个小练习,直到能写出每一步的执行顺序。
第二阶段:掌握FastAPI中async def和def的选择
FastAPI的判断原则很直接:如果你使用的库支持await,例如异步HTTP客户端或异步数据库驱动,可以使用async def并在调用处await;如果依赖库不支持异步调用,则可以保留def。FastAPI会对路径操作函数和依赖进行相应处理,因此不要为了“看起来更快”把所有函数都改成async def。
一个最小异步接口可以这样写:
from fastapi import FastAPI
app = FastAPI()
@app.get("/health")
async def health():
return {"status": "ok"}
然后使用项目环境中的FastAPI命令启动开发服务,并访问自动生成的接口文档。官方教程示例使用fastapi dev启动开发环境,接口文档通常可从/docs查看,具体命令以当前安装版本的文档为准。
现象判断:接口只是返回内存中的字典,通常不需要await。低风险对照:先让接口返回固定JSON,再加入一个明确支持异步调用的函数。执行步骤:确认函数是async def、确认调用处有await、确认异常能在日志中出现。观察结果:接口能返回预期JSON且没有“协程未等待”提示。停止条件:不要在没有理解调用链的情况下,把同步数据库、文件或网络库直接塞进async def。
参考:FastAPI async/await官方说明和FastAPI第一步官方教程。
第三阶段:用异步HTTP和数据库完成真实接口
真实项目通常会等待外部接口或数据库。异步学习的关键不是把函数名改成async,而是让等待链条中的库真正支持异步调用。
异步HTTP客户端
HTTPX提供AsyncClient,官方示例使用async with httpx.AsyncClient()创建异步客户端,并通过await client.get()发起请求。建议在一组请求中复用客户端,避免在高频循环中反复创建客户端。
import httpx
from fastapi import FastAPI, HTTPException
app = FastAPI()
@app.get("/remote-status")
async def remote_status():
try:
async with httpx.AsyncClient(timeout=5.0) as client:
response = await client.get("https://example.com")
response.raise_for_status()
return {"status_code": response.status_code}
except httpx.HTTPError as exc:
raise HTTPException(status_code=502, detail="上游请求失败") from exc
排查时记录:请求开始时间、目标地址、超时设置、状态码、异常类型和是否发生重试。不要仅凭一次超时就断定是线路或服务器问题,可能还涉及DNS、连接建立、证书、上游处理时间或本地资源。
异步数据库
SQLAlchemy官方提供AsyncEngine和AsyncSession,并提醒单个AsyncSession不适合被多个并发任务共享;如果使用asyncio.gather等并发方式,通常应为每个任务准备独立的AsyncSession。异步数据库还要注意懒加载可能触发隐式I/O,因此应显式加载需要的数据。
学习顺序建议是:先完成单条查询,再加入事务,再学习连接池和超时,最后才做并发查询。成功判据是接口能正确提交或回滚事务,失败分支则检查驱动是否真正支持异步、Session生命周期是否清晰、是否把同一个Session传给了并发任务。
参考:HTTPX异步支持文档和SQLAlchemy异步I/O官方文档。
第四阶段:异步测试、超时与后台任务怎么学
异步代码必须通过测试验证等待、异常和并发行为。FastAPI官方异步测试示例使用pytest的AnyIO标记、HTTPX的AsyncClient和ASGITransport,测试函数本身也声明为async def。
import pytest
from httpx import ASGITransport, AsyncClient
@pytest.mark.anyio
async def test_health():
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
response = await client.get("/health")
assert response.status_code == 200
先测三个结果:正常返回、上游超时、上游返回错误状态。每次测试记录请求路径、输入、预期状态码、实际状态码和异常类型。若出现事件循环不一致,检查需要事件循环的客户端或连接对象是否在正确的异步生命周期内创建。
BackgroundTasks适合响应返回后仍需执行的小任务,例如写日志或发送通知;FastAPI官方同时提示,重量较大的后台计算可能需要独立的任务队列系统。不要把耗时、必须可靠完成或需要跨进程协调的任务,简单地塞进单个Web进程的后台任务。
停止条件:当任务需要持久化、重试、跨进程执行或多个服务共同消费时,先重新评估任务架构,而不是继续增加BackgroundTasks调用。
参考:FastAPI异步测试官方文档和FastAPI后台任务官方文档。
第五阶段:用一个小项目检验是否真的学会
建议做一个“业务状态聚合API”:接口接收一个业务编号,同时查询本地数据库和一个HTTP上游,最后返回统一结果。这个项目能覆盖异步编程中最容易出问题的路径。
- 先做同步版本:只返回固定数据,确认路由、参数校验和错误响应正常。
- 加入异步HTTP:使用AsyncClient访问一个明确的测试地址,增加超时和状态码处理。
- 加入异步数据库:完成查询、事务提交和异常回滚,明确AsyncSession的创建与关闭位置。
- 加入并发:只有在多个等待操作彼此独立时,才考虑使用asyncio.gather;如果一个结果依赖另一个结果,就保持顺序执行。
- 加入测试:覆盖成功、超时、上游错误、数据库异常和返回结构校验。
- 加入观测字段:记录总耗时、数据库耗时、上游耗时、状态码、异常类型和请求关联标识。
最终检查清单:
- 是否知道每个await等待的具体操作?
- 是否在async def中误用了阻塞式网络、数据库或文件库?
- 是否为外部请求设置了合理超时?
- 是否区分了连接失败、响应超时和业务错误?
- 是否让并发任务共享了不应共享的数据库Session?
- 是否能用异步测试稳定复现失败分支?
- 是否把CPU密集型任务误认为异步就能自动提速?
如果这些问题都能回答清楚,就可以从“会写异步语法”进入“能维护异步服务”的阶段。
常见问题:FastAPI异步编程学习中的3个分岔口
Python基础一般,能直接学FastAPI异步吗?
可以先学最小路径,但至少要会函数、异常、模块、类型提示和虚拟环境。若还不会这些内容,先用普通FastAPI接口练习请求参数与返回值,再补asyncio,学习成本会更低。
所有FastAPI接口都应该写async def吗?
不应该。是否使用async def取决于调用的库是否支持await以及接口内部是否包含等待型I/O。FastAPI官方明确说明,支持await的库适合在async def中调用;不支持异步调用的库可以使用def。
asyncio.gather是不是越多越好?
不是。只有任务相互独立、并发不会超过上游或数据库承受范围时,才适合并发执行。要同时考虑超时、限流、连接池、取消任务和异常处理,不能只看代码是否能运行。
异步接口变慢,应该先换线路吗?
不要直接归因。先记录接口总耗时、DNS解析、连接建立、TLS、上游响应、数据库查询和本地CPU时间,再用固定输入做对照。只有当代码与上游服务指标都排除后,网络连接质量才是进一步排查线索。
常见问题
FastAPI异步编程怎么开始学?
先学Python的asyncio、协程、await和Task,再写FastAPI异步接口,之后学习异步HTTP、异步数据库、测试和超时排查。不要一开始就同时学习所有框架扩展。
FastAPI中的async def和def有什么区别?
使用支持await的异步库时,通常使用async def并等待调用结果;使用不支持异步调用的库时,可以保留def。选择应以依赖库能力和接口内部操作为准。
异步接口为什么还会阻塞?
可能是async函数内部调用了同步网络库、数据库库、文件操作或CPU密集型代码,也可能是连接池、上游响应、锁或资源限制导致等待。应按耗时字段逐层记录,不要只看函数声明。
异步数据库学习时最容易犯什么错?
常见问题包括把同步驱动当成异步驱动、没有明确Session生命周期、多个并发任务共享同一个AsyncSession,以及访问懒加载属性时触发未预期的I/O。