Python asyncio 任务取消全解析:从 cancel() 到优雅停机的实战指南

在 Python 编程生态中,asyncio 已经成为处理网络请求、数据库访问、消息队列、实时通信和自动化任务的重要工具。它让一个线程能够在多个 I/O 操作之间高效切换,以相对简洁的代码构建高并发应用。

然而,异步程序真正困难的部分,往往不是“如何启动任务”,而是:

当程序准备关闭、请求超时、用户主动退出,或者某个子任务失败时,怎样安全地停止正在运行的任务?

如果取消处理不当,程序可能出现连接没有关闭、锁没有释放、数据只写了一半、任务悄悄失踪,甚至服务无法正常退出等问题。

本文将从基础机制讲起,深入解析 asyncio 中的任务取消,并通过多个 Python 实战案例总结可靠的 Python 最佳实践。


一、任务取消不是“强制杀死”

先看一个最简单的异步任务:

import asyncio


async def download_file() -> None:
    print("开始下载")

    for progress in range(1, 6):
        await asyncio.sleep(1)
        print(f"下载进度:{progress * 20}%")

    print("下载完成")

创建任务后,可以调用 cancel() 请求取消:

async def main() -> None:
    task = asyncio.create_task(
        download_file(),
        name="file-downloader",
    )

    await asyncio.sleep(2.5)

    print("准备取消下载任务")
    task.cancel()

    try:
        await task
    except asyncio.CancelledError:
        print("下载任务已取消")


asyncio.run(main())

可能输出:

开始下载
下载进度:20%
下载进度:40%
准备取消下载任务
下载任务已取消

这里最重要的一个概念是:

task.cancel() 发出的只是取消请求,并不会像操作系统强制终止进程那样立即杀死任务。

取消请求会让事件循环在下一次适当的调度机会,向目标协程内部抛入一个 asyncio.CancelledError。协程可以借此清理资源,然后结束运行。严格来说,Task.cancel() 并不保证任务一定最终处于取消状态,因为协程有机会捕获并抑制该异常,不过这种做法通常不受推荐。(Python documentation)

任务取消流程可以概括为:

调用 task.cancel()
        │
        ▼
记录取消请求
        │
        ▼
任务运行到可响应取消的位置
        │
        ▼
协程内部收到 CancelledError
        │
        ├── 清理资源并重新抛出 ──▶ 任务被取消
        │
        └── 吞掉异常继续运行 ──▶ 任务可能没有真正取消

二、为什么取消通常发生在 await 附近?

asyncio 使用协作式调度。一个任务运行到 await 并暂停后,事件循环才有机会调度其他任务、处理 I/O 或传递取消请求。(Python documentation)

例如:

async def worker() -> None:
    while True:
        print("处理一批数据")
        await asyncio.sleep(1)

这里的 await asyncio.sleep(1) 不只是等待一秒,也给事件循环提供了调度和取消任务的机会。

如果协程长时间执行不包含 await 的 CPU 密集型代码:

async def cpu_heavy_job() -> int:
    total = 0

    for number in range(500_000_000):
        total += number * number

    return total

即使外部调用了 cancel(),事件循环也可能迟迟无法把 CancelledError 传入该协程,因为事件循环始终没有重新获得控制权。

对于长循环,可以偶尔主动让出控制权:

async def cooperative_job() -> int:
    total = 0

    for number in range(10_000_000):
        total += number * number

        if number % 10_000 == 0:
            await asyncio.sleep(0)

    return total

asyncio.sleep(0) 会暂停当前任务,让事件循环有机会运行其他任务。官方文档也将其描述为长时间运行函数主动让出执行权的一种优化方式。(Python documentation)

不过,真正繁重的 CPU 计算通常更适合进程池、原生扩展或其他并行计算方案,而不是简单塞进 asyncio 事件循环。


三、正确处理取消:清理后重新抛出

