如何将‘coroutine never awaited’作为异常捕获处理？

问题说明 #

大型项目里，协程未被await的情况很难完全避免，这类问题因静默特性容易被长期忽略。需要实现一套主动处理机制：当出现协程未被await时，要么触发指定函数，要么抛出可捕获的异常。此前尝试通过warnings.simplefilter('error', RuntimeWarning)将警告转为错误，但该方法无效，控制台仅输出Exception ignored in: <coroutine object XXX at 0x7fbca2e4eb90>，无法捕获并响应这个错误。

有效解决方案 #

方法1：重写协程的__del__方法拦截销毁事件 #

协程对象被垃圾回收时会触发__del__方法，通过修改types.CoroutineType的__del__方法，可以注入自定义处理逻辑：

import types

def custom_coroutine_cleanup(self):
    # 判断协程是否未执行完成
    if not self.done():
        # 替换为你的自定义逻辑：比如抛出可捕获异常
        raise RuntimeError(f"协程未被await就被销毁: {self}")
        # 或者调用指定处理函数
        # notify_unawaited_coroutine(self)

# 替换默认的协程销毁方法
original_del = types.CoroutineType.__del__
types.CoroutineType.__del__ = custom_coroutine_cleanup

注意：该方法在部分Python版本或复杂场景下可能存在兼容性问题，需要结合项目环境测试验证。

方法2：通过sys.excepthook捕获被忽略的异常 #

协程未被await时，Python会在销毁阶段抛出RuntimeWarning但主动忽略，利用sys.excepthook可以拦截这类被忽略的异常：

import sys

def custom_exception_handler(exctype, value, tb):
    if exctype is RuntimeWarning and "coroutine never awaited" in str(value):
        # 将警告转为可捕获的RuntimeError
        raise RuntimeError("检测到未被await的协程") from value
    # 其他异常沿用默认处理逻辑
    sys.__excepthook__(exctype, value, tb)

sys.excepthook = custom_exception_handler

这种方式依赖Python抛出警告的时机，部分场景下可能无法100%覆盖所有未被await的协程。

方法3：静态代码检查（提前预防） #

在大型项目中，优先通过静态检查工具从源头避免这类问题：

• 使用pylint的missing-await规则，扫描代码中未被await的协程调用
• 启用mypy严格类型检查模式，会直接提示未await的协程调用

原方案无效的原因 #

协程未被await的警告是在对象被垃圾回收时异步抛出的，此时Python的警告机制无法将其转为可捕获的错误，只能输出"Exception ignored"的日志信息，常规的try-except和warnings.simplefilter都无法拦截这类异步抛出的警告。

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