SQLAlchemy + Pytest：如何优雅地关闭异步数据库连接池

在开发高性能异步 Python 服务时，SQLAlchemy 配合 aiomysql 是标准的"黄金搭档"。然而，许多开发者在编写单元测试时，都会遇到一个令人困惑的报错：RuntimeError: Event loop is closed。

即便你在代码中显式调用了 await engine.dispose()，这个错误依然会像幽灵一样在测试结束时蹦出来。本文将深入剖析其底层成因，并提供一套工业级的解决方案。

1. 现象：明明关闭了引擎，为何报错？

在 Pytest 中使用 session 作用域的异步引擎时，典型的报错堆栈如下：

lua 复制代码

Exception ignored in: <function Connection.__del__ at 0x112ee7600>
Traceback (most recent call last):
  File ".../aiomysql/connection.py", line 1131, in __del__
    self.close()
  File ".../aiomysql/connection.py", line 339, in close
    self._writer.transport.close()
RuntimeError: Event loop is closed

困惑点： 我们的测试逻辑已经运行完毕，数据库清理也做了，为什么 Python 解释器仍试图在事件循环关闭后去操作连接？

2. 深度剖析：对象生命周期的"时间差"

问题的根源在于：逻辑上的"引擎销毁"不等于内存中的"对象回收"。

2.1 析构函数（del）的滞后性

当你调用 engine.dispose() 时，SQLAlchemy 只是宣布连接池关闭。但底层 aiomysql 的 Connection 对象可能仍被某些存活的引用（如未被清理的变量、循环引用或 GC 延迟）持有。

当 Pytest 结束 event_loop fixture 并调用 loop.close() 后，Python 的垃圾回收器（GC）才开始真正清理这些不再使用的连接对象。此时，对象的 __del__ 方法被触发，它试图通过 loop 来关闭底层的 Socket 传输层------但此时 loop 已经死了。

2.2 循环引用的陷阱

异步框架中，对象之间常形成复杂的引用环。Python 依靠分代回收机制处理循环引用，这使得资源释放的时机变得更加不可预测。

3. 终极解决方案：构建"异步清理屏障"

要彻底解决此问题，我们必须在 event_loop 关闭之前，强行同步对象回收过程。我们采用 "同步辅助函数 + 显式 GC + 任务周转" 的组合拳。

核心实现：`tests/conftest.py`

Python

python 复制代码

import gc
import asyncio
import pytest

def _cleanup_database_engines(loop):
    """工业级异步引擎清理方案"""
    try:
        # 1. 显式关闭异步引擎（清空连接池）
        async def dispose_engines():
            # 替换为你的引擎对象
            await your_async_engine.dispose()
        
        loop.run_until_complete(dispose_engines())

        # 2. 强制垃圾回收
        # 第一次清理普通对象，第二次清理因第一轮释放而暴露的循环引用
        gc.collect()
        gc.collect()

        # 3. 关键：给事件循环最后一次"呼吸"的机会
        # gc 触发的 __del__ 可能会向 loop 提交最后的清理 task
        # sleep(0) 能让 loop 切换上下文并执行这些就绪任务
        loop.run_until_complete(asyncio.sleep(0))
        
    except Exception as e:
        print(f"Cleanup Error: {e}")

@pytest.fixture(scope='session')
def event_loop():
    policy = asyncio.get_event_loop_policy()
    loop = policy.new_event_loop()
    yield loop

    try:
        # 清理所有待处理任务
        pending = asyncio.all_tasks(loop)
        if pending:
            loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
    finally:
        # 在 loop.close() 前执行清理屏障
        _cleanup_database_engines(loop)
        loop.close()

4. 方案的三大硬核知识点

A. 为什么不用 Async Fixture 直接清理？

在 Pytest 中，session 级别的 async fixture 清理时机往往早于 event_loop 的销毁，但也可能因为插件机制导致清理顺序异常。通过在 event_loop 的 finally 块中硬编码清理逻辑，我们建立了一个显式的保护屏障 ，确保顺序永远是：Dispose -> GC -> Final Tasks -> Loop Close。

B. 两次 `gc.collect()` 的必要性

Python GC 的分代机制决定了单次回收可能无法处理跨代的循环引用。两次调用能确保那些由数据库连接池引用的、位于更高代内存中的对象被彻底标记并释放，从而触发它们的析构函数。

C. `asyncio.sleep(0)` 的妙用

这行代码看似无意义，实则是异步编程中的"洗手液"。gc.collect() 触发的 __del__ 可能会产生新的微任务（Micro-tasks）到 loop 的就绪队列中。sleep(0) 强制 loop 进行一次调度，把这些最后的"垃圾"处理掉，防止它们在 loop.close() 之后炸裂。

5. 总结

处理异步数据库连接时，我们要敬畏内存。逻辑关闭（Dispose）不代表物理释放（GC）。 通过在测试框架的最底层注入清理逻辑，强制同步 GC 状态，并利用 sleep(0) 消化残余任务，我们可以获得一个干净、无报错的单元测试环境，同时也让系统在生产环境的优雅停机（Graceful Shutdown）变得更加可靠。

如果你在项目中遇到了类似的异步资源泄漏问题，欢迎在评论区分享你的调试经历！

SQLAlchemy + Pytest：如何优雅地关闭异步数据库连接池