TypedDict 是为普通字典添加类型契约的静态检查工具，运行时仍是原生 dict，仅在编辑器和类型检查器中生效；字段名必须为字符串字面量，total=False 控制是否允许额外键，NotRequired 控制字段可选性；它与 dataclass 职责分离，不支持方法、默认值或运行时行为。
TypedDict 不能替代普通字典——它根本就不是用来“替代”的，而是给普通字典加一层类型契约。运行时它就是 dict，没封装、没代理、不拦截赋值，也不做任何运行时检查。
你写 class User(TypedDict): name: str; age: int，之后创建的 {"name": "Alice", "age": 30} 还是原生 dict，isinstance(..., dict) 返回 True，json.dumps() 照常工作，pandas.DataFrame.from_dict() 也完全兼容。
真正变化的，只发生在编辑器里和类型检查器中（比如 mypy、pyright）。
TypedDict 字段名必须是字符串字面量，不能动态生成
你不能用变量、表达式或 Enum.value 当字段名：
立即学习“Python免费学习笔记（深入）”；
from enum import Enum
class MyKey(Enum):
NAME = "name"
AGE = "age"
<h1>❌ 错误：mypy 报 Invalid statement in TypedDict definition</h1><p>class BadUser(TypedDict):
MyKey.NAME.value: str # 不允许
这是因为 TypedDict 在定义时由元类解析字段，只接受静态字符串。如果需要枚举键映射不同类型的值，得换方案：dict[MyKey, Union[str, int]] + @overload 函数重载，才能让类型检查器准确推导。
total=False 是控制“是否允许额外字段”的开关，不是“字段可选”
初学者最容易混淆这点：total=False 不是指“某些字段可以不填”，而是说“这个字典允许包含未声明的键”。真正的字段可选性，靠 typing.NotRequired（Python 3.11+）或 typing.Optional（仅值类型，不约束键存在性）来表达：
-
class PartialUser(TypedDict, total=False): name: str; age: int→ 允许传{}、{"name": "A"}、{"score": 95}（多出的"score"不报错） -
class OptionalUser(TypedDict): name: str; age: NotRequired[int]→"age"键可缺，但出现时必须是int；其他未声明键（如"score"）仍会触发mypy报错
TypedDict 和 dataclass 的边界非常清晰：一个管“结构描述”，一个管“行为建模”
如果你要序列化/反序列化 JSON、校验 API 请求体、定义配置结构，TypedDict 更轻、更直接、零运行时开销；但一旦你需要默认值、方法、属性计算、__post_init__ 或字段验证逻辑，就必须用 dataclass（或 Pydantic）。两者不是互斥升级关系，而是职责分离：
-
TypedDict的实例不能有方法，不能继承，不能设置默认值（Python 3.12 仍不支持） - 你不能对
TypedDict子类调用.model_dump()或.copy()—— 它压根不是模型对象 - 当函数参数明确只消费键值对、不做任何状态管理时，用
TypedDict类型注解，IDE 补全立刻变精准，mypy能提前拦住user["emial"]这种拼写错误
真正容易被忽略的点是：TypedDict 的价值不在运行时，而在协作链路的前半段——写代码时的提示、PR 时的类型检查、新成员读代码时的第一眼理解。它不改变程序行为，但能显著压缩“人理解数据结构”的成本。
