asyncio.wait 与 as_completed 区别解析

本文深入解析了 Python asyncio 中 `wait()` 与 `as_completed()` 的核心差异：前者聚焦于**统一调度与状态控制**，通过 `(done, pending)` 集合和灵活的 `return_when` 策略（如首个完成、首个异常、指定数量达成）实现精细化并发协调，但需手动清理挂起任务；后者专为**流式消费结果**而生，以异步迭代器形式按实际完成顺序逐个返回结果，天然适配实时处理场景，却隐去任务身份与进度信息。二者在异常触发时机、取消行为、资源清理责任及适用模式上截然不同——选 `wait()` 是为了响应“谁完成了/何时该停”，选 `as_completed()` 是为了响应“下一个结果来了”，而忽视底层 task 生命周期管理，轻则引发警告，重则导致事件循环卡死、进程悬停。

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）。

• 返回值是 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 住。

到这里，我们也就讲完了《asyncio.wait 与 as_completed 区别解析》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！