Python异步IO为什么不起作用_检查是否漏写await或混用同步代码

Python异步编程：为什么你的async代码“跑”不起来？

不少开发者初次接触Python的asyncio时，都会遇到一个共同的困惑：代码明明没报错，但异步效果就是出不来，程序跑得跟同步一样慢。问题出在哪？其实，症结往往不在于复杂的框架原理，而是一些看似基础却极易踩中的“隐形坑”。下面就来盘点几个最常见的“异步失效”场景。

async函数里没加await，调用就变成同步执行

首先要明确一个核心概念：Python中的async函数，其本身并不执行任何异步操作。当你调用一个async def定义的函数时，它仅仅是返回一个coroutine（协程）对象。如果你只是写了fetch_data()而忘了在前面加上await，那么这个协程对象就会被静默地创建，然后被丢弃——它根本不会运行。

这时，你可能会在控制台看到一个RuntimeWarning: coroutine 'fetch_data' was never awaited的警告，但在某些环境（比如Jupyter Notebook或部分IDE）里，这个警告可能被默认忽略，让你误以为代码正常。

• 检查所有调用点：确保每一个async函数的调用，都出现在另一个async函数内部，并且前面有await关键字。
• 正确启动入口：在模块的最顶层，不能直接使用await，必须通过asyncio.run(main())这样的方式来启动事件循环。
• 警惕“无效赋值”：别把协程对象赋值给变量后就不管了，比如coro = fetch_data(); result = coro，这行代码实际上什么也没做，fetch_data从未被执行。

混用同步阻塞调用（如time.sleep、requests.get）导致整个event loop卡住

这是性能杀手。asyncio的事件循环（event loop）是单线程的，它依靠协程的主动挂起（await）和恢复来实现并发。一旦你在协程中执行了一个同步阻塞操作，比如time.sleep(5)或者同步的requests.get()，整个事件循环线程就会被卡住，所有其他任务都得停下来等它完成。

想象一下这个场景：你本想并发请求10个API，但因为其中一个不小心用了requests.get，结果其他9个任务全都只能干等着。

• 替换睡眠函数：将time.sleep 替换为 await asyncio.sleep。
• 使用异步HTTP客户端：将同步的requests库替换为aiohttp.ClientSession或httpx.AsyncClient。
• 处理遗留同步代码：如果必须使用某个同步库，可以用loop.run_in_executor()将其放到线程池中运行，避免阻塞主循环。不过要注意线程切换的开销和可能的上下文丢失问题。

忘记在async函数里用await调用另一个async函数

这个错误相当隐蔽。你定义了两个async函数A和B，并在A中调用了B，但写成了B()而不是await B()。结果，B的协程对象被创建了，但因为没有await，它被立即丢弃，函数A继续执行后续代码，而B内部的逻辑压根没跑。

举个例子：async def load_user(): return await db_query()，如果不慎写成了return db_query()，那么load_user函数会立刻返回一个协程对象（而非查询结果），并且db_query函数中的数据库操作实际上从未发生。

• 逐行审查：仔细检查每个async函数内部的所有函数调用，只要被调用的函数返回的是协程对象，前面就必须加await。
• 借助工具：使用IDE的类型提示（例如，函数标注返回Awaitable[T]类型）或像mypy这样的静态类型检查工具，可以帮助识别漏掉的await。
• 快速调试：如果不确定，可以临时print(type(some_call()))，如果输出是，那就说明你忘记await了。

await在非async函数里使用，语法直接报错

这是一个硬性语法规则：await关键字只能出现在由async def定义的函数体内。如果你把它写在普通的def函数、模块顶层、或者某个if分支里（但外层函数不是async），Python解释器会直接抛出SyntaxError: invalid syntax。

容易出错的地方包括：条件分支嵌套过深、代码重构时剪切了一段逻辑却忘了给新函数加上async、或者误以为某些Web框架的装饰器（如FastAPI的@router.get）会自动提供异步上下文。

• 确认函数定义：检查你写await的那个函数，其定义是否以async def开头，而不是def。
• 注意框架要求：在使用FastAPI、Starlette等异步Web框架时，路由处理函数必须定义为async def，否则其中的await将无效或导致错误。
• 交互式环境限制：在IPython等交互式环境中，通常不支持顶层的await。你需要确保await位于async函数内，或者直接使用asyncio.run(coro)来执行。

说到底，真正让异步程序“卡住”的，往往不是那些会直接报错的语法问题，而是那些“看起来在跑，实际上没有并发”的静默错误。比如漏写一个await、混入一个time.sleep、或者用requests发了10个串行请求却自以为实现了异步。调试时，一个简单有效的方法是：在关键任务的开始和结束处打上print(“start”)和print(“done”)日志，观察它们的执行顺序和时间间隔，这比凭空猜测要可靠得多。