可靠的异步任务通常应使用 try/finally 保证资源被释放。

import asyncio


async def consume_messages() -> None:
    connection_open = False

    try:
        print("连接消息服务器")
        connection_open = True

        while True:
            await asyncio.sleep(1)
            print("收到一条消息")

    finally:
        if connection_open:
            print("关闭消息服务器连接")


async def main() -> None:
    task = asyncio.create_task(consume_messages())

    await asyncio.sleep(2.5)
    task.cancel()

    try:
        await task
    except asyncio.CancelledError:
        print("消费者已安全停止")


asyncio.run(main())

即使任务在运行过程中被取消,finally 仍会执行。

如果还需要记录取消原因,可以显式捕获 CancelledError:

async def consume_messages() -> None:
    try:
        while True:
            await asyncio.sleep(1)
            print("处理消息")

    except asyncio.CancelledError:
        print("收到取消请求,准备停止消费者")
        raise

    finally:
        print("释放连接和缓存")

推荐模式是:

try:
    await do_work()
except asyncio.CancelledError:
    await cleanup()
    raise

也就是:

  1. 捕获取消异常;
  2. 完成必要清理;
  3. 使用 raise 继续传播取消。

Python 官方文档建议协程使用 try/finally 执行清理逻辑;如果显式捕获 CancelledError,通常应在清理完成后重新抛出。(Python documentation)


四、为什么 except Exception 捕获不到取消?

看下面的代码:

async def run_job() -> None:
    try:
        await asyncio.sleep(60)
    except Exception as exc:
        print("任务出错:", exc)

很多初学者认为,这段代码能够捕获所有异常。实际上,当前 Python 中的 asyncio.CancelledError 直接继承自 BaseException,而不是普通的 Exception。(Python documentation)

简化后的继承关系如下:

BaseException
├── KeyboardInterrupt
├── SystemExit
├── asyncio.CancelledError
└── Exception
    ├── ValueError
    ├── RuntimeError
    └── OSError

这项设计很有意义:普通的业务异常处理不应无意间拦截任务取消。

下面的写法通常比较合理:

async def run_job() -> None:
    try:
        await perform_request()

    except asyncio.CancelledError:
        print("任务被取消")
        raise

    except Exception as exc:
        print(f"业务执行失败:{exc}")

不要为了“捕获所有错误”而轻易使用:

except BaseException:
    ...

因为它可能同时吞掉任务取消、KeyboardInterrupt 和 SystemExit,让程序无法按预期退出。


五、调用 cancel() 后为什么还要 await task?

下面的代码并不完整:

task.cancel()

更可靠的写法是:

task.cancel()

try:
    await task
except asyncio.CancelledError:
    print("任务已经完成取消")

调用 cancel() 只是提交请求。继续 await task,调用方才能确认目标任务是否已经:

  • 收到取消异常;
  • 执行完资源清理;
  • 真正结束运行;
  • 在清理阶段抛出了其他异常。

完整示例:

async def save_data() -> None:
    try:
        await asyncio.sleep(10)
    finally:
        print("正在刷新缓冲区")
        await asyncio.sleep(0.2)
        print("缓冲区已刷新")


async def main() -> None:
    task = asyncio.create_task(save_data())

    await asyncio.sleep(1)
    task.cancel("程序准备关闭")

    try:
        await task
    except asyncio.CancelledError as exc:
        print(f"任务取消完成:{exc}")


asyncio.run(main())

任务只有在取消请求已经发出,并且内部协程最终传播了 CancelledError 后,task.cancelled() 才会返回 True。(Python documentation)

print(task.done())       # 任务是否已经结束
print(task.cancelled())  # 是否以取消状态结束

六、不要随意吞掉 CancelledError

下面是一种常见反模式:

async def bad_worker() -> None:
    try:
        await asyncio.sleep(60)
    except asyncio.CancelledError:
        print("忽略取消")

