Python asyncio.wait_for 超时后如何保留任务清理机会

asyncio.wait_for 超时后，任务不会凭空消失：默认行为是向被等待对象发送取消请求，等它真正完成取消，再向调用方抛出 TimeoutError。所以，必须释放的连接、临时文件和锁，应放在协程自己的 finally 中；如果超时只代表调用方不再等待、后台任务仍要继续，则先创建并保存 Task，再用 asyncio.shield 包住它。

先决定超时意味着“取消工作”还是“停止等待”。前者使用 wait_for(task)，让任务进入清理路径；后者使用 wait_for(shield(task))，让任务继续运行，并安排完成后的回收与异常记录。

先确认 wait_for 超时到底取消了什么

wait_for(aw, timeout) 接收协程、Task 或 Future。超时发生时，它会取消 aw 并抛出内置的 TimeoutError。从 Python 3.7 起，wait_for 会等待被取消对象实际结束，因此“超时 1 秒”是开始取消的时间点，不一定是函数返回的硬上限。

这一区别很重要：如果工作协程在 finally 中关闭连接、回滚临时状态，调用方捕获异常时，清理可能仍已完成或正在完成。不要在外层看到超时就立即创建第二个相同任务，否则可能出现两个任务同时写同一份业务状态。

把必须执行的清理放进协程的 finally

取消是协作式的。CancelledError 会在任务下一次有机会运行时进入协程，因此资源释放应靠工作函数自己负责。调用方只负责记录“这次等待超时”，不要把清理逻辑散落在多个异常分支里。

import asyncio

async def download_to_temp(client, target):
    handle = await client.open(target)
    try:
        # 业务工作可能在任意一次 await 处收到取消
        return await handle.read_all()
    finally:
        # 无论成功、超时取消还是上层主动取消，都关闭资源
        await handle.close()

async def read_with_deadline(client, target):
    try:
        # 超时后 wait_for 会等待 download_to_temp 的取消收尾
        return await asyncio.wait_for(
            download_to_temp(client, target), timeout=2.0
        )
    except TimeoutError:
        # 这里只处理调用方的超时结果，不重复创建同一个下载任务
        return None

finally 里也可能抛出异常，例如关闭远端连接失败。生产代码要把清理异常记录出来，并根据资源类型决定是否继续向上抛出；不要为了“确保返回超时”而吞掉所有异常。另一个边界是不要无条件捕获并压制 CancelledError，否则 TaskGroup、asyncio.timeout 等依赖取消传播的结构可能失去正确语义。

需要保留后台任务时使用 shield 和任务引用

有些请求只需要在截止时间内拿到结果，超时后任务仍应把缓存写完或把审计事件送入队列。这时不要直接把裸协程传给 shield 后丢掉引用，而要先创建 Task。事件循环对任务只保留弱引用，强引用同时也是后续查看结果、取消任务和回收异常的入口。

import asyncio

async def submit_with_graceful_timeout(build_report):
    task = asyncio.create_task(build_report())
    try:
        # 调用方最多等 1 秒，但这次超时不会取消后台任务
        return await asyncio.wait_for(asyncio.shield(task), timeout=1.0)
    except TimeoutError:
        # 保留引用，任务完成后主动取结果，避免异常无人读取
        def collect_finished(done_task):
            try:
                done_task.result()
            except asyncio.CancelledError:
                # 后台任务可能被其他控制路径取消
                pass
            except Exception as exc:
                # 晚到的异常必须进入日志或告警回路
                print(f"后台报告失败: {exc!r}")

        task.add_done_callback(collect_finished)
        return "accepted"

这个模式的含义是“停止等待”，不是“保证任务一定成功”。进程退出、事件循环关闭或其他代码显式取消 task 时，后台工作仍可能失败。若业务要求最终完成，应把工作放入可持久化队列或由独立 Worker 消费，而不是只依靠内存中的 Task。

用状态表和收尾回路检查失败边界

上线前可以把超时场景压缩成四个判断：工作是否允许取消、资源是否有 finally、超时后是否保留 Task、晚到异常由谁读取。若答案分别是“允许、没有、不要、没人”，问题通常不是 timeout 数值，而是任务生命周期没有被设计出来。

需要等待但又可取消的操作，优先使用带 context 的协作式函数；需要继续运行但不想阻塞请求，就使用 shield 加强引用；批量任务需要知道哪些已经完成，则使用 asyncio.wait 返回的 done 和 pending 集合，显式决定取消、重试或排队。

常见问题

wait_for 超时后 finally 一定会执行吗？

只要协程实际收到取消并继续运行到收尾路径，通常会执行。不要把进程被强制终止、事件循环关闭或 finally 自身抛错等情况当作正常取消处理。

shield 能让任务永远不被取消吗？

不能。它只阻止当前这次外层等待把取消传给内部任务；代码仍可以直接调用 task.cancel()，任务所属的事件循环也可能结束。

为什么 wait_for 返回时间会超过 timeout？

因为 wait_for 会等待被取消对象真正完成取消。清理中有额外 await、远端资源迟迟不响应时，实际返回时间就可能超过设定值。

处理 asyncio 超时，先画清“取消工作”和“停止等待”的边界，再选 wait_for 或 shield。把清理、任务引用和晚到异常都纳入生命周期，通常比不断调小 timeout 更能解决线上问题。