TypedDict是为普通字典添加静态类型契约的工具，运行时仍是原生dict，仅在mypy等类型检查器中生效；它要求键名为字符串字面量、字段类型明确且默认必填，而普通dict无结构约束、键值完全动态。
TypedDict 是什么，它和普通 dict 有什么本质区别
TypedDict 不是运行时类型检查工具，它只在静态类型检查阶段（比如用 mypy）起作用。定义一个 TypedDict 类型，不会改变字典的运行时行为——你依然可以随意增删键、赋任意值，但 mypy 会报错。
关键区别在于：普通 dict 的键和值类型是动态的；TypedDict 要求每个键名固定、类型明确，且必须全部提供（除非标记为可选）。
常见错误现象：mypy 不报错，但实际运行时字段缺失或类型错乱；或者写了 TypedDict 却仍用 dict() 构造，导致类型信息丢失。
- 必须用字面量
{...}或cast显式构造，不能用dict(key=value)（会退化为普通dict） - 键名必须是字符串字面量，不能是变量或拼接结果
- 继承
TypedDict时，子类新增字段默认也是必填的，除非显式标注NotRequired
如何正确定义和使用 TypedDict（含可选字段）
定义时优先用类语法（Python 3.8+），语义清晰、支持继承和注释：
立即学习“Python免费学习笔记（深入）”；
from typing import TypedDict, NotRequired <p>class User(TypedDict): name: str age: int email: NotRequired[str] # Python 3.11+；3.8–3.10 用 <code>typing_extensions.NotRequired</code>
使用场景：API 响应解析、配置字典、函数参数校验（配合 mypy）。
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 必填字段写法直接写
key: type；可选字段必须用NotRequired[type]，不能用Optional[type]（后者表示“值可为 None”，但键仍存在） - 如果用 Python typing_extensions 并从那里导入
NotRequired - 字段顺序不影响类型兼容性，但字段名必须完全一致（包括大小写和下划线）
为什么 mypy 不报错？常见漏检原因
最常被忽略的一点：TypedDict 实例必须由字面量或 cast 创建，否则类型推导失败。
例如：
# ❌ mypy 不会检查 —— 这只是普通 dict
user = dict(name="Alice", age=30)
<h1>✅ 正确：字面量直接构造</h1><p>user: User = {"name": "Alice", "age": 30}</p><h1>✅ 或显式 cast（谨慎使用）</h1><p>from typing import cast
user = cast(User, {"name": "Alice", "age": 30})
- 函数返回
dict，即使内容符合TypedDict结构，mypy 也不会自动识别为该类型 - 用
**kwargs解包构造时，mypy 通常无法追踪键名来源，会放弃检查 - 没启用
mypy或未加--strict，TypedDict的部分检查（如多余键）可能被忽略
和 dataclass / pydantic 对比：什么时候不该用 TypedDict
TypedDict 是零运行时开销的类型提示，但它不提供任何运行时保障。
容易踩的坑：
- 需要运行时字段校验、默认值、嵌套验证 → 用
pydantic.BaseModel，别硬套TypedDict - 需要实例方法、属性、继承行为 → 用
@dataclass，TypedDict是纯数据形状描述 - 字段很多且带复杂约束（如邮箱格式、范围限制）→
TypedDict完全无能为力 - 和其他语言（如 TypeScript）对接时，
TypedDict最接近interface，但缺少联合类型、索引签名等高级能力
真正复杂的结构，往往得组合用：用 TypedDict 描述 API 输入/输出形状，用 pydantic 做落地校验和转换。别指望一个工具解决所有问题。
