本文最后更新于：2025年12月16日 下午

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 插件）

主要作用

  1. 类型安全

  • 在静态类型检查器（如 mypy、Pyright）中提供字典结构的类型检查

  • 帮助 IDE（如 VS Code、PyCharm）提供更好的代码补全和类型提示

  1. 文档化数据结构

  • 明确说明字典应该包含哪些字段

  • 清晰展示每个字段的预期类型

  1. 提高代码可维护性

  • 当字典结构发生变化时，类型检查器可以捕获相关错误

  • 新开发者更容易理解数据结构

  1. 与现有代码兼容

  • 无需修改现有函数签名即可添加类型提示

  • 兼容现有的字典操作代码

不使用 TypedDict 的弊端

  1. 类型安全性差
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 键
  1. IDE 支持有限
1
2
3
4
user = {"name": "Alice", "age": 30}
# IDE 不知道 user 有哪些键
user["naem"]  # 拼写错误，但 IDE 无法警告
user["email"]  # 不存在的键，运行时才会报错
  1. 代码可读性差
1
2
3
4
5
6
7
8
# 字典结构的意图不明确
config = {
    "host": "localhost",
    "port": 8080,
    "timeout": 30.5,
    "retry": True
}
# 哪些是必需的？哪些是可选的？类型是什么？
  1. 重构困难
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, NotRequired

class 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, Optional

class 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, NotRequired

class 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 TypedDict

class 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/

“觉得不错的话，给点打赏吧 ୧(๑•̀⌄•́๑)૭”

微信二维码

微信支付

支付宝二维码

支付宝支付

Coding > Python
#Coding #Python
Python TypedDict
https://www.zywvvd.com/notes/coding/python/python-typedict/python-typedict/
作者
Yiwei Zhang
发布于
2025年12月16日
许可协议