本文介绍如何通过类型守卫（Type Guard）函数 not_none 实现运行时安全检查与静态类型推导的双重保障，支持 Optional[T] 到 T 的类型精炼，并对比 assert 与 raise 的适用场景及类型检查器行为。
本文介绍如何通过类型守卫（type guard）函数 `not_none` 实现运行时安全检查与静态类型推导的双重保障，支持 `optional[t]` 到 `t` 的类型精炼，并对比 `assert` 与 `raise` 的适用场景及类型检查器行为。
在 Python 类型驱动开发中，处理可空值（如 Optional[T]）时，常需在运行时确认其非 None，同时让类型检查器（如 mypy、Pyright）理解该值后续可安全当作非空类型使用。手动写 assert val is not None 虽可行，但重复冗余；封装为通用函数既能提升可维护性，又能借助类型系统实现类型精炼（type narrowing）——即让检查器在调用后将 T | None 推断为 T。
✅ 正确的类型守卫实现
以下是最简洁、符合 PEP 484 与主流类型检查器（mypy ≥ 1.0, Pyright）规范的实现：
from typing import TypeVar, Any
T = TypeVar("T")
def not_none(val: T | None, msg: str = "Value must not be None") -> T:
if val is None:
raise TypeError(msg)
return val? 关键设计说明：
- 参数类型标注为 T | None（等价于 Optional[T]），明确接受可空输入；
- 返回类型为 T（非可空），向类型检查器声明：只要函数成功返回，结果必为非 None 的 T 实例；
- 使用 if val is None: raise ... 而非 assert，因 assert 在 -O 优化模式下被完全移除，导致类型守卫失效且无运行时保障。
? 使用示例
from typing import Optional
def process_data(data: Optional[str]) -> str:
# 类型检查器此时认为 data: str | None
cleaned = not_none(data, "data cannot be None")
# ✅ 此处 cleaned 被精炼为 str，支持所有 str 方法
return cleaned.upper().strip()
# 调用
result = process_data(" hello ") # OK
# process_data(None) # ❌ 运行时报 TypeError，且 mypy/Pyright 提前报错⚠️ 注意事项与最佳实践
避免 assert 做类型守卫
尽管 assert val is not None 在类型检查器中也能触发精炼（如 x: int | None; assert x is not None; x += 1 合法），但它不具备运行时可靠性：启用 -O 时断言消失，None 值可能穿透至下游引发 AttributeError。生产代码应优先使用显式异常。-
类型检查器已原生支持 is not None 精炼
对于简单场景，无需封装函数。现代检查器能自动识别 if x is not None: 或 assert x is not None 后的类型变化：y: str | None = get_optional_string() if y is not None: print(y.upper()) # ✅ y 被推断为 str -
不推荐 AssertTypeOrSomething[T] 等伪类型
typing.Assertion 或自定义协议无法被主流工具识别为类型守卫。唯一被广泛支持的机制是：函数参数含 | None，返回类型为不含 None 的泛型 T。立即学习“Python免费学习笔记（深入）”；
-
进阶：显式 TypeGuard 注解（Python 3.10+）
若需更严格的守卫语义（例如用于 isinstance 风格的类型分支），可使用 typing.TypeGuard：from typing import TypeGuard def is_not_none(val: object) -> TypeGuard[object]: return val is not None # 但注意：此方式无法泛化到具体类型 T，故通用 `not_none()` 函数仍推荐上述 `T | None → T` 形式
✅ 总结
not_none(val: T | None) -> T 是兼顾类型安全、运行时健壮性与工具链兼容性的标准方案。它让类型检查器理解“调用成功 = 值非空”，消除冗余断言，同时通过 raise 提供确定性错误反馈。在团队项目中统一采用此模式，可显著提升代码可读性、可维护性与静态分析准确率。