这段代码捕获取消异常后没有重新抛出。调用方可能认为任务已成功完成,而不是被取消。

问题会在 TaskGroup 和 asyncio.timeout() 中变得更加严重,因为这些结构化并发工具内部正是通过取消机制控制任务边界。吞掉 CancelledError 可能破坏它们的正常行为。(Python documentation)

更好的写法是:

async def good_worker() -> None:
    try:
        await asyncio.sleep(60)

    except asyncio.CancelledError:
        print("记录取消并清理状态")
        raise

极少数场景可能确实需要彻底抑制取消。此时除了捕获 CancelledError,还涉及 Task.uncancel() 对取消状态的处理。但官方文档明确指出,uncancel() 主要面向 asyncio 内部实现,普通业务代码通常不应调用。(Python documentation)


七、取消会怎样向子任务传播?

假设父协程正在等待子任务:

async def child() -> None:
    try:
        await asyncio.sleep(60)
    finally:
        print("子任务清理完成")


async def parent() -> None:
    await child()

当运行 parent() 的任务被取消时,取消通常会沿着当前等待链传播。目标任务在取消时如果正在等待一个 Future,该 Future 也会被取消。(Python documentation)

在实际项目中,应当明确任务的父子关系:

HTTP 请求任务
    │
    ├── 查询用户
    ├── 查询订单
    └── 查询推荐

当 HTTP 客户端已经断开时,继续执行这些查询可能没有意义,子任务通常也应该一起停止。


八、asyncio.gather 中的取消行为

批量运行任务时经常使用:

results = await asyncio.gather(
    query_user(),
    query_orders(),
    query_inventory(),
)

如果 gather() 自身被取消,尚未完成的子任务也会被取消。(Python documentation)

group = asyncio.gather(
    query_user(),
    query_orders(),
    query_inventory(),
)

group.cancel()

try:
    await group
except asyncio.CancelledError:
    print("整组任务已取消")

但如果只是其中一个子任务被取消,gather() 会把它视为抛出了 CancelledError,不会因此自动取消其他所有子任务。这样可以避免单个任务的取消引发整组任务连锁取消。(Python documentation)

因此,需要区分:

取消 gather 本身
    └── 未完成的子任务也会被取消

某个子任务单独取消
    └── 其他任务默认继续运行

九、使用 TaskGroup 管理共同生命周期

在 Python 3.11 及以上版本中,多个属于同一业务作用域的任务,可以使用 asyncio.TaskGroup 管理:

import asyncio


async def worker(name: str) -> None:
    try:
        while True:
            print(f"{name} 正在工作")
            await asyncio.sleep(1)
    finally:
        print(f"{name} 已释放资源")


async def main() -> None:
    async with asyncio.TaskGroup() as group:
        group.create_task(worker("worker-A"))
        group.create_task(worker("worker-B"))


asyncio.run(main())

TaskGroup 会在退出上下文时等待组内任务结束。如果某个子任务首次抛出非 CancelledError 异常,任务组会取消其他未完成任务,等待它们结束,然后以异常组的形式报告错误。(Python documentation)

这是一种更清晰的结构化并发模型:

进入 TaskGroup
    │
    ├── 创建任务 A
    ├── 创建任务 B
    └── 创建任务 C
          │
          └── B 失败
                │
                ├── 取消 A
                ├── 取消 C
                ├── 等待清理
                └── 汇总并抛出异常

对于“共同成功或共同结束”的任务集合,TaskGroup 通常比散落的 create_task() 更安全。


十、超时本质上也是一种取消

1. 使用 asyncio.timeout

Python 3.11+ 可以使用异步超时上下文:

import asyncio


async def request_service() -> str:
    await asyncio.sleep(5)
    return "请求成功"


async def main() -> None:
    try:
        async with asyncio.timeout(2):
            result = await request_service()
            print(result)

    except TimeoutError:
        print("请求超过两秒,已终止")


