如何在Python中将复杂的类对象保存为Pickle文件？

先说说核心结论：不能直接拿 pickle.dump() 往所有类实例上怼——尤其是那些带着线程锁、文件句柄、Lambda表达式、模块级闭包或者C扩展对象的类。踩过这个坑的人应该不少。

哪些类对象会 pickle 失败？

最常见的报错信息是 AttributeError: Can't pickle local object 或者 TypeError: cannot pickle '_thread.RLock' object。追根溯源，问题出在 pickle 的工作机制上——它只能序列化「可重建」的状态。换句话说，它不关心内存地址或者运行时资源，只在乎三样东西：模块路径、类名、以及 __dict__（或者 __getstate__() 的返回值）。

具体来说，这类情况基本都会翻车：

• 类定义在函数内部或者交互式环境里——没有稳定的模块路径，pickle 找不到回家的路
• 实例身上绑了 lambda、嵌套函数或者局部 functools.partial
• 对象包含 threading.Lock、open() 返回的文件对象、数据库连接这类资源
• 用了 __slots__ 但没定义 __getstate__，同时还存在未声明的动态属性——这种情况下数据可能会悄无声息地丢失

手动控制 pickle 行为：__getstate__ 和 __setstate__

这是最常用也最好把控的方案。思路很简单：让类自己决定哪些字段进 pickle，哪些跳过，反序列化的时候再把那些不能持久化的资源补回来。

import threading
import pickle

class Worker:
    def __init__(self, name, data):
        self.name = name
        self.data = data
        self.lock = threading.RLock()  # 不可 pickle
        self.cache = {}               # 运行时缓存，也不用存

    def __getstate__(self):
        # 返回要保存的字典；剔除不可序列化项
        state = self.__dict__.copy()
        del state['lock']
        del state['cache']
        return state

    def __setstate__(self, state):
        # 恢复基础状态
        self.__dict__.update(state)
        # 重建运行时资源
        self.lock = threading.RLock()
        self.cache = {}

有一点需要留意：__setstate__ 必须能在模块顶层被访问到——也就是说类本身得在 sys.modules 里有明确的路径，否则反序列化的时候 Python 根本找不到这个类定义。

用 copyreg.pickle() 注册自定义序列化函数

这个方法特别适合那些你没法修改源码的场景，比如第三方类库。做法是提供一个可调用对象，让它返回一个 (callable, args) 元组，用来重建对象。

有几个硬性要求：

• callable 必须是模块级函数，lambda 或者闭包不行
• args 里的每个元素都得可 pickle（像字符串、数字、普通字典/列表这类）
• 注册之后，所有该类型的实例都会走这个自定义逻辑

import copyreg
import threading

def pickle_worker(obj):
    # 只保留核心数据，丢弃 lock
    return Worker, (obj.name, obj.data)

# 假设 Worker 类已定义且无法修改
copyreg.pickle(Worker, pickle_worker)

这种方式绕过了 __getstate__，但代价是你要完全掌控重建逻辑。如果 Worker.__init__ 的参数签名后来变了，这边没同步更新的话，很容易出问题。

保存前务必检查对象图的可达性

有时候一个表面简单的实例，背后可能隐式引用了不可 pickle 的全局对象——比如日志器、Flask app 实例、或者 matplotlib.pyplot。最直接的办法就是拿 pickle.dumps(obj) 试一把：

try:
    pickle.dumps(my_obj)
except Exception as e:
    print(f"Pickling failed: {e}")
    # 翻翻 traceback 或者手动 inspect obj.__dict__，看是哪一层出的问题

有几个容易被忽略的坑：类本身用了 __new__ 或者元类，但返回了非标准实例；或者实例绑定了用 types.MethodType 动态添加的方法——这些都可能让 pickle 链断裂。