asyncio.wait()适合统一控制超时与完成状态,返回(done, pending)并支持return_when精细调度;asyncio.as_completed()专为按完成顺序消费结果设计,返回异步迭代器,需async for逐个await。

asyncio.wait() 适合需要统一控制超时和完成状态的场景
当你需要等一批任务里「至少 N 个完成」,或者「全部完成 / 任意一个出错就停」,asyncio.wait() 是更直接的选择。它返回的是 (done, pending) 两个 set,你可以检查哪些已结束、哪些还在跑,还能配合 return_when 参数精细控制退出时机。
常见错误是默认用 return_when=asyncio.ALL_COMPLETED 却没处理 pending 里的 task —— 它们不会自动 cancel,可能持续占用资源甚至引发后续异常。
-
return_when=asyncio.FIRST_COMPLETED:拿到第一个结果就返回,适合“谁快用谁”逻辑 -
return_when=asyncio.FIRST_EXCEPTION:任一 task 抛出未捕获异常即返回,适合容错敏感场景 - 必须手动调用
task.cancel()或await asyncio.gather(*pending, return_exceptions=True)清理挂起任务
asyncio.as_completed() 专为按完成顺序消费结果而生
asyncio.as_completed() 返回一个异步迭代器,每次 await 都得到「下一个最先完成」的 Task 的结果(不是 task 对象本身)。它不关心谁先启动、谁后启动,只管谁先 finish —— 这让并发请求+流式处理变得非常自然。
容易踩的坑是误以为它会自动 await 所有 task:它只是包装了等待逻辑,你仍需在循环里显式 await 每次迭代;另外,如果某个 task 永远不完成,迭代就会卡住(除非加 timeout)。
立即学习“Python免费学习笔记(深入)”;
- 返回值是
coroutine,必须用async for或逐个await,不能直接 print - 无法得知哪个 task 对应哪个结果(除非你在创建 task 时绑定标识,比如用
asyncio.create_task(coro, name="req-1")) - 内部会把所有 task 包装成
asyncio.ensure_future(),所以传入普通协程也 OK,但传入已运行的Task更安全
性能与取消行为差异直接影响错误处理方式
asyncio.wait() 在返回前,对已完成的 task 调用的是 task.result(),如果 task 已失败,这里会直接 re-raise 异常;而 asyncio.as_completed() 是在你 await 迭代项时才触发 result(),异常延迟暴露。
这意味着:用 wait() 时,你得在 try/except 里包住整个 await wait(...);用 as_completed() 时,异常要放在 async for 循环体内捕获。
-
wait()的pending集合里 task 仍处于运行中,cancel 后需额外 await 确保清理 -
as_completed()不提供 pending 列表,也没法知道还有几个没完成,不适合做进度判断 - 两者都不自动 suppress exception —— 如果你不显式处理失败 task,异常最终会冒泡到 event loop,触发
Task exception was never retrieved警告
选哪个?看你要响应「完成事件」还是「完成结果」
如果你写的是监控脚本,要等 5 个健康检查里至少 3 个成功就上报状态,用 wait(return_when=asyncio.FIRST_COMPLETED) + 计数更清晰;如果你写的是爬虫,想一边收数据一边解析入库,as_completed() 配合 async for 就是天然流水线。
最易被忽略的一点:两者都依赖底层 task 的正确生命周期管理。传入已 cancel() 的 task、或忘了 await cleanup,都会导致 task 悬浮、event loop 关闭失败、甚至 Python 进程 hang 住。