asyncio.run(main())

asyncio.timeout() 到期后,会取消当前任务,并在内部将相应的 CancelledError 转换为可在上下文外捕获的 TimeoutError。因此,TimeoutError 应当在 async with 外部处理。(Python documentation)

2. 使用 asyncio.wait_for

async def main() -> None:
    try:
        result = await asyncio.wait_for(
            request_service(),
            timeout=2,
        )
        print(result)

    except TimeoutError:
        print("请求超时")

当超时发生时,wait_for() 会取消目标任务并抛出 TimeoutError。它还会等待目标任务实际完成取消,因此总耗时可能略微超过设置的超时时间。(Python documentation)

这也说明了为什么资源清理代码应该快速、可靠。一个清理过程如果无限阻塞,会拖延整个超时和关闭流程。


十一、什么时候使用 asyncio.shield?

有些操作不希望因为调用方取消而中途停止,例如:

  • 提交关键事务后的确认;
  • 写入审计日志;
  • 刷新必须落盘的数据;
  • 已经开始的协议关闭握手。

可以使用 asyncio.shield():

import asyncio


async def write_audit_log() -> None:
    print("开始写审计日志")
    await asyncio.sleep(2)
    print("审计日志写入完成")


async def handler() -> None:
    audit_task = asyncio.create_task(write_audit_log())

    try:
        await asyncio.shield(audit_task)
    except asyncio.CancelledError:
        print("handler 被取消,但日志任务仍可继续")

        # 根据业务需求,继续等待关键任务完成
        await audit_task
        raise

shield() 保护的是内部可等待对象,使其不因外层调用者被取消而自动取消。但外层调用者本身仍会收到 CancelledError。如果内部任务通过其他方式被取消,shield() 也无法阻止。(Python documentation)

同时,应保存 Task 的强引用:

audit_task = asyncio.create_task(write_audit_log())
await asyncio.shield(audit_task)

不要随意写成没有任何引用的临时任务。事件循环只保存任务的弱引用,没有其他引用的任务可能在完成前被垃圾回收。(Python documentation)

shield() 不是“所有重要任务都不允许取消”的许可证。过度屏蔽会让程序关闭困难,甚至制造无法停止的后台任务。它只应保护真正需要完成的关键操作。


十二、实战:实现服务的优雅停机

下面模拟一个拥有多个消费者的后台服务。当收到关闭请求时,系统会:

  1. 向所有任务发送取消请求;
  2. 等待任务完成清理;
  3. 收集取消和异常结果;
  4. 确认服务安全退出。
import asyncio
from typing import Any


async def consume_queue(worker_name: str) -> None:
    print(f"{worker_name} 已启动")

    try:
        while True:
            await asyncio.sleep(1)
            print(f"{worker_name} 处理了一条消息")

    except asyncio.CancelledError:
        print(f"{worker_name} 收到停止信号")
        raise

    finally:
        print(f"{worker_name} 正在提交偏移量")
        await asyncio.sleep(0.2)
        print(f"{worker_name} 已关闭连接")


async def shutdown(
    tasks: list[asyncio.Task[Any]],
) -> None:
    print("开始关闭服务")

    for task in tasks:
        task.cancel("service shutdown")

    results = await asyncio.gather(
        *tasks,
        return_exceptions=True,
    )

    for task, result in zip(tasks, results):
        if isinstance(result, asyncio.CancelledError):
            print(f"{task.get_name()} 已取消")
        elif isinstance(result, BaseException):
            print(f"{task.get_name()} 关闭失败:{result!r}")
        else:
            print(f"{task.get_name()} 正常完成")

    print("服务已安全退出")


async def main() -> None:
    tasks = [
        asyncio.create_task(
            consume_queue(f"worker-{index}"),
            name=f"worker-{index}",
        )
        for index in range(1, 4)
    ]

    try:
        await asyncio.sleep(3.2)
    finally:
        await shutdown(tasks)


