Pydantic 教程：在嵌套模型验证前动态注入字典键作为字段值

在 Pydantic 中处理嵌套模型时，有一个场景经常让人头疼：子模型的某个字段值，其实取决于它在父级字典中的键（key）。比如说，你有一个 Dict[str, UserType] 这样的结构，而每个 UserType 内部又需要一个 type 字段来标识自己属于哪个 key。按照常规写法，你得在构建数据的时候手动把 key 塞进去，或者在模型实例化之后另行处理。但这两种方式都不够优雅——前者增加了数据源侧的负担，后者则破坏了模型的封闭性。

那怎么解决？最优雅的方式，是利用 Pydantic v2 的 @field_validator(mode="before")。这个钩子可以在子模型验证之前、字段值还是原始字典形态的时候，就将 key 注入进去。整个过程透明、声明式，并且可以复用。

来看一个完整可运行的示例：

from typing import Dict
from pydantic import BaseModel, Field, field_validator, ValidationError

class UserType(BaseModel):
    name: str = Field(min_length=1)
    type: str = Field(min_length=1)  # 现在可由父级自动注入

class AppConfig(BaseModel):
    key1: int = Field(gt=0)
    objects: Dict[str, UserType]

    @field_validator("objects", mode="before")
    @classmethod
    def inject_type_from_key(cls, objects_dict):
        if not isinstance(objects_dict, dict):
            return objects_dict
        # 遍历每个 {key: value}，将 key 注入 value 字典的 "type" 字段
        for obj_key, obj_data in objects_dict.items():
            if isinstance(obj_data, dict):
                obj_data["type"] = obj_key  # ✅ 动态注入
        return objects_dict

# 测试数据：无需显式提供 "type"
data = {
    "key1": 1,
    "objects": {
        "type1": {"name": "Name 2"},
        "type2": {"name": "Name 1"}
    }
}

try:
    config = AppConfig.model_validate(data)
    print(config.model_dump_json(indent=2))
except ValidationError as e:
    print(e)

输出结果：

{
  "key1": 1,
  "objects": {
    "type1": {
      "name": "Name 2",
      "type": "type1"
    },
    "type2": {
      "name": "Name 1",
      "type": "type2"
    }
  }
}

这里有几个关键点需要特别留意：

• mode="before" 是整段逻辑的基石。它确保验证器在类型转换和子模型真正的验证逻辑之前触发，此时 obj_data 还是一个朴素的 Python 字典，你可以随意修改而不用担心中间件报错。
• 使用 model_validate() 而不是 AppConfig(**data)。前者会完整触发验证生命周期，包括你定义的这个 before 钩子；后者在 v2 中并不保证这一点，踩坑的概率不小。
• 验证器必须是 @classmethod，参数约定是 cls 加上字段的值（这里叫 objects_dict）。它的返回值会成为该字段新的原始输入。
• 防御性编程很重要：代码中增加了 isinstance 判断，避免对 None 或列表等非字典输入抛出难懂的异常。

最后，补充几点需要注意的地方：

• 这个方案不是用来做默认值填充的，它本质上是数据预处理。所以它不适用于 Field(default_factory=...) 或 default= 的场景。
• 如果字典的值已经是实例化后的 UserType 对象，再试图用它做字典赋值就会报错。建议数据源始终提供纯字典结构，在模型层统一完成实例化。
• 如果嵌套层级更深，可以链式使用多个 @field_validator(mode="before")，但要注意执行顺序——按字段声明的先后顺序来。

通过这种方式，你可以把那些“上下文敏感”的数据转换逻辑收拢到模型定义中，让代码更干净、更好测试，也更容易维护。这才是“验证即转换”该有的样子。