Python asyncio.wait处理部分任务成功的实现方法

在 Python 异步编程中，一个非常典型的场景是：当你一次性启动多个协程任务后，并不需要等待所有任务全部完成，而是希望立即获取那些已经结束的结果。此时，asyncio.wait 是一个顺手的工具。然而，很多初学者在实际使用时会发现，它返回的“已完成任务”集合中，既包含正常结束的任务，也包含因异常而终止的任务。这到底是怎么回事？如何才能安全地从已完成集合中提取成功的结果？这些问题值得深入剖析。

一、asyncio.wait 何时返回部分完成的任务？

当你传入一组协程任务时，如果其中有些已经结束（无论是正常返回还是抛出异常），而另一些仍在运行，asyncio.wait 会立即将完成和未完成的 Task 分成两组返回。它仅关注“结束”这一状态，并不区分成功或失败——即便某个任务出现了异常，它也会被放进 done 集合中。

因此，你需要自行判断哪些任务是成功的。方法就是遍历 done 集合，通过 task.exception() 检查是否存在未捕获的异常：如果返回 None，说明任务正常完成，这时再调用 task.result() 取值才是安全的。以下是几个关键点：

• 不要直接对 done 中的 task 调用 result()，若该任务失败，会直接抛出未经处理的异常。
• asyncio.wait 的默认行为是 return_when=asyncio.FIRST_COMPLETED，如果你希望等待第一批结束的任务立即返回，这个选项是正确的；如果需要等到出现第一个异常就返回，使用 FIRST_EXCEPTION；若想等到所有任务都结束，用 ALL_COMPLETED，但要注意它会阻塞直到全部完成。
• 很多人误以为 wait(..., timeout=1) 能实现“超时后只返回成功的任务”，实际上并非如此。超时后，未完成任务仍然留在 pending 里，而 done 中只包含那些确实已经结束的任务——失败的任务同样包含在内。

二、如何安全提取已完成且成功的任务结果？

核心思路很简单：将“已完成”和“成功”两个条件分开判断。先过滤出 done 中无异常的任务，再统一提取结果：

done, pending = await asyncio.wait(tasks, timeout=2)
successful_results = []
for task in done:
    if task.exception() is None:
        successful_results.append(task.result())

这段代码执行稳健，不会因为某个任务异常而中断，也不会试图从失败的任务中获取 result()。如果你需要记录失败原因以便后续重试或分析，可以额外收集 task.exception()。

另外还有几个容易被忽略的细节：

• 不要用 task.cancelled() 替代异常检查。取消与异常是两回事，当 cancelled() 返回 True 时，exception() 可能返回 CancelledError。
• 如果任务在正常逻辑中返回 None 是合法结果，千万不要靠 if task.result() 来判断成功与否——必须通过 exception() 是否为 None 来判定。
• 多个任务可能同时完成，done 是一个 set，因此顺序不保证。如果需要按原始任务列表的顺序整理结果，应提前为 task 加索引，或者在用 asyncio.create_task 包装时绑定上下文信息。

三、timeout=0 和 return_when=FIRST_COMPLETED 的实际效果差异

timeout=0 并不是“不等待”，而是“最多等0秒”。它会立即返回当前已经结束的任务，如果没有任何任务结束，done 就是空集。而 return_when=FIRST_COMPLETED 则至少会等待第一个任务结束才返回。

实际中这两者经常配合使用。比如你想“先看一眼有没有现成结果，没有的话再等待第一个完成”，可以先用 wait(..., timeout=0)，如果 done 为空，再调用 wait(..., return_when=FIRST_COMPLETED)。

• timeout=0 在事件循环刚启动时返回空 done 是预期行为，并非 bug。
• 如果所有任务都尚未调度执行——比如都是同步阻塞操作，没有包裹 asyncio.to_thread——那么 done 会长期为空，此时需要配合重试或 fallback 逻辑。
• return_when 的其他选项（如 ALL_COMPLETED 或 FIRST_EXCEPTION）会改变阻塞行为，选错会导致程序卡住或过早退出，使用时务必仔细考量实际需求。

四、为什么有时 done 里有 task 却取不到 result？

最常见的原因：任务已被取消或因异常结束，但你跳过了 exception() 检查。举个例子：

task = asyncio.create_task(some_coro())
await asyncio.sleep(0.1)
task.cancel()
done, _ = await asyncio.wait([task])
# 此时 task in done 为 True，但 task.result() 会 raise CancelledError

另一个容易忽略的情况是：task 可能在 wait 返回前已经正常结束，但你未及时处理，后来又手动 cancel() 了它——这时 exception() 返回的是 CancelledError，而非原始的异常信息。

因此，一个不得不说的好习惯是：永远先确认 task.done()，再调用 task.exception() 或 task.result()，这样可以避免 InvalidStateError。另外，如果你使用 asyncio.ensure_future 创建任务，行为是一致的；但若用 loop.create_task，要注意 loop 是否已经关闭。最后，在 finally 块中清理 pending 任务时，别忘了用 cancel() 加上 await asyncio.wait(...) 等待它们真正结束，否则可能残留未处理的异常。

总结下来，实际使用中最关键的并不是“等多少个”或“超时多久”，而是每一次从 done 中取出 task 后，必须做三个动作：先确认 done()，再检查 exception()，最后才取 result()。省略中间任何一环，都可能让看似稳妥的“部分成功”逻辑突然崩在异常上。