Python TaskGroup 怎样处理嵌套任务组异常

嵌套 asyncio.TaskGroup 出现异常时，最容易误判的是“外层只会收到一个错误”。实际边界是：内层任务组先等待并整理自己子任务中的非取消异常，形成 ExceptionGroup；外层任务组随后处理内层结果、自己的子任务异常以及取消信号。需要按异常类型处理时，用 except* 匹配异常组里的叶子异常，而不是把整个异常组当成一个普通异常对象。

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

实用结论是：把每个任务组当成一个异常边界；内层负责整理自己的子任务，外层用 except* 分流业务异常，未匹配的部分继续向上抛出。不要捕获后吞掉 asyncio.CancelledError，否则结构化并发的退出机制可能失效。

先看清嵌套 TaskGroup 的影响面

TaskGroup 不是简单的“批量创建任务”。当组内任意任务第一次抛出不是 asyncio.CancelledError 的异常时，组会取消尚未完成的同组任务并等待它们；所有需要报告的异常会在上下文管理器退出时合并。外层组看到的可能是一个包含内层 ExceptionGroup 的更大异常结构，因此普通的 except ValueError 不能替代 except* ValueError。

这也是为什么日志里经常出现多层 ExceptionGroup：它表达的是任务组的责任边界，不代表同一个错误被重复抛出了多次。内层组聚合一次，外层组再把内层聚合结果作为自己的子异常处理。

异常传播的时间线为什么从内层开始

把一次故障拆开看，责任边界会清楚很多：

1. 外层任务组创建一个负责批处理的内层任务组，同时还创建自己的兄弟任务。
2. 内层某个子任务抛出业务异常后，内层取消其余子任务，并等待清理完成。
3. 内层把仍需报告的异常组合成 ExceptionGroup，退出内层 async with。
4. 外层把这个内层异常组视为自己的子任务异常；如果外层还有其他异常，外层也会取消尚未完成的兄弟任务。
5. 外层完成等待后，再把内层异常组、外层主体异常和其他非取消异常组织成新的异常结构。

官方文档特别说明，内外任务组同时出现异常时，内层会先处理自己的异常，随后外层会收到另一次取消并处理自己的异常。这里的“另一次取消”是任务组内部唤醒 __aexit__() 的机制，不应和业务方主动取消任务混为一谈。

用一个最小结构定位异常从哪里来

下面的代码只展示责任边界和异常处理形状，不依赖某一次调度的先后顺序。两个内部函数代表不同业务来源，外层函数代表一个更大的工作单元：

import asyncio


class ConfigError(Exception):
    """配置分支的业务异常。"""


class DataError(Exception):
    """数据分支的业务异常。"""


async def load_config():
    # 这里用业务异常代替真实配置读取，重点是异常类型边界。
    raise ConfigError("配置不可用")


async def load_data():
    # 这里用另一种异常表示数据分支，便于观察 except* 的分流。
    raise DataError("数据不可用")


async def inner_group():
    # 内层只负责整理自己的子任务，不越权处理外层业务。
    async with asyncio.TaskGroup() as group:
        group.create_task(load_config())
        group.create_task(load_data())


async def outer_group():
    # 外层把内层工作单元和自己的任务放进同一个生命周期边界。
    async with asyncio.TaskGroup() as group:
        group.create_task(inner_group())
        group.create_task(asyncio.sleep(0))


async def main():
    try:
        await outer_group()
    except* ConfigError as errors:
        # except* 匹配异常组中的 ConfigError，并保留原有嵌套结构。
        print("配置分支数量：", len(errors.exceptions))
    except* DataError as errors:
        # 未被上一分支处理的 DataError 继续进入当前分支。
        print("数据分支数量：", len(errors.exceptions))


asyncio.run(main())  # 由 asyncio 负责创建事件循环并等待主协程。

这段代码的重点不是打印出的数量，而是两个 except* 分支都针对异常组内部的匹配项工作。匹配结果仍然保留原来的嵌套关系，所以处理器拿到的 errors 可能仍是一个分组，而不是裸的 ConfigError 实例。

