Python单例装饰器实现持久化：支持Pydantic与自动恢复实例

脚本专家

在开发中，单例模式常用于管理全局状态（如配置管理器、缓存服务）。但普通单例在程序重启后会丢失状态。本文介绍一个支持持久化的单例装饰器，可自动将实例保存到JSON文件，下次启动时恢复，且兼容Pydantic等禁止动态添加属性的库。

核心代码实现

以下是完整实现，包含三种调用方式和Pydantic兼容处理：

2. import os
3. import types
4. from functools import wraps
5. from typing import TypeVar
6. import jsonpickle
7. from pydantic import BaseModel
9. T = TypeVar('T')
11. def single(cls_or_filename: T | str = None, *, filename: str = None) -> T:
12.     """单例装饰器，支持持久化。
13.    
14.     用法:
15.         @single                # 默认文件名 类名.json
16.         @single()
17.         @single('file.json')
18.         @single(filename='file.json')
19.     """
20.     if isinstance(cls_or_filename, type):
21.         # @single 直接装饰类
22.         fname = cls_or_filename.__qualname__ + '.json'
23.         return _decorate(cls_or_filename, fname)
24.     else:
25.         fname = cls_or_filename if cls_or_filename is not None else filename
26.         def decorator(cls: T):
27.             return _decorate(cls, fname)
28.         return decorator
30. def _decorate(cls: T, fname: str) -> T:
31.     _instance: T = None
32.     # 用于jsonpickle解码时的类映射
33.     class_fullname = cls.__module__ + '.' + cls.__qualname__
34.     class_mapping = {class_fullname: cls}
36.     @wraps(cls)
37.     def wrapper(*args, **kwargs) -> T:
38.         nonlocal _instance
39.         if _instance is None:
40.             if fname is not None and os.path.exists(fname):
41.                 with open(fname, 'r', encoding='utf-8') as f:
42.                     _instance = jsonpickle.decode(f.read(), classes=class_mapping)
43.             else:
44.                 _instance = cls(*args, **kwargs)
45.             # 动态添加 save 方法
46.             if not hasattr(_instance, 'save'):
47.                 def save(self, filename: str = None):
48.                     save_path = filename or fname
49.                     if save_path is None:
50.                         raise ValueError(
51.                             "No filename specified. Either provide a filename to save() "
52.                             "or use the decorator with a filename."
53.                         )
54.                     with open(save_path, 'w', encoding='utf-8') as f:
55.                         f.write(jsonpickle.encode(self))
56.                 # 绕过Pydantic限制
57.                 object.__setattr__(_instance, 'save', types.MethodType(save, _instance))
58.         return _instance
59.     return wrapper

复制代码

三个关键实现细节

一、支持三种装饰语法

- @single                  # 无参数，默认文件名为 类名.json
- @single()               # 同上
- @single('b.json')       # 指定持久化文件
- @single(filename='b.json')

实现原理：检查第一个参数类型。如果是类（type），表示直接装饰；否则返回一个decorator函数等待接收类。注意当有文件名参数时，必须返回decorator，此时cls尚未传入。

二、jsonpickle 需要 class_mapping

编码时jsonpickle会保存类的全限定名（如 __main__.MyClass）。解码时必须通过classes参数告诉它全限定名对应的类，否则无法反序列化。代码中：

2. class_mapping = {class_fullname: cls}
3. _instance = jsonpickle.decode(f.read(), classes=class_mapping)

复制代码

这样解码就能正确重建实例。

三、object.__setattr__ 绕过 Pydantic 限制

Pydantic的BaseModel在__setattr__中进行了验证，会拒绝动态添加的属性（如save方法）。直接赋值 _instance.save = ... 会触发ValidationError。使用object.__setattr__绕过Pydantic的验证，直接写入实例的__dict__，使之正常工作。该技巧也适用于其他禁止动态属性的库。

使用示例

基本用法（无参数）

2. @single
3. class A:
4.     def __init__(self, x: int = 0):
5.         self.x = x
7. a = A(5)
8. print(type(a))          # <class '__main__.A'>
9. print(a.x)              # 5
10. a.save()                # 保存到 A.json

复制代码

指定持久化文件

2. @single('b.json')
3. class B:
4.     def __init__(self, y: str = ''):
5.         self.y = y
7. b = B('hello')
8. b.save()                # 保存到 b.json

复制代码

配合 Pydantic 使用

2. @single
3. class Task(BaseModel):
4.     id: str = 'id'
5.     label: str = 'label'
6.     children: list['Task'] = []
8. t = Task()
9. print(t.id)             # id
10. print(t.label)          # label
11. t.save()                # 正常保存，Pydantic不会拦截

复制代码

总结与适用场景

该装饰器自动为类添加save()方法，支持三种调用语法。通过jsonpickle实现序列化，利用class_mapping保证解码正确。object.__setattr__技巧让装饰器兼容Pydantic等框架。适用于配置管理器（启动恢复，修改后持久化）、缓存服务（重启不丢失）、轻量级状态管理（无需数据库）等场景。

热心网友3

这个实现很实用，尤其是对 Pydantic 的兼容处理很巧妙。我之前也遇到过用 pickle 或 jsonpickle 恢复实例时动态添加方法被 Pydantic 拦截的问题，用 `object.__setattr__` 绕过是个好思路。 有个小疑问：`jsonpickle` 序列化时会不会把 `save` 方法也存进去？如果实例里有自定义方法或有状态的闭包，反序列化后这些方法还在吗？另外在分布式或高并发场景下，会不会有文件锁或线程安全的问题？不过对于单进程单线程的配置管理类来说，这套方案已经很完整了，感谢分享。