Python typing用 TypeGuard 缩小联合类型的实现方法

我在处理“输入可能是对象，也可能是字符串列表”的接口时，最容易卡在一个细节：运行时检查明明已经通过，静态检查器仍把变量当成 list[object]。解决办法不是到处写 cast，而是把检查函数的返回注解改成 TypeGuard[目标类型]。这样检查器只在函数返回 True 的分支里收窄类型，运行时仍由你的判断逻辑负责兜底。

TypeGuard 是给静态类型检查器看的“成功分支承诺”，不是运行时转换器。检查逻辑必须真的验证目标类型，尤其要注意它默认只影响正向分支。

先把联合输入和目标类型写清楚

先确定函数接收什么、成功后要调用什么。下面的例子把外部数据定义为 list[object]，只有每个元素都是字符串时，才允许交给拼接函数。list[str] 和 list[object] 之间不能简单靠容器继承关系推导，所以这正是 TypeGuard 有价值的场景。

from typing import TypeGuard

def is_str_list(value: list[object]) -> TypeGuard[list[str]]:
    # 逐项检查，空列表也自然满足“所有元素都是字符串”。
    return all(isinstance(item, str) for item in value)

def render_names(value: list[object]) -> str:
    if is_str_list(value):
        # 成功分支里，检查器可将 value 视为 list[str]。
        return ", ".join(value)
    # 失败分支仍是 list[object]，不能直接当字符串使用。
    return "输入包含非字符串元素"

用 TypeGuard 标注正向收窄函数

TypeGuard[T] 的返回值在运行时仍是布尔值。类型检查器只把被检查函数的第一个位置参数，在 if 成功分支视为 T。因此函数体必须与注解一致：不能只返回一个固定的 True，也不要把它当作绕过类型系统的快捷方式。

如果守卫函数需要额外参数，它们可以参与判断，但不会被自动收窄。例如 is_set_of(values, str) 可以验证集合元素；真正被收窄的仍是第一个参数 values。类方法还要留意隐含的 self，需要收窄的对象应作为显式参数传入。

容器和 TypedDict 的结构检查边界

对于字典数据，先检查字段存在，再检查字段类型，避免把“键缺失”和“值类型错误”混在一起。TypedDict 只描述静态结构，TypeGuard 则把外部输入与这个结构连接起来。

from typing import TypedDict, TypeGuard

class Person(TypedDict):
    name: str
    age: int

def is_person(value: dict[object, object]) -> TypeGuard[Person]:
    # get 只能证明值类型；先检查键是否存在，再检查字段类型。
    return (
        "name" in value
        and "age" in value
        and isinstance(value["name"], str)
        and isinstance(value["age"], int)
    )

def format_person(value: dict[object, object]) -> str:
    if not is_person(value):
        # False 分支不会自动排除 Person，需要继续按原始类型处理。
        return "数据结构不匹配"
    return f"{value['name']}（{value['age']}岁）"

用静态检查器确认正负分支

写完守卫后，用项目实际使用的检查器验证，而不是只看 Python 能否运行。可以在代码中临时放置检查器支持的类型揭示函数，确认 if is_str_list(value) 内部是 list[str]，并确认 else 仍保留原始类型。PEP 647 明确规定，用户自定义 TypeGuard 的 False 结果不会自动排除目标类型。

这里也要区分 TypeGuard 与较新的 TypeIs：TypeIs 要求目标类型与输入存在子类型关系，并能在 False 分支做排除；TypeGuard 可以处理 list[object] 到 list[str] 这类不满足普通子类型关系的收窄。如果项目需要兼容 Python 3.9 及更早版本，从 typing_extensions 引入 TypeGuard；Python 3.10 起标准库 typing 已提供它。

常见问题

TypeGuard 会在运行时转换数据吗？

不会。它只改变静态分析在成功分支里的推断，函数返回的仍是普通布尔值，数据不会被复制、转换或包装。

为什么 False 分支没有自动变成“不是目标类型”？

因为 TypeGuard 只承诺 True 表示目标类型成立。若要让检查器利用 False 分支排除类型，并且目标类型符合输入的子类型约束，可以评估 TypeIs。

参考资料：Python typing 官方文档；PEP 647：User-Defined Type Guards。