Pydantic模型字段扩展方案解析：使用TypedDict规范元数据

在实际开发中，我们经常需要为模型字段添加额外的元数据信息。本文将以一个典型场景为例，探讨如何在Pydantic模型中优雅地实现字段扩展。

需求背景

假设我们需要开发一个前后端交互系统，其中前端页面需要根据模型字段的特定属性来决定如何渲染该字段（例如显示为普通文本还是超链接）。这就要求我们在模型定义时为字段附加额外的配置信息。

常见误区

很多开发者首先想到的是继承FieldInfo类来创建自定义字段类型，例如：

class CustomFieldInfo(FieldInfo):
    c_type: bool = None

class Demo(BaseModel):
    tags: str = CustomFieldInfo(c_type=False)

然而这种方法存在几个严重问题：

1. FieldInfo类的内部实现较为脆弱，其合并逻辑可能无法正确处理自定义属性
2. 静态类型检查器无法识别自定义的字段说明符
3. 破坏了Pydantic与类型系统的集成

推荐解决方案

Pydantic核心开发者建议使用TypedDict来规范json_schema_extra的内容：

from typing import TypedDict

class FieldMetadata(TypedDict):
    display_type: Literal["text", "link"]
    source: list[dict[str, str]]
    features: list[str]

class Demo(BaseModel):
    name: str = Field(
        json_schema_extra={
            "display_type": "link",
            "source": [{"field_name": "test_field1"}],
            "features": ["l1"]
        }
    )

方案优势

1. 类型安全：TypedDict提供了完整的类型提示，IDE可以自动补全
2. 规范统一：明确定义了元数据的结构和类型，避免随意添加字段
3. 兼容性好：完全遵循Pydantic现有机制，不影响模型的其他功能
4. 易于维护：集中管理字段元数据定义，修改时只需调整TypedDict

实际应用

在业务逻辑中获取这些元数据非常简单：

model = Demo()
field_metadata = model.model_fields["name"].json_schema_extra
# 类型提示会显示field_metadata包含display_type等字段

总结

当需要在Pydantic模型中添加字段元数据时，应避免直接扩展FieldInfo类，而是采用TypedDict规范json_schema_extra的内容。这种方法既保持了类型安全，又与Pydantic的设计理念完美契合，是生产环境中推荐的解决方案。