WSGI模式下Django调用asyncio触发SynchronousOnlyOperation错误排查

先搞懂WSGI+gevent下的请求上下文逻辑 #

Django在WSGI模式运行时，每个同步请求的专属数据（比如数据库连接、当前请求对象）都存在协程本地存储空间里（gevent用协程替代线程，用greenlet本地存储代替线程本地存储），各请求的上下文相互隔离。同时gevent通过monkey-patch修改了Python标准库，让asyncio的异步事件循环能和gevent的协程调度兼容，但这种兼容逻辑没考虑Django的上下文隔离需求。

asyncio.run的问题出在哪？ #

• asyncio.run会创建一个全新的asyncio事件循环，运行期间这个循环会占据当前协程的执行权。
• 当你的异步IO操作超过5秒时，gevent的调度器会暂时挂起这个跑事件循环的协程，转而去处理其他同步请求的协程。此时这些新的同步请求代码会运行在已经存在asyncio事件循环的上下文环境中。
• Django有严格的环境检测机制：如果检测到当前代码处于asyncio事件循环里，却调用了仅支持同步的操作（比如健康检查接口里的数据库查询、基础视图渲染逻辑），就会抛出SynchronousOnlyOperation异常——它默认这类同步操作不该出现在异步环境中。
• 核心问题是asyncio.run是Python原生方法，完全不知道Django的上下文隔离规则，不会做环境的切换与恢复，导致无关的同步请求被错误判定为处于异步环境。

为什么async_to_sync能解决问题？ #

async_to_sync是Django依赖的asgiref库提供的同步/异步互调专用工具：

• 它会把当前同步请求的专属上下文（比如数据库连接）安全传递到异步函数中，保证异步代码能正常访问这些数据。
• 更关键的是，它会在异步函数运行前后正确切换环境标识：异步函数执行时使用异步环境，结束后立刻恢复为同步环境，其他同步请求进来时，Django检测到的依然是正常的同步环境，不会触发异常。

内容的提问来源于stack exchange，提问作者user2283347