asyncio.run(main())

这个案例体现了几个重要的 Python 最佳实践:

  • 保存所有后台任务引用;
  • 为任务设置可读名称;
  • 取消后继续等待任务;
  • 使用 finally 清理资源;
  • 批量关闭时收集所有任务结果;
  • 区分取消、正常返回和真实故障。

十三、常见问题与错误写法

错误一:只取消,不等待

task.cancel()

问题:无法确认任务是否清理完毕。

推荐:

task.cancel()

try:
    await task
except asyncio.CancelledError:
    pass

错误二:吞掉取消异常

except asyncio.CancelledError:
    return

问题:调用方可能误判任务状态,还可能破坏 TaskGroup 和超时上下文。

推荐:

except asyncio.CancelledError:
    await cleanup()
    raise

错误三:在清理阶段无限等待

finally:
    await send_data_to_unavailable_server()

问题:任务已经准备关闭,却可能永远卡在清理逻辑中。

推荐为清理操作设置边界:

finally:
    try:
        async with asyncio.timeout(2):
            await flush_buffer()
    except TimeoutError:
        print("刷新超时,记录未提交状态")

错误四:误以为取消会立即终止 CPU 循环

async def work() -> None:
    while True:
        calculate_forever()

问题:没有可让事件循环重新获得控制权的暂停点。

推荐拆分计算、主动让出执行权,或把 CPU 密集工作迁移到更合适的执行器。

错误五:对所有任务滥用 shield

如果每个任务都被屏蔽取消,程序可能无法及时关闭。shield() 应用于极少数必须完成的关键步骤,而不是整个业务流程。


十四、任务取消最佳实践清单

在真实 Python 实战项目中,可以遵循以下原则:

  1. 把取消视为正常控制流程,而不是普通业务故障。
  2. 使用 try/finally 保证连接、文件、锁和缓冲区得到清理。
  3. 显式捕获 CancelledError 后,通常应重新抛出。
  4. 调用 task.cancel() 后继续 await task。
  5. 不要用 except BaseException 随意吞掉取消。
  6. 给后台任务设置名称并保存强引用。
  7. 为网络请求、关闭操作和资源清理设置超时。
  8. 使用 TaskGroup 管理具有共同生命周期的任务。
  9. 谨慎使用 shield(),只保护真正不可中断的操作。
  10. 不要在事件循环中执行长时间阻塞或 CPU 密集型代码。
  11. 普通业务代码不要随意调用 uncancel()。
  12. 在服务关闭测试中主动模拟取消,而不只测试成功路径。

结语:好的异步程序,也应该懂得如何结束

学习 asyncio 时,我们很容易把注意力全部放在并发数量、请求速度和吞吐能力上。但一个真正成熟的异步系统,不仅要能快速开始工作,也要能在任何时刻有序地停下来。

任务取消不是粗暴地“杀死”代码,而是一种协作协议:

调用方:请停止运行。
任务:我收到请求了,先释放资源。
任务:清理完成,现在安全退出。
调用方:确认任务已经结束。

当每个协程都知道如何响应取消,每个后台任务都有明确的所有者,每个资源都有确定的清理路径时,异步代码才真正具备了进入生产环境的可靠性。

你在日常 Python 编程中遇到过哪些任务无法取消、服务无法退出或资源没有释放的问题?你更习惯使用 gather 管理任务,还是使用 TaskGroup 构建结构化并发?欢迎在评论区分享你的 Python 实战经验与排查思路。

参考资料

  • Python 官方文档:协程与任务、任务取消、任务组、超时与取消屏蔽。(Python documentation)
  • 推荐书籍:《流畅的 Python》《Effective Python》《Python 编程:从入门到实践》。
  • 延伸关键词:Python编程、Python教程、Python实战、Python最佳实践、异步编程、协程、任务取消、结构化并发。

更多推荐