模块级变量替代单例更简单可靠，因Python模块导入机制天然保证全局唯一、线程安全且无需手动加锁；避免了__new__或装饰器实现中易出现的竞态、继承冲突与GC泄漏风险。
为什么直接用模块级变量替代单例更简单可靠
Python 的模块加载机制天然保证一个模块只被导入一次，import 后的模块对象就是全局唯一的。相比手写 __new__ 或装饰器实现的单例，模块级连接池更易读、更少出错、且无需考虑多线程下的双重检查锁问题。
常见错误是强行套用 Java 风格单例，在 Python 中反而引入竞态风险或绕过 GC 导致连接泄漏。
- 把连接池初始化逻辑全写在
db_pool.py模块顶层，首次import db_pool时完成创建 - 使用
threading.local()或contextvars.ContextVar管理每个请求的连接（非池本身），避免跨协程混用 - 不要在
__del__或atexit中关闭池——进程退出前可能已丢失引用，应显式调用close()
SQLAlchemy 中正确复用 create_engine 和 Pool
create_engine 默认启用连接池，且返回的引擎实例本身是线程安全的，可全局复用。重复调用 create_engine 创建多个引擎，等于建了多个独立池，不仅浪费资源，还可能突破数据库最大连接数限制。
典型误用：get_db_engine() 函数每次返回新引擎；正确做法是模块内只调用一次，并导出该实例。
立即学习“Python免费学习笔记（深入）”；
- 设置
pool_pre_ping=True，避免从池中取出失效连接（如数据库重启后） - 显式配置
pool_size和max_overflow，防止突发流量打爆 DB（例如pool_size=5, max_overflow=10） - 若用异步驱动（如
asyncpg+SQLAlchemy 2.0+），必须用create_async_engine，且不能与同步引擎混用
Flask/FastAPI 中如何安全注入连接池实例
框架生命周期管理与连接池释放容易脱节：Flask 的 app.teardown_appcontext 只在请求上下文结束时触发，但连接池应伴随应用整个生命周期；FastAPI 的 lifespan 更合适，但需确保异常时不跳过关闭。
错误做法：在路由函数里每次 engine.connect() 后手动 close()——这实际放弃池化，退化成短连接。
- Flask：在
create_app()内初始化引擎，挂到app.extensions['db']，关机时监听flask.signals.appcontext_tearing_down不够，应改用atexit.register(engine.dispose)或信号监听SIGTERM - FastAPI：在
lifespan异步生成器中yield前初始化，finally块中调用await engine.dispose() - 测试环境务必用
StaticPool替换默认池（connect_args={"check_same_thread": False}仅 SQLite 有效）
连接泄漏的三个隐蔽信号和排查方式
连接没被归还给池，比完全连不上更难定位。表现常为“偶发超时”或“DB 连接数缓慢上涨”，而非立刻报错。
关键线索藏在日志和指标里：SQLAlchemy 默认不打连接获取/归还日志，需主动开启。
- 开启池日志：
echo='debug'仅输出 SQL，要看到连接动作得加logging.getLogger('sqlalchemy.pool').setLevel(logging.INFO) - 监控
engine.pool.checked_in(), engine.pool.checked_out(), engine.pool.overflow()实时值（注意这是近似值，非原子计数） - 最硬核办法：在
pool_recycle设为 3600 秒的前提下，观察 DB 侧SHOW PROCESSLIST中 sleep 状态连接是否长期存在且不匹配应用请求数
真正棘手的是 ORM 层面的泄漏：比如忘记 session.close()、在生成器中 yield 了未提交的 session、或用了 scoped_session 但没配对 remove()。这些不会报错，但会持续占用连接。
