Python 中如何实现 weakref.finalize 自定义回调

本文深入剖析了 Python 中 `weakref.finalize` 的正确使用方法与关键陷阱：它仅适用于支持弱引用的对象（排除 int/str/tuple 等内置不可变类型及未声明 `__weakref__` 的 `__slots__` 类），必须在目标对象存活时及时注册并妥善持有返回的 `finalize` 实例；回调函数绝不能强引用被监控对象，否则将阻断垃圾回收、导致回调延迟甚至失效；更重要的是，`finalize` 本质是“尽力而为”的非可靠机制——不保证执行时机、不保证一定执行，也不适用于关键资源清理，开发者应优先采用显式关闭、上下文管理器或 `atexit` 兜底，而非将其当作 C++ 式析构函数依赖。

对象必须是可弱引用的（即不能是内置不可变类型）

Python 中只有部分对象支持 weakref，核心条件是：该对象所属的类不能禁用弱引用机制。默认情况下，自定义类都支持；但像 int、str、tuple 这些内置不可变类型，或显式设置了 __slots__ 却没包含 __weakref__ 的类，则无法被 weakref.finalize 跟踪。

常见错误现象：TypeError: cannot create weak reference to 'MyClass' object —— 说明类实例不支持弱引用。

• 确保类未定义 __slots__，或已显式加入 __weakref__：例如 __slots__ = ['x', '__weakref__']
• 避免继承禁用弱引用的父类（如某些 C 扩展类）
• 不要对临时对象（如函数返回的字面量、dict() 直接调用结果）尝试绑定 finalize，它们可能立即被回收

finalize 必须在对象还存活时创建

weakref.finalize 是基于弱引用实现的，它不会阻止对象被回收，但前提是创建时目标对象还“活着”。一旦对象已被垃圾回收器清理，再传入它的引用会直接失败或静默失效。

典型误用场景：在 __del__ 方法里调用 finalize，此时对象已处于析构中，弱引用无法建立。

• 应在对象构造完成、且确定生命周期长于 finalize 回调逻辑时立即注册，例如在 __init__ 末尾
• 避免把 finalize 创建延迟到某个条件分支后，尤其当该分支可能不执行时
• 注册后建议保留返回的 finalize 对象（如赋给实例属性），否则它可能被 GC 提前回收，导致回调永不触发

回调函数不能强引用原对象，否则形成循环引用

如果回调函数（例如闭包或方法）内部直接引用了被监控的对象，就可能让该对象无法被及时回收——因为 finalize 内部持有一个弱引用，而你的回调又通过闭包持有了强引用，导致引用计数不降为 0。

表现是：对象“应该”被回收时没触发回调，甚至整个程序退出前才触发（依赖 atexit 机制）。

• 回调应设计为纯函数，或只通过参数接收对象（finalize(obj, callback, obj) 形式），而非捕获实例
• 若需访问实例状态，改用 functools.partial 显式传参，而不是 lambda: self.cleanup()
• 调试时可用 sys.getrefcount(obj) 粗略观察是否意外多出引用

finalize 回调不保证执行时机，也不保证一定执行

weakref.finalize 的本质是注册一个“尽可能在对象销毁前运行”的钩子，但它受制于 Python 的 GC 策略、解释器退出顺序、以及是否启用了循环垃圾回收器。在 CPython 中，它通常能工作；但在 PyPy 或嵌入式环境里可能被跳过。

常见误解：把它当作 C++ 的析构函数来依赖。实际中，它更接近“尽力而为”的资源提示机制。

• 不要在 finalize 中做关键数据持久化（如写磁盘、发网络请求），这些操作应由显式 .close() 或上下文管理器负责
• 若需可靠清理，搭配 atexit.register 作为兜底，但注意两者都可能收不到“对象仍完整”的保证
• 测试时别只靠 print 验证回调是否执行——加日志文件或 time.sleep 观察进程退出行为，更容易暴露延迟/丢失问题

最常被忽略的一点是：finalize 的生命周期独立于它所监控的对象，但依赖于 Python 解释器的运行状态。一旦主线程结束、或 os._exit() 被调用，所有 finalize 都会失效——这比 __del__ 更不保险。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Python 中如何实现 weakref.finalize 自定义回调》文章吧，也可关注golang学习网公众号了解相关技术文章。