Python asyncio.TaskGroup 取消兄弟任务的处理方式

在一组并发任务里，一个任务失败后，剩下的任务是否继续跑，往往比异常本身更容易造成线上误判。asyncio.TaskGroup 的默认策略是：某个子任务抛出非 CancelledError 异常时，尚未完成的兄弟任务会被取消，任务组等待它们结束，最后把非取消异常聚合后重新抛出。

真正要处理的不是“怎样吞掉取消”，而是分清取消来源，并在每个子任务里完成清理后继续传播取消信号。本文只围绕 TaskGroup 的兄弟任务取消、显式终止和异常收口展开。

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

实战判断可以记成三句话：异常导致的兄弟任务取消由 TaskGroup 负责；资源释放写在子任务的 finally 中；捕获 CancelledError 做完清理后通常要重新抛出，不能让任务看起来“成功结束”。

先判断是哪一种取消

同样是 CancelledError，处理入口可能完全不同：

不要用“所有异常都当作取消”来简化逻辑。CancelledError 是控制生命周期的信号，普通异常才表示某个任务没有完成自己的业务目标。

一个任务失败时兄弟任务为什么会被取消

下面的例子模拟三个并发工作项：第一个任务先失败，另外两个任务正在等待。关键观察点是，兄弟任务在 finally 中记录清理动作，然后重新抛出 CancelledError。

import asyncio


async def worker(name: str, delay: float, fail: bool = False) -> str:
    resource = f"resource-{name}"
    try:
        # 这里代表持有连接、临时文件或锁之后的异步工作。
        await asyncio.sleep(delay)
        if fail:
            raise RuntimeError(f"{name} failed")
        return f"{name} completed"
    except asyncio.CancelledError:
        # 取消发生在下一个可等待点；这里只做必要的取消日志和状态标记。
        print(f"{name}: cancellation requested")
        raise
    finally:
        # 无论成功、失败还是取消，都释放当前任务持有的资源。
        print(f"{name}: cleanup {resource}")


async def run_batch() -> None:
    try:
        async with asyncio.TaskGroup() as group:
            # 第一个任务失败后，TaskGroup 会取消尚未完成的两个兄弟任务。
            group.create_task(worker("fast-failure", 0.1, fail=True))
            group.create_task(worker("slow-a", 2.0))
            group.create_task(worker("slow-b", 2.0))
    except* RuntimeError as errors:
        # 只处理业务失败；兄弟任务的 CancelledError 不会作为同类故障上报。
        for error in errors.exceptions:
            print(f"batch failed: {error}")


asyncio.run(run_batch())

这里有两个容易误读的点。第一，async with 退出前会等待被取消的兄弟任务完成清理，所以不能把“发出取消请求”当成“所有任务已经立刻消失”。第二，失败任务的普通异常会在组退出时被聚合；不要只在某个子任务内部打印异常而不让它离开任务组。

取消处理要放在 finally 的哪一层

资源清理应属于持有资源的子任务，而不是只放在 TaskGroup 外层。外层只能知道一组任务结束了，未必知道每个任务持有什么连接或临时状态。

async def fetch_piece(client, key: str) -> bytes:
    response = None
    try:
        # 让底层客户端也能感知当前任务的取消。
        response = await client.get(key)
        return await response.read()
    except asyncio.CancelledError:
        # 可以写入轻量取消原因，但不要把取消改写成普通成功结果。
        raise
    finally:
        # 关闭响应或归还连接，避免兄弟任务取消后留下半开资源。
        if response is not None:
            await response.close()

如果确实需要把取消转成一个业务结果，必须非常谨慎。Python 文档明确提醒，TaskGroup 等结构化并发组件依赖取消机制；协程吞掉 CancelledError 可能破坏任务组的内部协调。除非你同时正确处理取消状态，否则不要在这里使用“捕获后直接返回空值”的写法。

Python 3.15 如何显式提前结束任务组

