Python asyncio 取消清理 怎样处理

我排查 asyncio 任务“取消后还占着资源”的时候，最容易先怀疑事件循环，其实多数问题在取消语义被吞掉了：Task.cancel() 只是请求取消，Python 会在下一个可挂起点向协程注入 CancelledError。可靠的写法是把释放连接、锁、临时状态放进 finally，清理完成后通常继续抛出取消异常，让上层知道任务确实没有正常完成。

官方地址：https://docs.python.org/3.15/library/asyncio-task.html

一句话记忆：取消不是“立即杀死任务”，而是“请求任务在下一次 await 附近收尾”。不要用 except Exception 试图统一处理它，也不要在清理阶段无条件吞掉 CancelledError。

先认清取消信号会到哪里

调用 task.cancel() 后，任务不会凭空消失。若协程正在等待一个 Future，取消会沿着等待链传递；当协程再次获得执行机会，CancelledError 才会进入它。这个异常直接继承自 BaseException，所以普通的 except Exception 不会拦住它。

先把取消和清理写成一个最小边界。示例中的 resource 代表数据库连接、文件、锁或带异步关闭方法的客户端对象：

import asyncio

async def worker(resource):
    try:
        # 业务工作期间可能在这里等待 IO，也可能收到取消请求
        await resource.process()
    except asyncio.CancelledError:
        # 只做取消相关的记录或状态标记，不把取消改写成普通成功
        resource.mark_cancelled()
        raise
    finally:
        # finally 无论正常返回、异常还是取消都会进入
        await resource.aclose()

async def stop_worker(task):
    # cancel() 发送取消请求，真正的收尾由 worker 自己完成
    task.cancel()
    try:
        await task
    except asyncio.CancelledError:
        # 上层确认任务已按取消语义结束
        pass

这里有两个容易混淆的点。第一，finally 是资源收尾位置，不代表任务最后一定成功；第二，except asyncio.CancelledError 里的 raise 很重要，它让调用者可以继续取消父任务、统计主动取消，或者交给结构化并发组件处理。

并发结构要等清理完成

只取消一个子任务还不够，父任务还要决定是否等待它结束。asyncio.gather 在默认模式下会把第一个异常传播给调用方，但不会因为一个子任务异常就自动取消其它可等待对象；如果业务要求整体停止，要显式保存任务并统一取消、等待。

TaskGroup 更适合“这些子任务要一起收尾”的场景：一个子任务以非取消异常失败时，组内剩余任务会被取消，退出上下文前会等待它们完成清理。不要在子任务里无条件吞掉 CancelledError，否则结构化并发的内部取消可能失去原本的边界。

import asyncio

async def run_group(jobs):
    async with asyncio.TaskGroup() as group:
        for job in jobs:
            # TaskGroup 会持有子任务，并在上下文退出时等待它们收尾
            group.create_task(worker(job))

async def run_with_deadline(job):
    try:
        # timeout 内部使用取消结束当前代码块
        async with asyncio.timeout(3):
            await worker(job)
    except TimeoutError:
        # TimeoutError 应在 timeout 上下文外处理
        job.record_timeout()

async def cancel_all(tasks):
    # 先发出统一取消请求，再逐个等待，避免留下悬挂任务
    for task in tasks:
        task.cancel()
    results = await asyncio.gather(*tasks, return_exceptions=True)
    # 保留每个任务的结果或异常，便于上层区分取消与真实失败
    return results

asyncio.timeout() 会在上下文内部取消当前任务，并在上下文外把取消转换为 TimeoutError。这解释了为什么超时捕获通常写在 async with 外层；如果在内部直接捕获 CancelledError，容易把超时控制流弄乱。

区分主动取消、超时和业务异常

日志至少要保留三种结果：调用方主动取消、截止时间触发的超时、业务代码本身抛出的异常。它们的处理动作不同：主动取消通常是正常控制流，超时要记录边界与耗时，业务异常则需要保留原始堆栈。把三类结果都写成“任务失败”，后续就无法判断是用户离开、依赖变慢还是代码出错。

asyncio.shield() 只保护内部任务不被外层取消，外层的 await 仍可能收到 CancelledError，因此它不是“忽略取消”的开关。确实要在取消后继续完成一个很小的提交或关闭动作时，保存内部任务的强引用并记录这种特殊策略；不要为了让日志好看而调用 uncancel()。官方文档把它主要留给 asyncio 内部的结构化并发实现。

清理排查清单

• 是否把释放连接、锁和临时文件放进了 finally，而不是只写在正常返回路径？
• 捕获 CancelledError 后，是否在清理完成后重新抛出？
• 父任务是否保存了子任务引用，并在取消后等待它们结束？
• 是否把 TimeoutError、主动取消和业务异常分开统计？
• 是否误把 shield 或 uncancel 当成常规补丁？

常见问题

为什么 finally 里还要 await 关闭资源？

异步资源的关闭本身也可能需要等待 IO。把它放在 finally 能覆盖正常结束和异常结束，但应让关闭方法可重复调用，并避免在关闭阶段再次启动无关工作。

取消任务后为什么还要 await 它？

cancel() 只是发出请求。await task 才能让调用方观察到清理已结束，并拿到最终的取消或异常结果；不等待就可能留下后台任务继续占用资源。

把 asyncio 取消当成一种需要传播的控制信号，资源清理就有了稳定的落点：底层协程负责 finally，上层结构负责等待，日志负责区分取消、超时和失败。