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

本文介绍如何使用 Pydantic 的 @field_validator(mode="before") 在嵌套模型（如 Dict[str, BaseModel]）验证前，自动将字典键赋值给子模型的指定字段（如 type），避免手动预处理数据，实现声明式、可复用的数据增强逻辑。

本文介绍如何使用 pydantic 的 `@field_validator(mode="before")` 在嵌套模型（如 `dict[str, basemodel]`）验证前，自动将字典键赋值给子模型的指定字段（如 `type`），避免手动预处理数据，实现声明式、可复用的数据增强逻辑。

在 Pydantic 中，当嵌套结构依赖外部上下文（例如字典的 key 需映射为子模型的某个必填字段）时，标准验证流程会在子模型实例化前就失败——因为 UserType.type 缺失且无默认值。此时，不能依赖 model_post_init（它发生在所有字段已验证并实例化之后），而应选择 验证前钩子（pre-validation hook）。

最简洁、符合 Pydantic v2 设计哲学的方案是：对目标字段（如 objects）应用 @field_validator(..., mode="before")。该装饰器接收原始输入数据（未解析的 dict 或 None），允许你原地修改或重构数据结构，再交由后续验证流程处理。

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

from typing import Dictfrom pydantic import BaseModel, Field, field_validator, ValidationErrorclass 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)  # 推荐使用 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 仍是原始 dict，可安全修改；
• 使用 model_validate() 而非 AppConfig(**data)：前者明确触发完整验证生命周期（含 @field_validator(mode="before")），后者在 v2 中不保证调用所有验证器；
• 钩子必须为 @classmethod，且参数名需为 cls + 字段值（此处为 objects_dict），返回值将作为该字段的新输入；
• 注意类型检查：inject_type_from_key 中增加了 isinstance(objects_dict, dict) 和 isinstance(obj_data, dict) 防御性判断，避免对非字典输入（如 None、列表）报错。

⚠️ 注意事项：

• 此方法不适用于 Field(default_factory=...) 或 default= 场景，因其本质是数据预处理而非默认值填充；
• 若 objects 中某 obj_data 是已实例化的 UserType（而非字典），obj_data["type"] = ... 会失败——因此建议始终在数据源层保持纯字典结构；
• 多层嵌套时，可链式使用多个 @field_validator(mode="before")，但需注意执行顺序（按字段声明顺序）。

通过该模式，你可在模型定义中集中管理上下文敏感的数据转换逻辑，提升代码可读性、可测试性与可维护性，真正实现“验证即转换”的声明式开发体验。