Python asyncio.shield 保护后台任务免受外层取消

asyncio.shield() 能保护内部 Task 不被“等待它的外层协程取消”连带取消，但它不会替调用方吞掉取消：外层仍然会收到 asyncio.CancelledError。真正稳妥的写法还要做三件事：保留 Task 的强引用、回收最终结果或异常、为退出等待设置上限。

官方文档：https://docs.python.org/3/library/asyncio-task.html#shielding-from-cancellation

先看故障表现：外层取消不等于后台任务应该消失

Web 请求超时、客户端断开、服务关闭，都可能让当前处理协程被取消。如果支付确认已经完成，而审计写入、状态回传或幂等落库只差最后一步，直接把这些动作放在当前协程中等待，就会让取消沿等待链向下传播。

常见的误判是：“加了 shield，外层就不会再报 CancelledError。”事实正好相反。shield 保护的是内部 Task，不是调用者。调用者需要及时感知取消，才能释放连接、归还资源并结束请求；后台任务则可以按照业务约束继续完成。

import asyncio

async def persist_audit(event: dict) -> None:
    # 这里代表必须完整提交的短事务；真实项目应保证幂等
    await asyncio.sleep(0.3)
    print(f"audit saved: {event['id']}")

async def handle_request(event: dict) -> None:
    # 先显式创建 Task，后续才能持有引用并观察最终状态
    task = asyncio.create_task(persist_audit(event), name="persist-audit")
    await asyncio.shield(task)

这段最小写法只解决取消传播，还没有解决 Task 引用、异常回收和退出上限，因此不宜直接当成生产模板。

shield 真正隔离的是哪一段取消传播

当 handle_request 被取消时，等待 shield(task) 的表达式会抛出 CancelledError，但这次取消不会继续传给 task。从后台协程的视角看，这次外层取消没有发生。

要特别分清两条取消来源：

• 外层取消：取消等待者，shield 阻止它继续取消内部 Task。
• 任务自身或其他代码取消：如果有人直接调用 task.cancel()，或者任务内部进入取消状态，shield 不会把它恢复成成功。

因此，shield 是取消传播边界，不是“任务永不取消”的保证，也不是后台作业系统。

用强引用和完成回调保住后台任务

Python 官方文档提醒，事件循环只保留 Task 的弱引用。可靠的后台任务应由应用自己的集合持有，并在完成时移除。回调还必须读取异常，否则失败的任务可能在之后留下“Task exception was never retrieved”警告。

import asyncio
import logging

logger = logging.getLogger(__name__)
background_tasks: set[asyncio.Task[None]] = set()

def collect_task_result(task: asyncio.Task[None]) -> None:
    # 完成后先释放集合中的强引用，避免集合持续增长
    background_tasks.discard(task)
    try:
        # result() 会取回任务异常，避免异常无人观察
        task.result()
    except asyncio.CancelledError:
        logger.info("background task cancelled: %s", task.get_name())
    except Exception:
        logger.exception("background task failed: %s", task.get_name())

def start_audit_task(event: dict) -> asyncio.Task[None]:
    # Task 被集合持有，直到完成回调主动移除
    task = asyncio.create_task(persist_audit(event), name=f"audit-{event['id']}")
    background_tasks.add(task)
    task.add_done_callback(collect_task_result)
    return task

这种结构把“谁拥有 Task”和“谁处理失败”写得很清楚。若后台动作需要跨进程可靠执行、失败重试或服务重启后恢复，就不应只依赖内存中的 Task，而应改用持久队列、任务表或专门的作业系统。

给关键收尾增加有限等待窗口

有些业务希望外层取消后，仍给后台收尾一个很短的完成窗口。可以在捕获取消后再次通过 shield 等待同一个 Task，并用 asyncio.timeout() 限制等待时间；最后必须重新抛出原始取消，让上层正确结束。

import asyncio

async def handle_request(event: dict) -> None:
    task = start_audit_task(event)
    try:
        # 正常路径直接等待；外层取消不会传给内部 Task
        await asyncio.shield(task)
    except asyncio.CancelledError:
        try:
            async with asyncio.timeout(1.0):
                # 只给同一个 Task 一秒收尾时间，不能创建第二份任务
                await asyncio.shield(task)
        except TimeoutError:
            # 超时只结束本次等待，Task 仍由集合和完成回调管理
            pass
        finally:
            # 传播调用方的取消，保留 asyncio 的协作式取消语义
            raise

这里的“一秒”只是示例，实际值应由请求预算、关闭时限和业务幂等性共同决定。不要在取消处理里无限等待，也不要为了“继续运行”而随意调用 uncancel()。普通应用代码通常应在清理完成后继续传播 CancelledError。

识别 shield 不能解决的三类取消

还要谨慎处理 TaskGroup。它的价值是让相关子任务共享清晰的生命周期与失败传播规则。如果把某个子任务随意 shield 出结构化作用域，可能破坏“作用域退出时所有子任务都已结束”的假设。只有任务在业务上确实独立于该作用域时，才应把它移到独立所有者管理的后台集合中。

上线前检查与常见问题

• 受保护任务是否短小、幂等，并且重复执行不会造成双写？
• 是否保存了 Task 强引用，并在完成后清理引用？
• 是否调用 result() 或等价方式取回异常？
• 捕获 CancelledError 后是否完成清理并重新抛出？
• 退出等待是否有明确上限，服务关闭时是否能停止继续接收新任务？
• 需要重试、持久化或跨重启恢复时，是否已经改用持久队列？

直接把协程传给 shield 可以吗？

可以，shield 会把协程调度为 Task。但显式使用 create_task() 更容易保存强引用、命名任务、注册完成回调和检查状态，因此后台任务更推荐显式创建。

为什么捕获 CancelledError 后还要 raise？

取消是 asyncio 的协作控制信号。清理后继续传播，调用链和结构化并发组件才能正确结束。吞掉取消可能让超时与 TaskGroup 的内部语义异常，也会让上层误以为操作成功完成。

shield 能保证任务一定完成吗？

不能。进程退出、事件循环停止、任务自身异常、显式取消和资源错误都可能让任务失败。shield 只隔离一种取消传播路径；可靠交付仍需要任务所有权、异常回收、幂等设计以及必要时的持久化队列。

归根结底，asyncio.shield 最适合保护“必须尽量完成、但不应阻塞调用方取消”的短收尾任务。把取消边界、Task 所有权和失败处理一起设计，才能避免只加一层 shield 却留下新的后台失联问题。