asyncio.wait_for设计为“超时即异常”，不返回默认值而抛TimeoutError，因其核心目标是强制中断而非容错；必须用try/except捕获并手动提供fallback，同时确保被取消协程的资源清理。
asyncio.wait_for 为什么总是抛出 TimeoutError 而不是返回结果？
因为 asyncio.wait_for 的设计就是「超时即异常」：它不会静默失败，只要任务没在指定时间内完成，就一定会 raise TimeoutError。这不是 bug，是控制流的一部分——你得用 try/except 显式捕获它。
常见误用是直接写 result = asyncio.wait_for(coro, timeout=2) 然后接着用 result，一旦超时，代码就中断了，后续逻辑根本跑不到。
- 必须用
try/except asyncio.TimeoutError:包裹调用 -
wait_for返回的是原协程的返回值（成功时），不是封装后的对象 - 超时后，被等待的协程**不会自动取消**（Python 3.11+ 默认会，但旧版本不会）——这意味着它可能还在后台运行，造成资源泄漏或重复副作用
如何确保超时后协程真正被取消？
显式传入 shield=False（默认值）还不够，关键要看 Python 版本和是否手动处理取消逻辑。3.11 前需自己 cancel；3.11+ 默认启用取消，但前提是协程本身能响应 CancelledError。
稳妥做法是：用 asyncio.create_task() 包一层，再传给 wait_for，并在 except 块中主动 task.cancel()：
立即学习“Python免费学习笔记（深入）”；
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
task = asyncio.create_task(some_coro())
try:
result = await asyncio.wait_for(task, timeout=3)
except asyncio.TimeoutError:
# 即使 3.11+，也建议显式 cancel 来确保清理
task.cancel()
try:
await task # 让 CancelledError 真正抛出并被处理
except asyncio.CancelledError:
pass
raise # 或返回默认值
timeout 参数传 float 还是 int？精度和系统限制要注意什么？
timeout 接受 float（如 0.1、2.5），但实际精度受限于事件循环的调度粒度和系统定时器分辨率。在 Linux 上通常约 10–15ms，在 Windows 可能更差（尤其旧版本）。
- 不要指望
timeout=0.001（1ms）能稳定生效 - 小于 0.01 的值在多数生产环境意义不大，还可能因浮点误差导致意外超时
- 传
None表示永不超时（等价于不调用wait_for） - 传负数会立即触发
TimeoutError
和 asyncio.timeout() 上下文管理器比，什么时候该选 wait_for？
asyncio.timeout()（3.11+）更现代、语义更清晰，适合「整个代码块」设超时；而 wait_for 更底层、兼容老版本，且能单独控制某个协程——比如你只想给网络请求设超时，但后续解析逻辑不设限。
典型场景：wait_for 更适合嵌套调用或需要精细控制取消时机的地方；如果只是简单包装一个协程，且环境支持 3.11+，优先用 asyncio.timeout()。
注意：wait_for 不支持「超时后继续执行其他分支」这种写法，它的控制粒度只到协程级别，没法像 timeout() 那样包裹任意同步/异步混合逻辑。
超时处理真正的难点从来不在语法，而在协程是否真的可取消、取消后状态是否干净、以及 timeout 值是否在目标环境中具备实际意义。
