Python中如何使用TypedDict定义强类型的JSON映射？-Python教程-PHP中文网

typeddict是python标准库中用于定义字典键名和值类型的静态类型提示工具，运行时为普通dict，不支持直接实例化，仅服务于mypy等类型检查器。

python中如何使用typeddict定义强类型的json映射？

TypedDict 必须继承自 typing.TypedDict，不能直接实例化

很多人写 MyConfig = TypedDict("MyConfig", {...}) 后就直接 my_data = MyConfig(...)，结果报 TypeError: 'MyConfig' object is not callable。这是因为 TypedDict 创建的是类型提示构造器，不是类——它只在静态检查时起作用，运行时就是普通 dict。

正确做法是：用字面量或 dict() 构造数据，靠类型检查器（如 mypy）验证结构。例如：

from typing import TypedDict
<p>class User(TypedDict):
name: str
age: int
active: bool</p><h1>✅ 正确：赋值时结构匹配，mypy 会检查</h1><p>user: User = {"name": "Alice", "age": 30, "active": True}</p><h1>❌ mypy 报错：缺少 'active'，类型不匹配</h1><h1>user2: User = {"name": "Bob", "age": 25}</h1>

必需字段和可选字段要显式区分，否则默认全为必需

JSON 数据里常有可选字段（比如 API 返回中某些字段可能缺失），但 TypedDict 默认所有键都必须存在。不声明可选，运行时不会出错，但 mypy 会拒绝合法的字典赋值。

使用 typing.NotRequired（Python 3.11+）或 typing.Optional + 总是允许 None 的方式不等价——前者表示“键可以不存在”，后者表示“键必须存在且值可为 None”。

NotRequired[str] → 字典里可以没有这个 key，有则必须是 str
Optional[str] → 字典里必须有这个 key，值可以是 str 或 None
Python total=False 声明整个类为“非完全匹配”，再配合 Optional 模拟部分可选（但粒度粗，不推荐）

from typing import TypedDict, NotRequired
<p>class ApiResponse(TypedDict):
code: int
message: str
data: NotRequired[dict]  # 可能无此字段
timestamp: NotRequired[str]</p><h1>✅ 合法：mypy 接受缺少 data/timestamp 的字典</h1><p>resp: ApiResponse = {"code": 200, "message": "OK"}</p><div class="aritcle_card flexRow artxards">
											<div class="artcardd flexRow">
												<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill9386" title="python学习"><img
														src="https://img.php.cn/upload/skill/000/000/081/179257684888086.jpg" alt="python学习" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
												<div class="aritcle_card_info flexColumn">
													<a rel="nofollow" href="/xiazai/skill9386" title="python学习" class="overflowclass">python学习</a>
													<p class="overflowclass">Python 编程学习助手 skill，面向零基础用户。 当用户表达以下意图时触发： - 学习 Python 基础概念（变量、数据类型、循环、函数、类等） - 请求 Python 练习题或测验 - 请求审查或调试 Python 代码 - 请求 Python 项目实战指导（爬虫、数据分析、Web 开发等入门项目） - 泛化表述如"教我 Python""我想学编程""Python 怎么写""帮我学 Python" 此 skill </p>
												</div>
												<a rel="nofollow" href="/xiazai/skill9386" title="python学习" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
												</a>
											</div>
										</div>

嵌套 JSON 结构需递归定义 TypedDict，不能用 dict[str, Any]

把嵌套对象写成 payload: dict[str, Any] 就等于放弃类型约束——你无法知道 payload["user"]["id"] 是否存在、是不是 int。真正强类型的写法是逐层定义 TypedDict 子类。

注意：嵌套时别漏掉 total 参数传递；若子类型本身含可选字段，父类型引用它时无需额外修饰，语义自动继承。

避免 Any 或 Dict ——它们让类型检查形同虚设
数组元素如果是对象，用 list[SomeTypedDict]，不是 list[dict]
如果嵌套层级深且复用多，建议拆成独立类，别堆在顶层

class Address(TypedDict):
    city: str
    zip_code: str
<p>class Person(TypedDict):
name: str
address: Address  # ✅ 强类型嵌套
phones: list[str]</p><h1>✅ mypy 能检查 person["address"]["city"] 是 str</h1><p>p: Person = {
"name": "Tom",
"address": {"city": "Shanghai", "zip_code": "200000"},
"phones": ["13800138000"]
}</p>