asyncio.wait_for会触发cancellederror但不保证任务停止，必须用asyncio.shield保护关键清理操作；shield需直接包裹协程对象，且内部子协程也须主动响应取消。
asyncio.wait_for 会无差别取消协程，但有些任务你绝不能让它被中断——比如正在写入数据库、释放锁、上传文件的清理操作。这时候必须用 asyncio.shield 包一层，否则超时后资源就真泄漏了。
asyncio.wait_for 取消协程时到底发生了什么
它不是“暂停”，而是调用 task.cancel() 并向协程抛出 asyncio.CancelledError。如果协程没做任何响应（比如没写 try/except CancelledError，也没检查 asyncio.current_task().cancelled()），它仍会在后台继续跑完——只是结果被丢弃。
- 常见表现：日志里看到“任务超时”，但数据库连接没关、临时文件没删、Redis锁没释放
- 根本原因：
wait_for只负责发信号，不保证任务真正停止 - 关键点：取消是否生效，取决于被等待协程内部是否配合（例如是否用了可取消的
await asyncio.sleep()，而非阻塞的time.sleep()）
什么时候必须套 asyncio.shield
当你有一段逻辑，无论外层是否超时，都必须完整执行完毕——尤其是带副作用的清理动作。
- 数据库事务提交或回滚（
await conn.commit()或await conn.rollback()） - 异步锁的释放（
await lock.release()） - 大文件分块上传后的最终确认（
await finish_upload()） - 调用第三方 SDK 的 close()、shutdown() 方法
注意：shield 不是万能的——它只保护被包裹的协程不被外层取消，但如果该协程自己又 await 了别的可取消协程，那些子协程仍可能被 cancel。
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
asyncio.shield 的正确写法和典型错误
它必须直接包裹「协程对象」，而不是调用结果；且不能和 wait_for 嵌套在同一个 await 表达式里，否则 shield 无效。
- ✅ 正确：
await asyncio.wait_for(asyncio.shield(cleanup()), timeout=3) - ❌ 错误：
await asyncio.shield(asyncio.wait_for(cleanup(), timeout=3))（这 shield 的是 wait_for 的返回值，不是 cleanup 本身） - ❌ 错误：
await asyncio.shield(cleanup())单独用（没配wait_for就没超时控制）
示例：
async def upload_and_finalize():
try:
await upload_chunks()
# 这一步绝不能被中断
await asyncio.wait_for(asyncio.shield(finalize_upload()), timeout=5)
except asyncio.TimeoutError:
log.error("finalize timed out — but shield kept it running")
# 这里不能 return，因为 shield 内部还在跑
比 shield 更容易被忽略的问题：嵌套取消传播
如果你的 cleanup() 内部又调用了另一个协程（比如 await db.close()），而那个协程没做取消处理，shield 也救不了它——取消信号仍会穿透进去。
- 验证方法：在 cleanup 协程开头加
print("cleanup started")，结尾加print("cleanup done")，看是否总能成对出现 - 安全做法：所有关键子协程都要主动监听取消，例如在循环中插入
if asyncio.current_task().cancelled(): break - 硬性限制：不要在
shield里调用同步阻塞函数（如requests.get），它会卡死整个事件循环
真正健壮的超时处理，从来不是靠一层 shield 就能兜住的——它只是最后一道防线，前面每一步是否可取消、是否及时响应、是否释放资源，才决定系统会不会在某个凌晨三点悄悄崩掉。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
