在 Python 的类型提示体系中，dict 是最常用但也最容易“失控”的类型之一。当我们需要一个具有固定键名和明确值类型的字典时（例如 API 响应、配置对象、数据模型），普通的 Dict[str, Any] 就显得过于宽泛，无法提供有效的类型检查。
为此，Python 3.8 引入了 TypedDict（通过 typing_extensions 可向后兼容至 3.6+），它允许我们像定义类一样，为字典的每个键指定名称和类型，从而在保留字典灵活性的同时获得强大的静态类型安全保障。
本文将通过你整理的学习笔记，系统讲解 TypedDict 的基本用法、可选字段处理，并结合实际代码示例展示其强大之处。
一、为什么需要 TypedDict？
考虑以下场景：
defprocess_user(data: dict) -> str:
returnf"Name: {data['name']}, Age: {data['age']}"
user = {"name": "Alice", "age": 30}
print(process_user(user))
这段代码能运行，但存在严重问题：
- 如果调用者传入
{"username": "Alice"}，程序会在运行时报 KeyError - 如果
age 是字符串 "thirty"，后续计算会出错 - IDE 和类型检查器（如 mypy、PyCharm）无法提前发现这些问题
而使用 TypedDict，我们可以在编码阶段就捕获这些错误。
二、基础用法：所有字段都是必需的
首先，让我们看一个最基本的 TypedDict 声明：
📌 注意：TypedDict 看起来像类，但它不是真正的类！它只是一个类型注解，用于告诉类型检查器这个字典应该长什么样。你不能用它来实例化对象（如 PersonInfo()），只能用字面量字典（如 {"name": "...", "age": ...}）。
✅ 示例代码（来自你的笔记）
# a7_typedict.py
from typing import TypedDict
# 声明一个 TypedDict：所有字段都是必需的
classPersonInfo(TypedDict):
name: str
age: int
defprint_person(person: PersonInfo) -> None:
print(f'name: {person["name"]}')
print(f'age: {person["age"]}')
# 正确调用：包含所有必需字段
print_person({"name": "wang", "age": 18})
🔍 详细解释
class PersonInfo(TypedDict):：定义了一个名为 PersonInfo 的类型，它描述了一种字典结构。name: str 和 age: int：指定了该字典必须包含两个键："name"（值为字符串）和 "age"（值为整数）。print_person 函数接收一个 PersonInfo 类型的参数，确保传入的字典符合规范。
💡 运行输出
$ python a7_typedict.py
name: wang
age: 18
⚠️ 如果违反约束？
尝试传入缺少字段的字典：
print_person({"name": "wang"}) # 缺少 "age"
- 运行时：Python 不会报错（因为
TypedDict 不影响运行时行为）
error: Missing key "age" for TypedDict "PersonInfo" [typeddict-item]
这就是 TypedDict 的核心价值：在不牺牲运行时性能的前提下，提供编译期（开发期）的类型安全。
三、进阶用法：定义可选字段
现实中的数据往往包含可选字段。例如，一个人可能有邮箱，也可能没有。这时我们需要标记某些字段为“非必需”。
从 Python 3.11 开始，标准库 typing 模块引入了 NotRequired（之前需用 typing_extensions）。
✅ 示例代码（来自你的笔记）
# a7_typedict.py (续)
from typing import TypedDict, NotRequired
# 声明一个 TypedDict：age 是可选的
classPersonInfo2(TypedDict):
name: str
age: NotRequired[int] # age 字段可以不存在
defprint_person2(person: PersonInfo2) -> None:
print(f'name: {person["name"]}')
# 注意：不能直接访问 person["age"]，因为它可能不存在！
if"age"in person:
print(f'age: {person["age"]}')
# 调用：只传入必需字段
print_person2({"name": "wang"})
🔍 详细解释
age: NotRequired[int]：表示 age 键是可选的，但如果存在，其值必须是 int。- 在函数内部，必须先检查键是否存在，再访问，否则可能引发
KeyError。 - 这种设计迫使开发者显式处理可选字段，提高代码健壮性。
💡 运行输出
$ python a7_typedict.py
name: wang
注意：第二段代码注释掉了 print(f'age: {person["age"]}')，因为 age 可能不存在。
✅ 安全访问可选字段的方式
除了 if "key" in dict，还可以使用 .get()：
defprint_person2(person: PersonInfo2) -> None:
print(f'name: {person["name"]}')
age = person.get("age")
if age isnotNone:
print(f'age: {age}')
四、完整示例：结合必需与可选字段
让我们扩展例子，展示更真实的场景：
from typing import TypedDict, NotRequired
classUserProfile(TypedDict):
username: str # 必需
email: str # 必需
full_name: NotRequired[str] # 可选
age: NotRequired[int] # 可选
is_active: NotRequired[bool] # 可选
defcreate_profile_link(profile: UserProfile) -> str:
# 必需字段可直接使用
link = f"https://example.com/users/{profile['username']}"
# 可选字段需检查
if"full_name"in profile:
link += f"?name={profile['full_name']}"
return link
# 合法调用
user1 = {"username": "alice", "email": "alice@example.com"}
user2 = {
"username": "bob",
"email": "bob@example.com",
"full_name": "Bob Smith",
"age": 25,
"is_active": True
}
print(create_profile_link(user1))
print(create_profile_link(user2))
输出：
https://example.com/users/alice
https://example.com/users/bob?name=Bob Smith
五、与其他类型提示工具对比
| | | |
|---|
TypedDict | | | |
dataclass | | | |
NamedTuple | | | |
Pydantic BaseModel | | | |
✅ 选择建议：如果你的数据天然就是字典（如 JSON 解析结果），优先用 TypedDict；如果需要方法、验证或序列化，用 Pydantic。
六、兼容性说明
- Python ≥ 3.11：直接使用
from typing import TypedDict, NotRequired - Python 3.8–3.10：
NotRequired 需从 typing_extensions 导入：from typing import TypedDict
from typing_extensions import NotRequired
- Python 3.6–3.7：
TypedDict 也需从 typing_extensions 导入
安装 typing_extensions（向后兼容）：
pip install typing_extensions
七、总结
TypedDict 是 Python 类型提示体系中一个轻量但极其强大的工具，它解决了“结构化字典”的类型安全问题：
- ✅ 可选字段（
NotRequired）：灵活处理非必需信息
通过合理使用 TypedDict，你可以：
📚 官方文档：typing.TypedDict
现在，就用 TypedDict 来加固你的下一个 Python 项目吧！
