cattrs：Python 对象序列化与验证工具

cattrs：Python 对象序列化与验证工具

cattrs 是一个专注 Python 数据结构转换的库，目前有 1,035 个 Star。它的作用很直接：把字典这类非结构化数据转成类型化的 Python 类实例，同时支持反向转换。

后端开发的人应该都遇到过这个场景：API 返回的 JSON 数据是一大堆嵌套字典，手动解析和类型检查写起来又臭又长。cattrs 配合 attrs 或者标准库的 dataclasses，能把这段繁琐代码压缩到几行。

核心能力：双向转换

cattrs 提供两个主要操作：structure 和 unstructure。

structure 负责把字典转成对象。你给 cattrs 一个目标类型，它会递归解析字典里的每个字段，按照类型注解完成映射。支持的类型不少，包括 Optional、list、tuple、set、dict、TypedDict、attrs 类、dataclass，甚至还有 Union 类型。

unstructure 则做反向工作，把对象转回字典。attrs 类和 dataclass 会变成字典，枚举值转成对应的基础类型，其他基础类型原样保留。

这两个操作的设计是分离的。转换规则不绑定在数据模型上，这意味着一个模型可以对应多套转换逻辑，也能给第三方库的类写转换规则。

代码写起来什么样

实际用起来很直接：

from attrs import define
from cattrs import structure, unstructure

@define
class C:
    a: int
    b: list[str]

instance = structure({'a': 1, 'b': ['x', 'y']}, C)
# C(a=1, b=['x', 'y'])

unstructure(instance)
# {'a': 1, 'b': ['x', 'y']}

嵌套结构也自动处理，不需要手动递归。类型不匹配时会抛异常，算是附带了一层基础验证。

配套生态完善

cattrs 内置了多个序列化库的预配置转换器，包括标准库 json、orjson、msgpack、cbor2、bson、PyYAML、tomlkit、msgspec。这些转换器已经处理好类型映射和边缘情况，可以直接接入项目。

设计上的取舍

这个库有几个明确的设计原则。

规则与模型分离。转换逻辑不写在类定义里，而是通过注册 hook 的方式外部配置。这样做的好处是模型保持干净，同一个类可以在不同场景下用不同的规则转换。

尽量复用 Python 原生机制。比如异常处理就直接用标准库的 ExceptionGroup，不发明新的异常类型。学 cattrs 的过程，很多时候其实是在学 Python 的类型系统。

拒绝猜测。遇到歧义时，cattrs 不会自作主张选一个方案，而是交给用户配置。

适合谁用

如果你在用 attrs 做数据建模，或者需要把外部 API 的 JSON 响应转成类型安全的 Python 对象，cattrs 能省掉大量样板代码。它和 Pydantic 的定位不同，Pydantic 更偏向运行时验证和配置管理，cattrs 则专注在结构转换这件事上，更轻量，侵入性更低。

对于数据 pipeline、配置文件解析、API 响应处理这些场景，cattrs 是个务实的选择。