Tornado框架中Handler调用异步函数报错问题排查

核心问题原因 #

你遇到的coroutine 'MainHandlerIndex.get' was never awaited警告，本质是异步协程调用后未被正确等待：

• 当用@gen.coroutine装饰Handler的get方法时，该方法本身是一个协程；内部调用其他异步协程函数时，如果不通过yield（旧版Tornado）或await（新版Tornado）挂起等待，被调用的协程会处于未执行状态，Python会抛出警告。
• 若你混用了@gen.coroutine和原生async def语法，也可能触发该问题。

快速修复方案 #

根据你的Tornado版本，选择对应写法：

方案1：现代Tornado（5.0+，推荐） #

弃用@gen.coroutine，改用Python原生async def/await语法，这是Tornado官方推荐的现代异步写法：

class MainHandlerIndex(tornado.web.RequestHandler):
    @decoradores.authenticated
    async def get(self):
        # 关键：用await等待异步函数执行完成
        await your_async_function()
        self.render("index.html")

方案2：兼容旧版Tornado（4.x及以下） #

如果必须保留@gen.coroutine，用yield替代await来等待异步协程：

class MainHandlerIndex(tornado.web.RequestHandler):
    @decoradores.authenticated
    @gen.coroutine
    def get(self):
        # 关键：用yield等待异步协程
        yield your_async_function()
        self.render("index.html")

额外检查：自定义装饰器兼容性 #

如果@decoradores.authenticated是你自己实现的装饰器，必须确保它支持异步函数。示例如下：

def authenticated(method):
    async def wrapper(self, *args, **kwargs):
        if not self.current_user:
            if self.request.method in ("GET", "HEAD"):
                self.redirect(self.get_login_url())
                return
            raise tornado.web.HTTPError(403)
        # 异步调用原方法
        return await method(self, *args, **kwargs)
    return wrapper

正确的Tornado异步调用架构 #

1. 协程语法选择 #

• Tornado 5.0+优先使用async def/await原生协程，替代旧的@gen.coroutine，语法更简洁且符合Python现代规范。
• 若维护旧项目，@gen.coroutine需配合yield使用，注意不要混用两种语法。

2. 装饰器顺序 #

权限类装饰器（如@authenticated）必须放在异步语法（async def或@gen.coroutine）的上层，确保先完成权限校验，再进入异步逻辑。

3. 异步操作规范 #

所有IO密集型操作（数据库查询、HTTP请求、文件读写）必须使用异步实现：

• 数据库：用异步驱动（如motor for MongoDB、asyncpg for PostgreSQL）
• HTTP请求：用Tornado自带的AsyncHTTPClient
• 同步阻塞函数：若必须使用，放到线程池执行，示例：

  async def get(self):
      # 将同步函数放到线程池执行，避免阻塞事件循环
      result = await tornado.ioloop.IOLoop.current().run_in_executor(None, your_sync_function)
      self.render("index.html", data=result)
  

4. 错误处理 #

异步逻辑中的异常处理和同步代码一致，用try/except包裹await或yield语句：

async def get(self):
    try:
        await risky_async_function()
    except Exception as e:
        self.set_status(500)
        self.write(f"Error: {str(e)}")

内容的提问来源于stack exchange，提问作者Kentron.dna