TaskGroup 是 Python 3.11 引入的、用于安全并发管理的上下文管理器，核心解决 asyncio.gather 在异常时粗暴取消任务导致资源清理失败的问题；它确保任一子任务异常时，其余任务能响应取消并执行 async with/finally 清理逻辑后再聚合抛出 ExceptionGroup。
TaskGroup 是什么，为什么不用 asyncio.gather
Python 3.11 引入的 asyncio.TaskGroup 不是语法糖，而是为了解决 asyncio.gather 在异常传播和资源清理上的硬伤。当你并发启动多个协程，其中某个中途抛出异常，gather(return_exceptions=False) 会立刻取消其余任务，但不保证它们能安全退出——比如正在写文件、发 HTTP 请求或释放锁的协程可能被粗暴中断。
TaskGroup 的核心保障是：所有子任务共享同一个生命周期上下文，任一任务异常时，其他任务会收到取消信号，并**等待它们自行完成清理逻辑（如 async with 或 try/finally）后再向上冒泡**。
- 必须在
async with TaskGroup()块内调用create_task()，否则报RuntimeError: TaskGroup is closed -
gather返回结果列表顺序固定，TaskGroup不承诺顺序，需靠任务自己返回标识（如传入id参数） - 不能在
TaskGroup外部 await 单个子任务，否则破坏结构约束
如何正确启动并捕获子任务异常
常见误区是把 TaskGroup 当作更“高级”的 gather，试图统一 catch 所有异常。实际它只保证“异常发生时其他任务有机会收尾”，异常本身仍要由你显式处理。
典型写法是让每个子任务内部处理自己的错误，或用 except BaseException 捕获后包装成结果的一部分；若想集中处理，应在 async with TaskGroup() 外层再套 try-except：
立即学习“Python免费学习笔记（深入）”；
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
async def fetch_user(user_id):
async with httpx.AsyncClient() as client:
resp = await client.get(f"/api/user/{user_id}")
resp.raise_for_status()
return resp.json()
<p>async def main():
try:
async with asyncio.TaskGroup() as tg:
task1 = tg.create_task(fetch_user(1))
task2 = tg.create_task(fetch_user(2))
task3 = tg.create_task(fetch_user(3))</p><h1>这里才真正拿到全部结果（或首个异常）</h1><pre class="brush:php;toolbar:false;"> results = [task1.result(), task2.result(), task3.result()]
except* httpx.HTTPStatusError as eg:
# 注意：是 except*，不是 except
print(f"多个请求失败：{len(eg.exceptions)} 个")
-
except*是 Python 3.11 新语法，专用于匹配ExceptionGroup（TaskGroup抛出的异常类型） - 单个子任务抛出异常不会立即中断
async with块，但块退出时会聚合所有未处理异常 - 如果子任务里用了
sys.exit()或os._exit()，TaskGroup无法拦截——这类操作应避免在协程中使用
与 aiofiles / aiomysql 等异步库配合的关键点
很多用户以为只要用了 TaskGroup，异步 I/O 就自动线程安全了。其实不然：TaskGroup 解决的是任务生命周期协同问题，不是数据竞争问题。
比如多个子任务同时写同一个文件，或并发更新数据库同一行记录，依然需要显式加锁或用事务隔离：
- 用
aiofiles.open(..., mode="a")追加写时，OS 层面通常原子，但内容拼接仍可能错乱，建议每个任务写独立文件，后续合并 - 对共享变量（如
list或dict）做修改，必须用asyncio.Lock包裹，不能依赖“协程切换少”来赌运气 -
aiomysql连接对象不是线程安全的，更不是协程安全的——每个子任务应使用自己的连接，或从连接池acquire()后及时release()
性能影响：TaskGroup 本身几乎零开销，但别误用
TaskGroup 的实现基于现有 asyncio 事件循环机制，创建/销毁开销可忽略。真正影响性能的是你让它管理的任务数量和行为模式。
- 不要在一个
TaskGroup里启动上千个任务——不是语法限制，但会拖慢异常聚合和取消通知，建议按批分组（如每 100 个一组） - 避免在
TaskGroup内部嵌套另一个TaskGroup，除非业务逻辑明确需要分层取消语义；否则增加调度复杂度 - 如果所有子任务都是 CPU 密集型（如解析大 JSON），
TaskGroup不会加速它们，反而因协程切换产生额外成本，此时应考虑loop.run_in_executor
最易被忽略的一点：TaskGroup 不改变协程本身的执行顺序或优先级，它只是给并发任务加了一道“协同退出协议”。是否真正提升安全性，取决于你有没有在每个子任务里写好清理逻辑、有没有管住共享状态、有没有用对异常捕获语法。
