Python TypedDict Required 怎样表达部分字段必须存在

如果一个接口的字典里，name、version 必须存在，而 comment、owner 可以省略，Python 的 TypedDict 不必拆成两套类型。用 total=False 先把字段设为“默认可缺省”，再用 Required 标回真正的必填键即可。

官方文档：https://docs.python.org/3/library/typing.html

核心写法是：class Payload(TypedDict, total=False)，然后写 name: Required[str]。Required 约束的是键必须存在，不是字符串一定非空；它也不会替普通 dict 自动执行运行时校验。

先分清字段存在性和字段值类型

TypedDict 描述的是“字典允许哪些字符串键，以及每个键对应什么值类型”。字段存在性和字段值类型是两条不同规则：Required[str] 表示键必须出现且值按 str 检查；它不等价于“值不能是空字符串”。

from typing import Required, TypedDict

class UserPayload(TypedDict):
    # Required 约束键存在，str 约束键对应的值类型
    name: Required[str]

payload: UserPayload = {"name": "Ada"}
# payload = {}  # 类型检查器应提示缺少 name

默认情况下，TypedDict 的字段是必填的。因此只有“部分字段必填”时，才需要引入 total=False 或显式混合继承。

用 total=False 建立可选字段基线

把字段数量较多、但多数来自可选请求参数的对象先定义成 total=False，可以减少重复的 NotRequired。随后用 Required 把协议真正依赖的字段挑出来。

from typing import NotRequired, Required, TypedDict

class CreateUser(TypedDict, total=False):
    # total=False 让本类中未覆盖的字段默认可以缺失
    name: Required[str]
    version: Required[int]
    comment: str
    # 显式写出 NotRequired，适合强调可缺省的公共字段
    owner: NotRequired[str]

request: CreateUser = {"name": "Ada", "version": 1}

这里的结果是：name 和 version 必须存在；comment 和 owner 可以不出现，但一旦出现仍要满足各自的值类型。total=False 只影响当前类体里的字段，不会把继承来的规则随意改写。

用 Required 和继承处理版本兼容

如果项目需要兼容较老的 Python 版本，或者希望把“基础可选字段”和“新增必填字段”拆开，可以使用 TypedDict 继承。它表达的是同一套字段契约，不是运行时的类层次业务对象。

from typing import TypedDict

class OptionalPart(TypedDict, total=False):
    # 兼容写法：基础字段默认允许省略
    comment: str
    owner: str

class UserPayload(OptionalPart):
    # 子类默认 total=True，因此新增字段默认必填
    name: str
    version: int

在现代 Python 中，Required 和 NotRequired 更直观，尤其适合字段集中在同一个定义里的场景。不要把 Optional[str] 当成“键可以缺失”：它通常只表示值可以是 None，键是否存在仍由 Required、NotRequired 或 total 决定。

用元数据检查静态契约边界

TypedDict 类型对象提供 __required_keys__ 和 __optional_keys__，可以帮助框架或调试代码读取字段集合。但这类元数据不是校验器；要拒绝来自网络的缺键请求，仍需在边界层编写显式检查或交给专门的运行时数据校验库。

from typing import TypedDict

class CreateUser(TypedDict, total=False):
    # 显式字段集合便于类型检查器和框架读取
    name: str
    version: int

required = CreateUser.__required_keys__
optional = CreateUser.__optional_keys__
# 真实接口仍应检查 payload 是否包含必填键，再读取其值
def has_required_keys(payload: dict[str, object]) -> bool:
    # 只判断键是否存在，不把空字符串误当成缺键
    return required.issubset(payload)

若使用 from __future__ import annotations 或字符串形式注解，官方文档提醒运行时元数据可能不准确；这更说明类型标注和运行时输入校验应分层处理。

常见问题

Required 会检查值不能为空吗？

不会。它只检查键是否存在；空字符串、零或 None 是否允许，要由值类型和业务校验另行决定。

字段默认必填，还需要写 Required 吗？

不需要，但在 total=False 的混合字段定义中，写出来能清楚表达协议边界。

TypedDict 能替代请求参数校验吗？

不能。它主要服务静态类型检查和工具提示；网络边界仍要做键、值、范围和错误响应的运行时校验。

记住三点：先用 total 设定默认存在性，再用 Required/NotRequired 修正单个字段，最后把 TypedDict 的静态契约与运行时校验分开。