TypedDict用于为字典结构提供精确类型提示，适用于API响应、配置字典等场景，支持ide补全与静态检查，但无运行时验证，不可变且无行为。

TypedDict 主要用于给字典结构添加精确的类型提示，而不是泛泛地标注为 dict[str, Any] 或 Dict。它真正有用的地方，是当你明确知道字典的键名和对应值类型，又不想定义一个完整类（比如数据量小、结构临时、来自 jsON/API 响应等），同时希望获得 IDE 补全、类型检查和重构支持时。

处理 API 返回的 json 数据

调用 http 接口拿到的响应通常是 dict，但结构固定。用 TypedDict 可以让类型信息“透传”到业务逻辑中：

from typing import TypedDict, List 
class User(TypedDict): id: int name: str email: str is_active: bool
def fetch_user(user_id: int) -> User:
模拟 requests.get(...).json()
return {"id": 123, "name": "Alice", "email": "a@example.com", "is_active": True}
user = fetch_user(123) user["nam"]  # IDE 立即报错：Key "nam" not found in TypedDict user["name"].upper()  # ✅ 有字符串方法补全 

这样既避免了运行时 KeyError 风险（静态检查阶段就能发现拼写错误），也不用为简单结构写 dataclass 或 pydantic.BaseModel。
立即学习“Python免费学习笔记（深入）”；
配置项或参数字典的类型约束
函数接收一个配置字典，键有限且含义明确：
 

from typing import TypedDict, Optional 
class DbConfig(TypedDict): host: str port: int database: str user: str password: Optional[str]
def connect(config: DbConfig) -> None:
config 必须包含全部 required 字段
pass
connect({"host": "localhost", "port": 5432, "database": "mydb", "user": "admin"})
connect({"host": "l", "port": 5432})  # ❌ 缺少 database/user，mypy 报错


相比 **kwargs 或 Dict[str, Any]，TypedDict 能强制校验字段完整性，防止漏传关键配置。
与 JSON 序列化/反序列化协同工作
python 标准库 json 加载后是 dict，配合 TypedDict 可实现“带类型的 JSON 解析”：

定义 TypedDict 描述 JSON 结构
用 json.loads() 得到原始 dict
通过类型断言（cast）或运行时验证（如 typeguard）转为 TypedDict 实例
后续所有操作都享受类型安全

注意：TypedDict 本身不提供运行时验证，所以如果 JSON 字段缺失或类型错误，需额外加一层检查（例如用 pydantic 做 fallback，或自己写简单校验）。
替代部分 dataclass 场景（轻量级、无行为）
当只需要结构化数据容器，不需要方法、默认值、__init__ 或继承时，TypedDict 更轻：

内存开销更低（纯类型提示，无实例属性）
定义更简洁（尤其嵌套结构，不用写 field(default_factory=...)）
天然兼容 JSON-like 数据流（无需 .model_dump() 或 .dict()）

但注意：TypedDict 实例不能直接修改（除非声明为 total=False 并用 NotRequired），也不支持实例方法——它只描述“形状”，不是运行时对象。