TypedDict是Python标准库中用于定义字典键名和值类型的静态类型提示工具，运行时为普通dict，不支持直接实例化，仅服务于mypy等类型检查器。
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}必需字段和可选字段要显式区分，否则默认全为必需
JSON 数据里常有可选字段（比如 API 返回中某些字段可能缺失），但 TypedDict 默认所有键都必须存在。不声明可选，运行时不会出错，但 mypy 会拒绝合法的字典赋值。
立即学习“Python免费学习笔记（深入）”；
使用 typing.NotRequired（Python 3.11+）或 typing.Optional + 总是允许 None 的方式不等价——前者表示“键可以不存在”，后者表示“键必须存在且值可为 None”。
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
-
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"}嵌套 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"]
}运行时无类型信息，JSON 解析后需手动校验字段是否存在
TypedDict 不提供运行时 schema 验证。用 json.loads() 得到的 dict 即使类型声明了 name: str，也可能是 {"name": None} 或根本没 "name" 键——mypy 不管运行时，它只检查你写的字面量或明确标注的变量赋值。
所以生产代码中，不能只靠类型提示保安全。常见做法：
- 用
pydantic.BaseModel替代（如果需要运行时校验+默认值+转换） - 用
dataclasses+dataclasses.asdict()做双向映射（适合内部结构固定场景） - 若坚持用
TypedDict，解析后加一层assert或if "key" not in d:判断（尤其对外部 JSON）
最容易被忽略的一点：TypedDict 的键名是字符串字面量，但 JSON key 是动态读入的——这意味着你无法用 getattr 或点号访问，只能用 d["field"]，且 IDE 不会在运行时补全字段名。