当业务条件表示“目标已经满足，不再需要剩余任务”时，这不一定是故障。Python 3.15 文档为 TaskGroup 提供了 cancel()，它会取消组内尚未完成的任务和包含 async with 的父任务，任务组上下文退出时不会把这次正常终止重新作为 CancelledError 抛出。

async def stop_when_ready() -> None:
    async with asyncio.TaskGroup() as group:
        # 这些任务代表并行探测或并行拉取，不再需要的任务会被统一收尾。
        group.create_task(worker("probe-a", 1.2))
        group.create_task(worker("probe-b", 1.8))
        await asyncio.sleep(0.2)

        # 业务条件已经满足时，显式结束任务组而不是伪造一个故障。
        group.cancel()

这条路径适合“找到第一个可用结果”“服务停止”“上游不再需要剩余工作”等场景。日志里应记录 cancel() 的业务原因，否则后续只看任务取消数，很难判断这是正常短路还是异常退化。

旧版本怎么用哨兵异常收口

如果运行环境还没有 TaskGroup.cancel()，可以让组内一个专用协程抛出哨兵异常。其余任务仍会被 TaskGroup 取消，外层用 except* 把这个“正常终止请求”单独拦住。

class StopGroup(Exception):
    """表示业务上主动结束任务组，不代表系统故障。"""


async def stop_group() -> None:
    # 这个异常只负责唤起 TaskGroup 的兄弟任务取消逻辑。
    raise StopGroup("winner found")


async def run_with_sentinel() -> None:
    try:
        async with asyncio.TaskGroup() as group:
            # 先启动需要被统一收尾的工作，再安排一个终止信号任务。
            group.create_task(worker("candidate-a", 1.5))
            group.create_task(worker("candidate-b", 1.5))
            group.create_task(stop_group())
    except* StopGroup as stops:
        # 哨兵异常被识别为正常短路，写入原因并执行业务回滚记录。
        print(f"group stopped intentionally: {stops.exceptions[0]}")

哨兵异常不是“吞掉全部异常”的借口。只捕获你定义的 StopGroup，其余异常仍应继续向上抛出；如果多个任务几乎同时失败，ExceptionGroup 可能包含多个异常，处理器应按类型分别记录。

值班时怎么确认取消没有变成故障

可以把排查分成三层：

1. 触发信号：确认最早出现的是业务异常、tg.cancel()，还是父任务被外部取消。不要用最后一条日志代替首个触发点。
2. 清理状态：确认每个被取消的子任务都经过 finally，连接、文件、锁或临时目录都有对应的释放记录。
3. 结果收口：确认业务异常没有被哨兵异常处理器误吞，主动终止也没有被告警系统当作失败率上升。

回滚路径也应和取消来源对应：故障触发时回滚未完成的批次；正常提前终止时保存已找到的结果并标记剩余任务为短路；外部取消时保留上层取消语义，让调用方决定是否重试。

常见问题

TaskGroup 会不会自动取消已经完成的任务？

不会。它只会处理尚未完成的任务，已经得到结果的任务不会因为兄弟失败而重新执行。

为什么捕获 CancelledError 后还要 raise？

因为取消是结构化并发的控制信号。清理完成后继续传播，TaskGroup 和上层调用方才能准确知道生命周期已经被取消。

except* 能不能替代 finally 做资源释放？

不能。except* 适合在外层按异常类型收口，资源属于哪个子任务，就应在那个子任务的 finally 中释放。

什么时候不要用显式取消？

如果剩余任务仍然有必须完成的副作用，例如提交不可重复的结算或写入审计记录，就不要把“提前得到一个结果”直接等同于可以取消全部兄弟任务，应先拆分任务边界。

总结一下：让 TaskGroup 负责组级协调，让子任务负责自己的清理，让 except* 负责按类型收口。这样无论是失败触发的兄弟取消，还是业务主动结束，都能在日志、回滚和告警层面保持可解释。