如何将嵌套列表数据反序列化为 Pydantic 模型

本文介绍在 pydantic v2 中，如何将形如 `[[1, “red“], [2, “blue”]]` 的二维列表自动转换为结构化模型（如 `item(id: int, color: str)`），并通过 `@model_validator(mode=”before”)` 实现灵活、健壮的自定义解析。

在实际 API 开发或数据集成场景中，后端返回的 jsON 响应有时并不遵循标准字段命名规范——例如，data 字段可能直接是一个二维列表（如 [[id, color], …]），而非对象数组（如 [{“id”: 1, “color”: “red”}, …]）。此时若直接用 Pydantic 的默认解析机制，会因类型不匹配而报错：Expected list[Item], got list[list]。

解决该问题的核心思路是：在模型实例化前，对原始输入数据进行预处理。Pydantic v2 提供了 @model_validator(mode=”before”) 装饰器，允许我们在字段值被验证和类型转换前，介入并重写其结构。

以下是一个完整、可运行的示例：

from datetime import datetime from pydantic import BaseModel, model_validator  # 原始响应数据（模拟服务器返回） data = {     "date": "2024-02-05 15:34:44",     "status": True,     "data": [         [1, "red"],         [2, "blue"],         [3, "yellow"]     ] }  class Item(BaseModel):     id: int     color: str      @model_validator(mode="before")     @classmethod     def from_list(cls, values):         # 当输入是长度为 2 的列表时，映射为字段字典         if isinstance(values, list) and len(values) == 2:             return {"id": values[0], "color": values[1]}         # 否则保持原样，交由默认验证器处理（支持 dict 输入）         return values  class Model(BaseModel):     date: datetime     status: bool     data: list[Item]  # 反序列化成功！ result = Model(**data) print(result) # 输出：date=datetime.datetime(2024, 2, 5, 15, 34, 44) status=True data=[Item(id=1, color='red'), ...]

✅ 关键要点说明：

• @model_validator(mode=”before”) 在字段值进入类型校验前触发，适用于结构转换；
• isinstance(values, list) and len(values) == 2 是安全判断，避免误处理合法字典输入；
• 支持多源兼容：该 Item 模型既能解析 [1, “red”]，也能解析 {“id”: 1, “color”: “red”}；
• 若列表格式不固定（如含额外字段），可在 from_list 中扩展逻辑（如解包到 *args 或按索引取值）；
• ⚠️ 注意：datetime 字段依赖字符串格式匹配（此处 “yyYY-MM-DD HH:MM:SS” 符合默认解析规则；若格式不同，需配合 @field_validator 或 json_encoders 处理）。

这种方案简洁、可维护性强，无需引入额外依赖或手动遍历转换，是处理非标准 json 结构与 Pydantic 模型对齐的推荐实践。