Python 结构化数据工具详解：dataclass、Pydantic 与 TypedDict

三、底层原理拆解

3.1 dataclass：基于元编程

• @dataclass 解析 __annotations__，动态生成方法：__init__、__repr__、__eq__。
• 类仍为普通 Python 类，支持继承与扩展，性能与原生类一致。

示意：

@dataclass
class User:
    id: int
    name: str
# 自动生成
# def __init__(self, id: int, name: str): ...
# def __repr__(self): ...

3.2 TypedDict：静态类型约束

• Python 解释器不创建新类型，运行时实例仍是普通字典。
• 类型检查工具（mypy、Pyright）解析 TypedDict 提供静态提示。

class UserDict(TypedDict):
    id: int
    name: str

user: UserDict = {"id": "wrong type"} # 运行时不报错

3.3 Pydantic Model：描述器 + 运行时校验

• 字段解析为描述器对象，存储类型、校验逻辑。
• 实例化时执行类型校验、数据转换、自定义校验器。
• V2 使用 Rust 核心，大幅提升性能。

流程示意：

输入数据 --> 字段描述器校验/转换 --> 自定义校验器 --> 验证通过生成实例 

四、实战选型与代码示例

4.1 内部数据载体（dataclass）

from dataclasses import dataclass, asdict
from typing import List

@dataclass(frozen=True)
class User:
    id: int
    name: str
    age: int
    tags: List[str] = None

user = User(id=1, name="张三", age=25, tags=["python"])
print(asdict(user))

4.2 动态字典（TypedDict）

from typing import TypedDict, List, Optional

class UserDict(TypedDict, total=False):
    id: int
    name: str
    age: Optional[int]
    tags: List[str]

user: UserDict = {"id": 1, "name": "张三", "tags": ["python"]}

4.3 API 接口/配置解析（Pydantic Model）

from pydantic import BaseModel, field_validator, ValidationError
from typing import List, Optional

class UserModel(BaseModel):
    id: int
    name: str
    age: Optional[int] = None
    tags: List[str] = []

    @field_validator("age")
    def age_must_be_positive(cls, v):
        if v is not None and v < 0:
            raise ValueError("年龄必须为正数")
        return v

user = UserModel(id="1", name="张三", age=25)
print(user.model_dump_json())

4.4 决策树：快速选型

需要运行时校验/转换？
├─ 是 → Pydantic Model
└─ 否 → 数据形态？
    ├─ 固定结构类 → dataclass (+slots/frozen)
    └─ 动态字典 → TypedDict 

五、进阶实践与优化

5.1 dataclass

@dataclass(frozen=True, slots=True, kw_only=True)
class OptimizedUser:
    id: int
    name: str
    age: int

• frozen=True：不可变实例
• slots=True：减少内存占用
• kw_only=True：强制关键字参数

5.2 TypedDict

from typing import TypedDict, NotRequired, List

class AddressDict(TypedDict):
    city: str
    street: str

class UserWithAddress(TypedDict):
    id: int
    name: NotRequired[str]
    address: AddressDict
    tags: List[str]

• NotRequired控制可选字段（Python 3.12+）
• 支持嵌套结构

5.3 Pydantic

from pydantic import BaseModel, ConfigDict
from pydantic.types import EmailStr

class CustomUser(BaseModel):
    model_config = ConfigDict(
        extra="forbid",
        str_strip_whitespace=True,
        validate_assignment=True
    )
    id: int
    email: EmailStr
    name: str

user = CustomUser(id=1, email="[email protected]", name=" 张三 ")
print(user.name) # 自动去空格

• 可生成 JSON Schema
• 支持嵌套、继承和动态模型

六、常见误区与避坑

1. dataclass 类型注解不是校验
2. TypedDict 运行时不限制类型
3. Pydantic 高频实例化需注意性能（V2 优化、缓存模型）

七、总结：核心选型逻辑

核心选型原则：

1. 是否需要运行时校验/转换？ → 是 → Pydantic
2. 数据形态为固定类 → dataclass，动态字典 → TypedDict
3. 内部高频传递 → dataclass + slots
4. 对外接口、核心数据流程 → Pydantic
5. 仅需静态类型提示 → TypedDict + mypy