TypeGuard仅在静态类型检查阶段生效，不干预运行时行为；它不抛异常、不跳过分支、不校验数据合法性，仅向类型检查器提供类型收窄依据，故不能替代isinstance或运行时校验。
TypeGuard 不是运行时过滤器，它只在类型检查阶段起作用；想靠它拦住非法数据，代码会照常执行出错。
为什么 TypeGuard 不能替代 isinstance 或数据校验
很多人看到 TypeGuard 的名字就以为它能“守卫”运行时行为——其实它只是给类型检查器（如 mypy、PyCharm）看的契约。函数体里怎么写，它不管；返回 False 也不会抛异常或跳过分支。
-
TypeGuard的返回值bool对程序流无影响，if分支仍按常规逻辑执行 - 类型检查器只在静态分析时信任该函数：一旦
if is_str_list(items):成立，后续代码中items就被推断为list[str]，但若实际是["a", 123]，运行时仍会报错 - 它不自动触发数据清洗、转换或拒绝，必须手动补上
raise ValueError或return None等逻辑
TypeGuard 函数该怎么写才不会被 mypy 报错
mypy 对 TypeGuard 的实现有硬性要求，漏掉任意一条都会导致类型推断失效或直接报错。
- 函数签名必须显式标注返回类型为
TypeGuard[T]，不能用-> bool或-> TypeIs[T]（除非你明确要用TypeIs） - 至少有一个位置参数（不能全用
**kwargs或仅关键字参数），且该参数需参与类型判断 - 函数体必须包含对参数的实质性类型检查，比如
isinstance(x, SomeClass)、hasattr(x, "id")、isinstance(x, dict) and "name" in x等；纯return True或return len(x) > 0不被认可 - 避免在判断中调用可能抛
TypeError却未捕获的函数（如issubclass对非类对象），否则 mypy 可能跳过整个分支的类型推断
正确示例：
from typing import TypeGuard, Any
def is_nonempty_str_list(val: Any) -> TypeGuard[list[str]]:
if not isinstance(val, list):
return False
if len(val) == 0:
return False
return all(isinstance(item, str) for item in val)
和 Union / | 搭配使用时的实际效果
单独用 Union[str, int] 或 str | int 只告诉类型检查器“可能是这个或那个”，但进到分支后还是得手动判断。加了 TypeGuard，才能让分支内类型真正“收窄”。
- 没用
TypeGuard：def handle(x: str | int) -> str: return x.upper()会报错，因为int没有upper - 用了之后：
if is_str(x): return x.upper()—— 这里x在if块内被识别为str，.upper()通过检查 - 注意：
is_str必须自己定义，标准库没有现成的；也不能用type(x) is str替代，mypy 不认这种写法 - 多个守卫可嵌套，比如先
is_dict，再在分支里用is_user_dict进一步收窄键名和值类型
FastAPI 里哪些地方悄悄依赖了 TypeGuard
你写的路由函数里几乎看不到 TypeGuard，但它在 FastAPI 内部驱动着依赖解析、响应序列化和类型验证流程。
-
lenient_issubclass(cls, Request)是个典型——它用TypeGuard[type[_T]]告诉框架：“如果返回True，那cls就是_T的子类”，从而决定是否把当前参数当作Request实例注入 -
_annotation_is_sequence判断用户注解是不是list、tuple等，决定了 FastAPI 是否启用批量解析逻辑 - 你传一个
UploadFile类型参数，框架靠TypeGuard确认它是合法上传类型，才启用文件读取逻辑；否则就走普通表单解析 - 这些函数都不暴露给你调用，但如果你写自定义依赖或中间件，想复用类似逻辑，就得自己照着写符合规范的
TypeGuard
最易被忽略的一点：TypeGuard 的类型收窄只发生在它被直接用于 if 条件表达式时。赋值给变量、放进列表、作为参数传给另一个函数，都会丢失这个能力——这点连经验开发者也常踩坑。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
