TypedDict 和 Pydantic 都是 Python 生态中用于处理数据结构、提升代码健壮性的重要工具，但它们的底层机制和适用场景有显著区别。

1. TypedDict：字典结构的静态类型提示

TypedDict 是 Python typing 模块提供的一个工具，主要用于为字典（dict）提供精确的结构化类型提示。

• 核心特点：它仅存在于静态类型检查阶段。它告诉类型检查器（如 mypy、pyright）或 IDE 一个字典具体包含哪些键，以及每个键对应的值是什么类型。
• 运行时行为：在代码实际运行时，TypedDict 完全不会生效。它不会进行任何数据校验，也不会抛出异常。即使你传入了错误的键或值类型，Python 解释器也不会报错。
• 适用场景：适合用来描述 API 响应结构、配置文件或函数参数等“结构固定的字典”。它能带来极佳的 IDE 代码自动补全体验，并在代码运行前通过静态检查规避拼写错误和类型错误，且没有任何运行时性能开销。

2. Pydantic：强大的运行时数据验证库

Pydantic 是一个基于 Python 类型注解的第三方库，核心功能是数据验证和设置管理。

• 核心特点：它提供运行时强制验证。通过继承 BaseModel 定义模型，Pydantic 会在程序运行时自动检查传入的数据是否符合预期的格式和类型（如字符串长度、数值范围、邮箱格式等）。如果数据不合法，它会直接抛出 ValidationError 异常。
• 运行时行为：它不仅做校验，还能自动进行数据转换（例如将字符串类型的数字 '30' 自动转换为整数 30）和序列化（将模型实例轻松转换为字典或 JSON 字符串）。
• 适用场景：广泛应用于 Web 框架（如 FastAPI）的请求体与响应体验证、配置文件管理、数据管道处理以及 AI 模型的结构化输出等需要严格保证数据正确性的场景。

核心区别总结

简单来说，两者的最大区别在于生效阶段：

• 如果你只需要在写代码时获得编辑器的智能提示，并在编译前拦截低级错误，且不关心运行时的数据安全性，选择 TypedDict。
• 如果你需要在程序实际运行时，对传入的原始数据（如 JSON、字典）进行严格的合法性校验、自动类型转换或序列化，必须选择 Pydantic。

在 Python 工程实践中，TypedDict 和 Pydantic 并不是互相替代的关系，而是各司其职的分工关系。选择哪一个，主要取决于数据所处的系统层级以及是否需要运行时校验。以下是具体的选型指南：

一、 核心选型原则

1. 是否需要运行时校验/转换？
   • 是 → 必须选 Pydantic。
   • 否（仅需静态类型提示） → 选 TypedDict。
2. 数据的形态是什么？
   • 动态字典、JSON 数据契约 → TypedDict。
   • 固定类、不可信的外部输入 → Pydantic。
3. 数据流转的阶段？
   • 内部高频传递、纯数据载体 → TypedDict（或 dataclass）。
   • 对外接口、核心数据流程、系统边界 → Pydantic。

二、 场景化选型建议

1. 优先选择 Pydantic 的场景

• API 输入与对外接口：API 请求来自外部世界，永远是不可信的。用户可能少传字段、传错类型，此时必须使用 Pydantic 进行运行时校验、数据清洗和转换。
• 配置文件解析：需要从环境变量、.env 文件等多种来源读取配置，并自动进行类型转换（如将字符串 "true" 转为布尔值 True）。
• AI 模型结构化输出：在 LLM 开发中，将 Pydantic 模型导出为 JSON Schema 传给模型，并用其反序列化 AI 返回的 JSON，可以有效避免模型幻觉数据影响业务。
• 复杂的数据清洗管道：在数据进入核心业务逻辑之前，需要确保数据的质量和格式完全正确。

2. 优先选择 TypedDict 的场景

• 描述 API 响应结构：当你只需要描述一个结构固定、字段名和类型明确的字典，但不需要实例化或进行运行时验证时，TypedDict 是最贴切的选择。
• 轻量级数据契约：作为函数输入/输出的“形状契约”，或者定义配置片段，相比普通字典，它能提供字段级的静态检查，且没有任何运行时性能开销。
• AI Agent 原型阶段：在单 Agent 或原型阶段，如果仅需快速跑通逻辑，TypedDict 的零开销和极低学习成本非常合适。
• 高频事件处理：如果工作流需要每秒处理上万次状态更新，TypedDict 的极轻量特性可以避免 Pydantic 模型实例化带来的微小开销。

三、 核心差异对比总结

总结建议：在大型项目中，通常会将两者结合使用。例如，使用 TypedDict 来描述外部 API 返回的原始 JSON 响应结构（保证静态类型安全），而在接收用户请求或处理核心业务数据时，使用 Pydantic 来确保数据的绝对合法与安全。