TypedDict 是 Python 3.8 中引入的类型提示功能，用于为字典定义明确的键和值类型。它允许你指定字典中应该包含哪些键以及每个键对应的值类型，类似于定义了一个数据类或结构体。本文介绍相关内容。
简介
TypedDict是 Python 标准库typing模块里的工具（Python 3.8 + 支持），作用很简单：
给普通字典 “贴标签”，定义这个字典必须包含哪些字段、每个字段的类型是什么。
注意！它不是创建一个新的 “字典子类”，而是给字典加 “类型提示信息”—— 运行时 Python 不会真的检查类型（比如你强行传错类型，运行时不会报错），但编辑器（VS Code/PyCharm）和静态检查工具（如 mypy）会帮你实时纠错，提前发现问题。
TypedDict 是给普通字典加 “类型说明书”—— 告诉编辑器 “这个字典该有哪些字段，每个字段是什么类型”，让编辑器实时帮你检查错误，提前规避运行时 bug。
- 对自己：写代码时不用记字典字段，编辑器自动补全，减少低级错误；
- 对团队：新人看代码时，不用问 “这个字典里有哪些字段”，直接看 TypedDict 定义就行；
- 对项目：减少运行时的 KeyError、TypeError，提升代码健壮性。
普通字典的问题
举个常见的场景：处理坐标数据，需要一个包含x和y的字典。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
| # 函数：打印坐标def print_coords(coord): # 这里根本不知道coord需要哪些字段、字段类型是什么 print(f"X坐标：{coord['x']}，Y坐标：{coord['y']}") # 如果后续要计算，类型错了就会崩 print(f"坐标和：{coord['x'] + coord['y']}") # 坑1：少传字段，运行时才报错 print_coords({"x": 10}) # 运行后报错：KeyError: 'y' # 坑2：字段类型错，计算时才报错 print_coords({"x": 10, "y": "20"}) # 打印X/Y时没事，计算时报错：TypeError: unsupported operand type(s) for +: 'int' and 'str' # 坑3：编辑器没提示，写代码全靠记 # 输入coord.的时候，编辑器根本不知道有x/y字段，没法自动补全
|
这些问题的核心原因：普通字典没有 “类型契约” —— 没人知道它该有什么字段、字段是什么类型。而TypedDict就是来补这个漏洞的。
版本需求
| 功能 |
最低 Python 版本 |
说明 |
| 基础 TypedDict（必需字段） |
3.8+ |
支持用类继承创建 TypedDict |
| NotRequired（可选字段） |
3.11+ |
3.11 前需用typing-extensions库兼容 |
| 字典字面量直接标注 |
3.9+ |
支持dict[str, int]这种简洁语法 |
如果你的 Python 版本低于 3.11（比如 3.8/3.9/3.10），想用上NotRequired，需要先装兼容库：
1
| pip install typing-extensions
|
编辑器支持
推荐用以下编辑器，能实时显示 TypedDict 的提示和错误：
- VS Code（装 Python 插件）
- PyCharm（社区版 / 专业版都支持）
- Sublime Text（装 LSP 和 Python 插件）
主要作用
- 类型安全
- 文档化数据结构
-
明确说明字典应该包含哪些字段
-
清晰展示每个字段的预期类型
- 提高代码可维护性
-
当字典结构发生变化时，类型检查器可以捕获相关错误
-
新开发者更容易理解数据结构
- 与现有代码兼容
-
无需修改现有函数签名即可添加类型提示
-
兼容现有的字典操作代码
不使用 TypedDict 的弊端
- 类型安全性差
1
2
3
4
5
6
7
8
9
10
| # 不使用 TypedDict
def process_user(user_data):
# user_data 的结构不明确
name = user_data.get("name") # 类型未知
age = user_data.get("age") # 可能是字符串或数字？
return f"{name}: {age}"# 调用时容易出错
process_user({"name": "Alice", "age": "25"}) # age 是字符串，可能不符合预期
process_user({"name": "Bob"}) # 缺少 age 键
|
- IDE 支持有限
1
2
3
4
| user = {"name": "Alice", "age": 30}
# IDE 不知道 user 有哪些键
user["naem"] # 拼写错误，但 IDE 无法警告
user["email"] # 不存在的键，运行时才会报错
|
- 代码可读性差
1
2
3
4
5
6
7
8
| # 字典结构的意图不明确
config = {
"host": "localhost",
"port": 8080,
"timeout": 30.5,
"retry": True
}
# 哪些是必需的？哪些是可选的？类型是什么？
|
- 重构困难
1
2
| # 如果要修改字典结构，需要手动查找所有使用的地方
# 没有类型检查器帮助确保一致性
|
核心用法
TypedDict 有两种创建方式：类继承式（最常用，适合复杂场景）和字典字面量式（简洁，适合简单场景）。
方式 1：类继承 TypedDict（推荐）
通过定义一个类继承TypedDict，类里的属性就是字典的字段和类型。这是最直观、最常用的方式。
基础案例：定义坐标字典（必需字段）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
| # Python 3.8+：基础用法from typing import TypedDict # 1. 定义TypedDict类：告诉编辑器，Coord类型的字典必须有x（int）和y（int）
class Coord(TypedDict):
x: int # 字段名：x，类型：整数（必需）
y: int # 字段名：y，类型：整数（必需） # 2. 用TypedDict给函数参数加提示
def print_coords(coord: Coord):
print(f"X坐标：{coord['x']}，Y坐标：{coord['y']}")
print(f"坐标和：{coord['x'] + coord['y']}") # 3. 正确使用：字段和类型都对
correct_coord: Coord = {"x": 10, "y": 20} # 编辑器不报错
print_coords(correct_coord) # 输出：X坐标：10，Y坐标：20；坐标和：30 # 4. 错误场景：编辑器实时报错（不用等运行） # 错1：少传y字段（必需字段）
missing_field_coord: Coord = {"x": 10} # 编辑器提示：缺少必需字段'y' # 错2：y字段类型错（该传int，传了str）
wrong_type_coord: Coord = {"x": 10, "y": "20"} # 编辑器提示：类型不匹配（str≠int）
|
编辑器效果：
- 输入
correct_coord["时，编辑器会自动补全x和y；
- 少传字段或类型错时，会出现红色波浪线，鼠标放上去能看到错误原因。
进阶：必需字段 + 可选字段（用 NotRequired）
很多场景下，字典的某些字段不是必须的（比如用户信息里的 “邮箱” 可能没有）。Python 3.11 + 用NotRequired标记可选字段，3.11 前用typing-extensions的NotRequired。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
| # 情况1：Python 3.11+（直接用typing的NotRequired）
from typing import TypedDict, NotRequiredclass User(TypedDict):
id: int # 必需字段：用户ID（整数）
name: str # 必需字段：用户名（字符串）
email: NotRequired[str] # 可选字段：邮箱（字符串，可不存在）
age: NotRequired[int] # 可选字段：年龄（整数，可不存在） # 情况2：Python <3.11（用typing-extensions的NotRequired） # from typing_extensions import TypedDict, NotRequired
# class User(TypedDict):
# id: int
# name: str
# email: NotRequired[str] # 正确用法：
user1: User = {"id": 1, "name": "Alice"} # 只有必需字段，OK
user2: User = {"id": 2, "name": "Bob", "email": "bob@example.com"} # 有必需+可选，OK
user3: User = {"id": 3, "name": "Charlie", "age": 25} # 有必需+另一个可选，OK # 错误用法（编辑器提示）：
user4: User = {"id": 4} # 缺name（必需字段），报错
user5: User = {"id": 5, "name": "Dave", "email": 12345} # email类型错（该是str，传了int），报错
|
进阶：total 参数控制字段是否默认必需
TypedDict有个特殊参数total，默认值是True（所有字段必需）。如果设为False，则所有字段默认可选（除非用Required标记为必需，Python 3.11 + 支持Required）。
用表格对比total参数的效果更清晰：
| total 参数 |
字段默认状态 |
搭配 NotRequired/Required 的效果 |
适用场景 |
| True（默认） |
所有字段必需 |
用 NotRequired 标记部分字段为可选 |
大部分场景（多数字段必需） |
| False |
所有字段可选 |
用 Required 标记部分字段为必需（Python 3.11+） |
少数场景（多数字段可选） |
代码例子：total=False（默认可选）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| from typing import TypedDict, Required # Required也是3.11+# total=False：所有字段默认可选，用Required标记必需字段 class Product(TypedDict, total=False):
id: Required[int] # 必需字段：产品ID
name: str # 可选字段：产品名
price: float # 可选字段：价格
stock: int # 可选字段：库存 # 正确用法：
product1: Product = {"id": 1001} # 只有必需字段，OK
product2: Product = {"id": 1002, "name": "手机", "price": 2999.9} # 必需+部分可选，OK # 错误用法：
product3: Product = {"name": "电脑", "price": 5999.9} # 缺id（Required字段），报错
|
方式 2：字典字面量 + TypedDict（简洁版）
如果只是临时用一个简单的 TypedDict，不用专门定义类，直接用TypedDict+ 字典字面量标注即可（Python 3.9 + 支持，因为 3.9 才支持dict[str, int]这种语法）。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| # Python 3.9+：简洁用法
from typing import TypedDict# 直接标注：这个字典是TypedDict类型，有name（str）和score（int）字段
student: TypedDict("Student", {"name": str, "score": int}) = {
"name": "小明",
"score": 95
} # 函数参数也能这么用（但不如类继承清晰，复杂场景不推荐）
def print_student(student: TypedDict("Student", {"name": str, "score": int})):
print(f"姓名：{student['name']}，分数：{student['score']}") print_student(student) # 输出：姓名：小明，分数：95
|
注意：这种方式的缺点是 “不可复用”—— 如果多个地方需要用同一个 TypedDict，还是得用类继承式定义一次，避免重复代码。
避坑指南
关键字冲突
字段名是 Python 关键字（如 for、class）
如果字典的字段名刚好是 Python 关键字（比如 API 返回的字段里有 “for”），直接写会报错。解决办法：用引号把字段名括起来。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| from typing import TypedDict# 字段名是"for"（关键字），用引号括起来
class QueryParams(TypedDict):
"for": str # 正确：用引号避免关键字冲突
limit: int
offset: int # 创建实例：
params: QueryParams = {"for": "user", "limit": 10, "offset": 0} # 访问时：不能用params.for（会报错），必须用下标params["for"]
print(params["for"]) # 输出：user
print(params["limit"]) # 输出：10
|
Python 3.11 废弃旧语法
Python 3.11 之前，定义可选字段有个 “旧语法”：用Optional（比如email: Optional[str]）。但Optional和NotRequired完全不是一回事：
Optional[str]：字段必须存在，但值可以是str或None；NotRequired[str]：字段可以不存在，存在时值是str。
Python 3.11 明确废弃了用Optional表示 “字段可选” 的用法，如果你还这么写，编辑器会提示警告。
错误旧语法（3.11 + 不推荐）：
1
2
3
4
5
6
7
8
9
10
11
| from typing import TypedDict, Optionalclass OldUser(TypedDict):
id: int
name: str
email: Optional[str] # 旧写法：想表示“邮箱可选”，但实际是“必须有email，值可None” # 旧写法的问题：
user: OldUser = {"id": 1, "name": "Alice"} # 编辑器报错：缺少email字段（因为Optional要求字段必须存在） user: OldUser = {"id": 1, "name": "Alice", "email": None} # 这才是旧写法的正确用法（字段存在，值为None）
|
正确新语法（3.11+）：
1
2
3
4
5
6
7
8
9
10
| from typing import TypedDict, NotRequiredclass NewUser(TypedDict):
id: int
name: str
email: NotRequired[str] # 正确：邮箱字段可不存在 user: NewUser = {"id": 1, "name": "Alice"} # OK，字段可不存在 user: NewUser = {"id": 1, "name": "Alice", "email": "alice@example.com"} # OK，字段存在
|
运行时不生效
TypedDict 是 “类型提示”，不是 “运行时强制检查”。哪怕你定义了 TypedDict，强行传错类型的字典，Python 运行时也不会报错 —— 错误检查只在编辑器或静态工具（如 mypy）里生效。
比如下面的代码，运行时不会报错，但编辑器和 mypy 会提示错误：
1
2
3
4
5
6
7
8
9
10
| from typing import TypedDictclass Coord(TypedDict):
x: int
y: int # 强行传错类型，运行时不报错（但编辑器提示错误）
wrong_coord: Coord = {"x": "10", "y": 20} # 运行时不报错 print(wrong_coord["x"] + wrong_coord["y"]) # 运行时才报错：TypeError（str+int）
|
如果想在运行时也检查类型，可以用pydantic库（专门做数据校验），但这是额外功能，TypedDict 本身不负责运行时检查。
场景案例
TypedDict 在处理 API 返回数据时特别好用 ——API 返回的字典结构固定，用 TypedDict 标注后，不用再猜字段名和类型。
案例：解析用户列表 API 返回
假设 API 返回的数据格式如下（每个用户有 id、name，可选 email 和 address）：
1
2
3
4
5
6
7
8
9
10
11
12
13
| [
{
"id": 1,
"name": "Alice",
"email": "alice@example.com",
"address": {"city": "Beijing", "street": "Main St"}
},
{
"id": 2,
"name": "Bob",
"address": {"city": "Shanghai"}
}
]
|
用 TypedDict 标注后，代码清晰且不易错：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
| from typing import TypedDict, List, NotRequired# 1. 先定义嵌套的Address TypedDict（因为address是字典）
class Address(TypedDict):
city: str # 必需：城市
street: NotRequired[str] # 可选：街道 # 2. 定义User TypedDict，包含嵌套的Address
class User(TypedDict):
id: int # 必需：用户ID
name: str # 必需：用户名
email: NotRequired[str] # 可选：邮箱
address: Address # 必需：地址（嵌套的TypedDict） # 3. 定义API返回的类型（列表，每个元素是User）
UserList = List[User] # 4. 模拟API返回数据
def get_user_list() -> UserList:
return [
{
"id": 1,
"name": "Alice",
"email": "alice@example.com",
"address": {"city": "Beijing", "street": "Main St"}
},
{
"id": 2,
"name": "Bob",
"address": {"city": "Shanghai"} # street可选，OK
}
] # 5. 处理用户数据
user_list = get_user_list() for user in user_list: # 编辑器会自动提示user的字段：id、name、email、address
print(f"用户{user['id']}：{user['name']}") # 访问嵌套的address字段，编辑器也有提示
print(f" 城市：{user['address']['city']}") # 可选字段需要先判断是否存在
if "street" in user['address']:
print(f" 街道：{user['address']['street']}") if "email" in user:
print(f" 邮箱：{user['email']}")
|
案例的好处：
- 写代码时，编辑器会自动补全所有字段（包括嵌套的
address.city）；
- 如果 API 返回的字段少了（比如某个用户没有
address），编辑器会提前提示，不用等运行时发现。3
与类似功能的比较
| 特性 |
TypedDict |
dataclass |
NamedTuple |
普通 dict |
| 可变性 |
可变 |
可变（默认） |
不可变 |
可变 |
| 类型检查 |
静态检查 |
静态检查 |
静态检查 |
无 |
| 运行时验证 |
无 |
可添加 |
无 |
无 |
| 内存使用 |
低 |
中等 |
低 |
低 |
| 访问语法 |
dict式["key"] |
属性式.key |
属性式.key |
dict式["key"] |
| JSON 兼容 |
是 |
需要转换 |
需要转换 |
是 |
常见问题 & 错误
整理了新手用 TypedDict 时最容易踩的坑，每个坑都给解决办法。
| 常见问题 |
错误表现 / 提示 |
原因 & 解决办法 |
| Python 3.11 前用 NotRequired 报错 |
ModuleNotFoundError: No module named ‘typing.NotRequired’ |
原因：3.11 前typing模块没有 NotRequired解决：用from typing_extensions import NotRequired，并先装typing-extensions |
| 混淆 Optional 和 NotRequired |
字段没传却报错 “缺少字段” |
原因：用了Optional[str]（要求字段必须存在，值可 None），想表达 “字段可选”解决：换成NotRequired[str]（字段可不存在） |
| total=False 时字段仍需存在 |
定义class A(TypedDict, total=False): x: int，传空字典报错 |
原因：编辑器或 mypy 版本旧，没正确识别 total 参数解决：更新编辑器 Python 插件或 mypy 版本，或用NotRequired明确标记 |
| 嵌套 TypedDict 没定义 |
访问嵌套字段时编辑器没提示 |
原因：嵌套的字典没定义对应的 TypedDict，直接用dict类型解决：给嵌套字典也定义 TypedDict（如前面案例的 Address） |
| 运行时字段错没报错 |
传错字段类型，运行时没反应，后续才报错 |
原因：TypedDict 是类型提示，不做运行时检查解决：用mypy做静态检查（终端运行mypy 你的脚本.py），提前发现错误 |
总结
TypedDict 是 Python 类型系统中一个强大的工具，特别适合处理字典形式的结构化数据。虽然它不提供运行时验证，但在开发阶段通过静态类型检查，可以显著提高代码的可靠性、可读性和可维护性。对于需要保持字典形式（如处理 JSON 数据、配置、API 响应）的场景，TypedDict 是一个理想的选择。
参考资料
文章链接：
https://www.zywvvd.com/notes/coding/python/python-typedict/python-typedict/
