asyncio 常用函数分类整理

asyncio 常用函数分类整理

按用途分组，附简单作用+示例，结合刚才的协程代码理解。

前提： import asyncio

一、入口 & 事件循环（程序启停）

1.  asyncio.run(coro) 
Python3.7+ 推荐，启动事件循环，运行主协程，循环结束自动关闭。

python

async def main():
pass
asyncio.run(main())

✅ 就是你例子里的入口，替代老版本手动写  loop 。

2.  asyncio.get_running_loop() 
获取当前正在运行的事件循环（只能在async函数内部调用）。
3.  asyncio.get_event_loop() 
旧版获取循环对象，新版本不推荐直接使用。

二、创建并发任务（最常用！）

1.  asyncio.create_task(coro, name=None) 
把协程包装成  Task ，立刻丢进事件循环调度并发执行，就是你代码里的。

关键点：调用这一行任务就开始跑，不是await才跑。

python

task = asyncio.create_task(fetch_api(1,2))

2.  asyncio.gather(*coros_or_tasks, return_exceptions=False) 
并行执行多个协程/Task，收集全部返回值，打包成列表返回。

• 默认：任意一个任务抛异常，整体直接报错；
• return_exceptions=True ：异常当成结果保存，不会中断其他任务。

python

res = await asyncio.gather(fetch_api(1,2), fetch_api(2,1))

res 是两个return结果组成的列表

3.  asyncio.wait(tasks, timeout=None, return_when=...) 
等待一组任务，区分已完成 / 未完成任务集合，返回两个集合  (done, pending) 。
 return_when  可选：

• FIRST_COMPLETED ：任意一个任务完成就返回
• FIRST_EXCEPTION ：遇到第一个异常就返回，否则等全部完成
• ALL_COMPLETED （默认）：等待全部结束

和gather区别：gather直接拿结果；wait用来判断哪些任务做完了。

4.  asyncio.as_completed(tasks) 
迭代器，哪个任务先完成，就先产出它的结果。适合逐个处理结果。

python

for task in asyncio.as_completed(task_list):
result = await task

三、等待、休眠（IO模拟）

1.  asyncio.sleep(delay) 
非阻塞休眠，让出事件循环，其他协程可以运行。

❗不要用time.sleep()，它是阻塞，卡死整个循环。

python

await asyncio.sleep(2)

2.  asyncio.wait_for(aw, timeout) 
带超时等待：等待协程/任务，如果超过指定时间没完成，抛出 TimeoutError 。

python

最多等3秒，超时直接报错

res = await asyncio.wait_for(fetch_api(1, 5), timeout=3)

四、Task 对象相关（任务控制）

1.  task.cancel() ：取消任务，后续await会抛出 CancelledError 
2.  task.cancelled()  判断任务是否被取消
3.  task.done()  判断任务是否结束（成功/异常/取消都算done）
4.  task.result()  获取任务返回值（任务完成后调用）

五、底层工具（锁、信号量，并发安全）

用于多协程争抢同一个资源，防止并发冲突

1.  asyncio.Lock()  协程锁，同一时间只允许1个协程执行代码块
2.  asyncio.Semaphore(value)  信号量，控制同时运行协程最大数量（爬虫限流最常用）

python

sem = asyncio.Semaphore(5) # 最多5个并发
async def work():
async with sem:
# 最多5个协程同时进入这里

3.  asyncio.Queue()  协程安全队列，生产者消费者模型。

六、辅助函数

1.  asyncio.iscoroutine(obj)  判断对象是不是协程
2.  asyncio.all_tasks(loop=None)  获取当前循环所有正在运行的task

✅ 极简选型口诀

• 想批量并发拿所有结果 → gather
• 需要单独控制任务、提前创建 → create_task
• 等待任务，区分哪些做完了 → wait
• 任务完成逐个输出结果 → as_completed
• 设置超时时间 → wait_for
• 限制并发数量（爬虫） → Semaphore