Python项目如何向后兼容迁移到现代attrs/cattrs编码风格

我自2020年初起基于attrs v19.3.0版本开发了多个Python项目，使用cattrs实现序列化/反序列化功能。请问将这些项目中的类从旧有@attr.s/attr.ib写法，迁移至采用@define、@frozen装饰器的现代风格时，正确且完全向后兼容的迁移方式是什么？

我此前默认新旧风格的类可以混合搭配使用，且新的注解写法总能实现等价功能，因此采用逐类转换的策略，每次转换单个类后检查单元测试失败情况、MyPy告警等问题。
当我推进到代码中最复杂的对象层级（该层级同样使用cattrs做序列化/反序列化）时，无法找到向后兼容的解决方案：只要转换该模块内的任意一个类，测试套件就会立刻抛出cattr相关错误导致运行失败。

我最初贴出了部分业务实际代码，但内容过于繁杂不具备参考性，目前已将问题收敛为一个小型测试用例。
如下是采用@attr.s与attr.ib的旧风格类实现，该代码可正常通过测试用例：

from __future__ import annotations

from typing import Dict
import attr
import cattrs

converter = cattrs.Converter()

@attr.s
class Game:
    players = attr.ib(type=Dict[str, str])
    def copy(self) -> Game:
        return converter.structure(converter.unstructure(self), Game)

class TestGame:
    def test_copy(self):
        game = Game(players={"key" : "value"})
        copy = game.copy()
        assert copy == game and copy is not game

如下是对应新风格类的等价测试用例实现：

from __future__ import annotations

from typing import Dict
import attrs
import cattrs

converter = cattrs.Converter()

@attrs.define
class Game:
    players: Dict[str, str]
    def copy(self) -> Game:
        return converter.structure(converter.unstructure(self), Game)

class TestGame:
    def test_copy(self):
        game = Game(players={"key" : "value"})
        copy = game.copy()
        assert copy == game and copy is not game

运行新风格代码时抛出如下错误：

test_sample.py:15 (TestGame.test_copy)
self = <tests.test_sample.TestGame object at 0x108ab2490>

    def test_copy(self):
        game = Game(players={"key" : "value"})
>       copy = game.copy()

test_sample.py:18: 
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
test_sample.py:13: in copy
    return converter.structure(converter.unstructure(self), Game)
../.venv/lib/python3.9/site-packages/cattrs/converters.py:281: in structure
    return self._structure_func.dispatch(cl)(obj, cl)
../.venv/lib/python3.9/site-packages/cattrs/converters.py:446: in structure_attrs_fromdict
    conv_obj[name] = self._structure_attribute(a, val)
../.venv/lib/python3.9/site-packages/cattrs/converters.py:422: in _structure_attribute
    return self._structure_func.dispatch(type_)(value, type_)
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 

self = <cattrs.converters.Converter object at 0x108a9d6d0>, _ = {'key': 'value'}
cl = 'Dict[str, str]'

    def _structure_error(self, _, cl):
        """At the bottom of the condition stack, we explode if we can't handle it."""
        msg = "Unsupported type: {0!r}. Register a structure hook for " "it.".format(cl)
>       raise StructureHandlerNotFoundError(msg, type_=cl)
E       cattrs.errors.StructureHandlerNotFoundError: Unsupported type: 'Dict[str, str]'. Register a structure hook for it.

../.venv/lib/python3.9/site-packages/cattrs/converters.py:344: StructureHandlerNotFoundError

经初步排查，报错原因似乎是cattrs无法识别新风格类中players字段为映射类型字段。

你遇到的报错和@define本身的功能无关，核心原因有两个：一是你用了from __future__ import annotations把所有类型注解转成了字符串形式，二是当前使用的cattrs版本默认不会自动解析新风格attrs类上的字符串类型注解——旧@attr.s写法里你显式给attr.ib(type=...)传入了真实的类型对象，所以不会触发这个问题。

完全向后兼容的迁移步骤 #

• 先对齐依赖版本，从根源解决类型识别问题
  把attrs升级到21.3.0及以上版本（这是@define装饰器首次稳定发布的版本），把cattrs升级到22.1.0及以上版本，该版本开始原生支持PEP 563延迟注解解析，不需要额外配置就能正常识别Dict[str, str]这类字段类型，你贴的最小复现用例升级后直接就能跑通。
• 逐类迁移时显式对齐旧@attr.s的默认行为，避免隐式逻辑变更
  @define的默认参数和旧@attr.s有几处差异，迁移时不要直接裸用@define，加上参数对齐旧行为，保证逻辑完全一致：

  # 旧写法
  @attr.s
  # 行为100%对齐的新写法
  @attrs.define(
      auto_attribs=True,
      slots=False, # 旧@attr.s默认不生成slots，直接开True会导致旧代码动态绑定属性时报错
      frozen=False,
      eq=True,
      order=False,
      hash=None,
      repr=True,
      collect_by_mro=True # 旧版attr默认按MRO收集字段，避免多继承场景字段顺序错乱
  )
  

  原来用@attr.s(frozen=True)的类，直接替换为参数对齐的@attrs.frozen(...)即可。
• 受环境限制无法升级cattrs的话，手动给converter加注解解析支持
  如果没法升级依赖，初始化Converter后添加全局配置，手动开启字符串注解的解析能力：

  from cattrs.gen import make_dict_structure_fn, make_dict_unstructure_fn
  
  converter = cattrs.Converter()
  # 全局适配新旧风格的attrs类，自动解析延迟注解
  converter.register_structure_hook_factory(
      attrs.has,
      lambda cls: make_dict_structure_fn(cls, converter)
  )
  converter.register_unstructure_hook_factory(
      attrs.has,
      lambda cls: make_dict_unstructure_fn(cls, converter)
  )
  

  加完配置后不需要修改类定义，新旧风格的类都能正常完成序列化/反序列化。
• 逐类校验，避免漏改
  每转换完一个类就跑对应的单元测试，重点核对几个点：实例化参数校验逻辑、cattrs序列化反序列化结果、相等性判断/哈希逻辑（如果用到）、动态属性绑定是否正常，确认没问题再转换下一个类。

迁移注意事项 #

• 迁移全程可以混合使用新旧风格的类，适配后的cattrs能同时处理两种写法，不需要一次性全量替换完才能运行。
• 迁移阶段不要开启@define默认的slots=True，等所有类转换完成、全量测试跑通之后，再按需开启slots做性能优化。
• 原来attr.ib上用的validator、converter、default等参数，直接平移到attrs.field()里即可，API完全兼容，不需要修改业务逻辑。

内容的提问来源于stack exchange，提问作者Ken Pronovici