asyncio.wait_for 是处理异步超时的首选，因其原生支持、语义清晰、不侵入任务逻辑；需确保 awaitable 为未启动协程、timeout 合理设置，且被等协程须响应取消信号。
wait_for 为什么是处理异步超时的首选
因为 asyncio.wait_for 是 asyncio 原生支持的、语义最清晰的超时控制机制——它不依赖手动轮询或信号，也不修改任务本身逻辑，只在等待层面加一层“时间围栏”。其他方式（比如用 asyncio.create_task + asyncio.sleep 配合 asyncio.shield）容易漏掉取消传播或状态残留。
wait_for 的三个关键参数怎么配才不踩坑
常见错误是只传 timeout，忽略 loop（已弃用）和 return_when（不适用），但真正要小心的是第一个参数 awaitable 必须是可等待对象，且不能是已取消/已完成的状态；否则会立刻抛 InvalidStateError 或直接返回结果，导致超时逻辑失效。
-
awaitable：必须是未启动的协程对象（如fetch_data()），不能是await fetch_data()（那已经是值了） -
timeout：设为None表示永不超时；设为数字（如5.0）单位是秒，支持浮点；设为 0 会立即触发超时 - 如果
awaitable在超时前完成，wait_for返回其结果；超时则抛asyncio.TimeoutError，不是TimeoutError
TimeoutError 捕获后，原任务真的被取消了吗
是的，wait_for 在超时发生时会调用 task.cancel()，但这个取消操作是“尽力而为”——若原协程正在执行 CPU 密集型同步代码（比如 time.sleep(10)），不会被中断；只有在 await 点才会响应取消。所以务必确保被包装的协程内部有合理的 await 分割，并在关键位置检查 if task.cancelled(): return。
典型误用：
async def bad_io():
time.sleep(10) # 同步阻塞，cancel 无效
return "done"应改为 await asyncio.sleep(10)。并发多个 wait_for 时要注意资源竞争
多个 wait_for 并发等待同一个底层连接（比如共用一个 aiohttp.ClientSession），可能因连接池耗尽或服务端限流导致连锁超时。这不是 wait_for 的问题，而是上游资源没做隔离。
- 每个
wait_for实例独立管理自己的取消逻辑，互不干扰 - 但底层 IO（如 socket、HTTP 连接）是共享的，超时频繁发生时建议限制并发数（用
asyncio.Semaphore） - 不要对同一
awaitable多次套wait_for，会触发重复取消，引发RuntimeError: Task is already done
实际超时处理中最容易被忽略的，是协程内部对取消信号的响应能力——光靠 wait_for 设时间围栏不够，还得让被等的逻辑“听得见”。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
