Python 数据模型演进的版本控制策略

python数据模型版本冲突时，__eq__和__hash__必须同步更新，否则实例无法放入set或作dict键；字段变更需用__setstate__修复pickle反序列化；可变默认值须用default_factory；测试需覆盖不同pickle协议版本。

Python 数据模型版本冲突时，__eq__ 和 __hash__ 必须同步更新

Python 的数据模型（如 __eq__、__hash__、__repr__）一旦在类中定义，就构成该类实例的行为契约。版本迭代中若只改 __eq__ 判断逻辑（比如新增字段参与比较），却忘了重写 __hash__，会导致实例无法放入 set 或用作 dict 键——报错 TypeError: unhashable type。

常见错误现象：MyData(a=1, b=2) 在 v1 版本可放进 set，v2 加了字段 c 后，相同代码抛异常；或 dict 查不到已存在的 key，但 in 判断却返回 True。

• 只要类定义了 __eq__，且你希望实例仍可哈希，就必须显式定义 __hash__（哪怕只是 return hash((self.a, self.b, self.c))）
• 如果字段含不可哈希类型（如 list、dict），别硬套 hash()，要么改用 frozenset/tuple 包装，要么直接设 __hash__ = None（明确放弃哈希能力）
• 使用 dataclass 时注意：默认 @dataclass(eq=True, unsafe_hash=False)，要开哈希必须显式写 unsafe_hash=True，且所有字段必须可哈希

用 __setstate__ 修复 pickle 反序列化失败

当数据模型字段增减后，旧 pickle 文件加载会因 __dict__ 结构不匹配而崩溃，典型错误是 AttributeError: 'MyData' Object has no attribute 'new_field' 或 KeyError。

这不是版本号问题，而是 Python 默认反序列化机制直接把字节流映射到 __dict__，没留兼容入口。

立即学习“Python免费学习笔记（深入）”；

• 在类中定义 __setstate__(self, state)，手动接管反序列化过程
• 检查 state 字典是否含新字段，缺失则补默认值；多余字段可忽略或 warn
• 示例：

  def __setstate__(self, state):     state.setdefault('new_field', 'default_value')     self.__dict__.update(state)

• 别依赖 __getstate__ 做“向前兼容”——它只控制序列化输出，不影响旧数据加载

字段变更时，dataclass 的 default_factory 比 default 更安全

给数据类字段加默认值看似简单，但用 default=[] 这类可变对象字面量，会在所有实例间共享引用，版本升级后可能引发隐蔽的数据污染。

更危险的是：v1 版本用 default=None + 属性访问时惰性初始化，v2 改成 default=[]，老代码读取旧 pickle 时，None 被强制转为空列表，语义已变。

• 所有可变默认值必须用 default_factory=list（而非 default=[]）
• 新增字段若需兼容旧数据，优先用 default_factory 返回带逻辑的函数，比如 Lambda: [] if legacy_mode else deque()
• 字段类型变更（如 str → Path）时，default_factory 可封装转换逻辑，避免调用方感知

测试里必须覆盖 __reduce_ex__ 行为差异

Python 3.8+ 对某些内置类型（如 datetime）和自定义类的 pickle 协议做了优化，__reduce_ex__ 返回结果可能因协议版本不同而变化。线上环境用 protocol=4 保存，测试却用 protocol=5 加载，可能触发意外的 __new__ 调用或绕过 __init__。

表现是：单元测试全绿，但生产反序列化后对象状态异常（如字段为 None、__post_init__ 未执行）。

• 测试时显式指定协议版本：pickle.loads(pickle.dumps(obj, protocol=4), encoding='bytes')
• 若自定义 __reduce_ex__，确保各协议版本返回一致的构造逻辑；否则干脆删掉，让 Python 用默认逻辑
• CI 中至少跑两组 pickle 测试：一组用最低支持协议（如 4），一组用当前解释器默认协议

数据模型的版本控制不是加个 __version__ 字段就能糊弄过去的事——字段语义、序列化路径、哈希契约、构造时机，任何一处松动都会在下游某个深夜突然报错。最常被跳过的其实是 __setstate__ 和协议版本对齐，而不是文档或注释。