触发条件里有三个容易混淆的边界

还要注意版本边界：TaskGroup 从 Python 3.11 引入；较新的 Python 文档还描述了同时发生内部、外部取消时的处理改进。文章讨论的是异常传播模型，实际项目仍应以部署的 Python 版本文档为准。

用 except* 按类型处理，而不是吞掉整棵树

except* 的价值在于可以把一棵异常树拆成多个类型分支；一个分支处理后，未处理的部分会继续传播。处理器里适合做分类、记录、转换或补偿，不适合把所有异常都打印成一行字符串就结束。

def iter_leaf_exceptions(group):
    # 递归保留异常组的叶子，方便日志系统记录真实业务类型。
    for item in group.exceptions:
        if isinstance(item, BaseExceptionGroup):
            yield from iter_leaf_exceptions(item)
        else:
            yield item


async def run_with_classified_errors():
    try:
        await outer_group()
    except* ConfigError as errors:
        # 对配置问题执行降级，但只处理匹配到的子树。
        for leaf in iter_leaf_exceptions(errors):
            print("记录配置异常：", leaf)
    except* DataError as errors:
        # 数据问题可以进入重试队列，未匹配异常仍会自动向上抛出。
        for leaf in iter_leaf_exceptions(errors):
            print("记录数据异常：", leaf)

BaseExceptionGroup 是递归判断的基类，能够覆盖普通异常组以及包含更高层基类异常的分组。不要在 except* 中匹配 ExceptionGroup 本身来代替业务异常类型；这里要关心的是组里的叶子类型。对于不确定是否可恢复的分支，记录后直接让它继续传播，通常比返回一个“看似成功”的结果安全。

防止下一次故障变成难读的异常树

第一，内层任务组只处理自己能判断的业务异常，转换后的异常要带上来源信息；不要在内层把所有异常都改成同一个通用类型，否则外层无法区分配置、数据和外部依赖。

第二，清理协程不要无条件吞掉 CancelledError。如果必须在 finally 中释放资源，可以完成释放后让取消继续向上传播。TaskGroup 和超时机制内部都依赖取消协作，吞掉取消会让退出行为变得不可预测。

第三，日志记录要保留任务组层级、异常类型、消息和上下文，而不是只记录最外层字符串。一个简单的递归函数能把叶子异常抽出来，但生产日志最好同时保存组的层级信息，这样才能知道故障属于哪个任务边界。

第四，恢复策略要和异常类型对应：配置异常可以走默认配置，数据异常可能进入重试，未知异常则应保留原始异常链并交给上层决策。不要因为 except* 能拆分异常，就在每个分支里都返回成功。

速查表：嵌套异常该怎么判断

常见问题

为什么普通 except Exception 没有把每个错误都拿到？

普通 except 面向抛出的整体异常对象；嵌套任务组抛出的是异常组。要按异常组里的成员类型分开处理，应使用 except*，并在处理器里按需展开分组。

内层 TaskGroup 抛出后，外层还会继续执行兄弟任务吗？

外层会按照自己的 TaskGroup 规则取消尚未完成的兄弟任务并等待它们。已经完成的任务不会被回滚，仍需报告的异常会参与外层的异常组合。

可以在 except* 里把所有错误转成 None 吗？

可以写出这样的代码，但通常不应该这样做。只有明确可恢复的异常才应在对应分支中被消费；未确认的异常应继续抛出，否则调用方会得到一个不真实的成功状态。

如何记录嵌套 ExceptionGroup？

至少记录任务组名称、分组消息、叶子异常类型和异常链。递归遍历 group.exceptions 可以获得叶子，但排障时还应保留每层分组的上下文。

嵌套 TaskGroup 的关键不是记住某个固定输出，而是理解“内层先聚合、外层再组合”的责任边界。用 except* 做类型分流，保留未处理子树，并让取消信号正常传播，异常处理才会随着任务组层级扩展而保持可读。