本文介绍在 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 模型对齐的推荐实践。
