下面这份是 “asyncio 核心 API 全景表”，按功能分层来讲，每个函数都给你：

• ✅ 功能
• ✍️ 函数签名
• 📦 返回值
• ⚠️ 使用注意事项（重点）

这是偏 工程 & 原理级 的整理，不是入门手册。

一、事件循环（Event Loop）

asyncio 的心脏

1️⃣ asyncio.run()

功能

程序入口，创建并运行事件循环

签名

asyncio.run(coro, *, debug=False)

返回值

• coro 的返回值

注意事项 ⚠️

• ❌ 不能在已有事件循环中调用
• ❌ 只能调用一次
• ✔ 自动关闭 loop、清理 Task

📌 只能用在最外层

2️⃣ asyncio.get_running_loop()

功能

获取当前正在运行的事件循环

签名

asyncio.get_running_loop()

返回值

• AbstractEventLoop

注意事项 ⚠️

• ❌ 在同步函数中调用会抛异常
• ✔ 只能在 async 上下文

3️⃣ asyncio.get_event_loop()（旧）

功能

获取事件循环（历史 API）

注意事项 ⚠️

• ⚠️ Python 3.10+ 不推荐
• 行为在不同版本不一致
• 用 get_running_loop() 替代

二、Task / 协程调度

4️⃣ asyncio.create_task()

功能

把 coroutine 包装成 Task 并调度执行

签名

asyncio.create_task(coro, *, name=None)

返回值

• asyncio.Task

注意事项 ⚠️

• coroutine 立即开始执行
• Task 会被事件循环管理
• 忘了 await → 可能被 GC

5️⃣ asyncio.ensure_future()

功能

兼容 API，接受 coroutine 或 Future

注意事项 ⚠️

• 新代码 用 create_task
• 保留给老代码

6️⃣ asyncio.current_task()

功能

获取当前正在运行的 Task

返回值

• Task | None

三、并发控制（最常用）

7️⃣ asyncio.gather()

功能

并发运行多个 awaitable，收集结果

签名

asyncio.gather(*aws, return_exceptions=False)

返回值

• list（结果顺序与参数一致）

注意事项 ⚠️

• ❌ 一个 Task 抛异常 → 全部取消（默认）
• return_exceptions=True 可避免

8️⃣ asyncio.as_completed()

功能

按完成顺序返回结果

签名

asyncio.as_completed(aws)

返回值

• iterator（Future）

注意事项 ⚠️

• ✔ 适合“谁先完成先处理”
• ❌ 顺序不固定

9️⃣ asyncio.wait()

功能

低层并发控制

签名

asyncio.wait(aws, *, timeout=None, return_when=ALL_COMPLETED)

返回值

• (done, pending) 两个集合

注意事项 ⚠️

• API 偏底层
• 新代码少用

四、Future（底层同步原语）

🔟 asyncio.Future

功能

表示“未来某个时刻才有的结果”

常用方法

future.set_result(value)
future.set_exception(exc)
await future

注意事项 ⚠️

• 一般 不手写
• Task 是 Future 的子类

五、时间 / IO 控制

1️⃣1️⃣ asyncio.sleep()

功能

非阻塞睡眠

签名

asyncio.sleep(delay, result=None)

返回值

• result

注意事项 ⚠️

• ✔ 释放事件循环
• ❌ time.sleep() 会阻塞 loop

1️⃣2️⃣ loop.run_in_executor()

功能

把 阻塞函数 丢进线程池 / 进程池

签名

loop.run_in_executor(executor, func, *args)

返回值

• awaitable

注意事项 ⚠️

• ✔ async 中调用同步代码的正确姿势
• executor=None → 默认线程池

六、网络 & 底层 API

1️⃣3️⃣ loop.getaddrinfo()

功能

异步 DNS 解析

返回值

list[(family, type, proto, canonname, sockaddr)]

注意事项 ⚠️

• 实际是在线程池执行
• 需要 await

1️⃣4️⃣ loop.create_server() / create_connection()

功能

低层 TCP / UDP server

适合

• 网络库
• 自定义协议

七、同步原语（async 版本）

1️⃣5️⃣ asyncio.Lock

async with lock:
    ...

• 非阻塞锁
• ❌ 不能跨 event loop

1️⃣6️⃣ asyncio.Semaphore

• 控制并发数量（限流）

1️⃣7️⃣ asyncio.Queue

• producer / consumer 模型
• async 安全

八、超时 / 取消（非常重要）

1️⃣8️⃣ asyncio.wait_for()

功能

给 awaitable 设置超时

签名

asyncio.wait_for(aw, timeout)

注意事项 ⚠️

• 超时会 取消协程
• 抛 asyncio.TimeoutError

1️⃣9️⃣ Task.cancel()

功能

取消 Task

行为

• 抛 CancelledError
• 协程必须配合处理

九、Python 3.11+ 新特性（强烈推荐）

2️⃣0️⃣ asyncio.TaskGroup

功能

结构化并发（替代 gather）

示例

async with asyncio.TaskGroup() as tg:
    tg.create_task(coro1())
    tg.create_task(coro2())

优点

• 自动取消
• 异常传播清晰
• 可读性极强

十、一张“使用优先级表”（工程经验）

十一、一句话总结（给你这种级别的）

asyncio = 事件循环 + Task 调度 + 协作式让出

你现在已经到了 “该看 API 全貌，而不是示例” 的阶段。