Python 类型提示的最佳实践总结

python 3.10+ 推荐用 T | None，兼容旧版本（≤3.9）必须用 Optional[T]；混用会导致语法错误；函数参数默认为 None 时类型必须显式包含 None。

什么时候该用 Optional[T] 而不是 T | None

Python 3.10+ 支持联合类型语法 T | None，但它和 Optional[T] 并不完全等价。类型检查器（如 mypy）对二者处理一致，但实际运行时 Optional[T] 是 union[T, None] 的别名，而 T | None 是 PEP 604 引入的新语法，需 Python ≥ 3.10 才能解析——如果项目还要支持 3.9 或更早版本，必须用 Optional[T]。

常见错误是混用导致 CI 失败：比如在 3.9 环境下写 def f(x: str | None) -> int:，会直接报 SyntaxError: invalid syntax。mypy 本身不报错，但解释器过不去。

• 团队用 Python 3.10+ 且不兼容旧版本 → 可统一用 T | None，更简洁
• 需要支持 3.9 或打包成 wheel 分发 → 坚持用 Optional[T]
• 函数参数带默认值为 None 时，类型提示必须显式包含 None，否则类型检查器无法推断可为空，例如：def load_config(path: str | None = None) -> dict:

Any 和 Union 混用引发的类型擦除问题

Any 是类型系统的“逃生舱”，一旦引入，后续所有操作都会失去类型约束；而 Union[A, B] 是明确的有限集合。但很多人误以为 Union[str, int, Any] 还能保留前两项的约束，其实不然——mypy 会直接将整个类型退化为 Any。

典型场景：写一个通用日志函数，想支持任意类型输入，又希望字符串和数字有特殊处理逻辑：

立即学习“Python免费学习笔记（深入）”；

def log_value(val: Any) -> None:     if isinstance(val, str):         print(f"[str] {val}")     elif isinstance(val, int):         print(f"[int] {val}")

这段代码类型安全，但如果你改成 val: Union[str, int, Any]，mypy 就不再强制你写 isinstance 检查，因为 Any 已经覆盖一切。

• 避免在 Union 中混入 Any；真要泛型，用 Object 或定义协议（Protocol）
• 临时绕过检查请用 # type: ignore，而不是塞 Any 进联合类型
• Union 成员超过 5 个时考虑是否设计失当——可能是该拆成多个函数或引入枚举/数据类

泛型类里如何正确标注 self 返回类型

在自定义泛型类中，如果方法返回 self（比如链式调用），直接写 -> Self 最清晰，但要注意：Python 3.11+ 才原生支持 Self，3.10 需导入 from typing import Self，3.9 及更早必须用字符串字面量 -> "Myclass[T]" 或 -> "Self"（后者仅在 mypy ≥ 0.990 后支持）。

错误示例（3.9 环境）：def add(self, x: T) -> Self: → NameError: name 'Self' is not defined

• 跨版本兼容写法：from typing import TYPE_CHECKING + 字符串注解，例如：def add(self, x: T) -> "Stack[T]":
• 若用 mypy，推荐升级到 1.0+ 并启用 --enable-error-code operator，它能捕获 self 类型未标注导致的链式调用失败
• 不要用 -> MyClass（没泛型参数），这会导致类型信息丢失，下游无法感知 T 的具体类型

运行时类型检查（isinstance）与类型提示不一致的坑

类型提示只是静态契约，isinstance 是运行时行为。两者不一致时，mypy 不会报错，但逻辑可能崩在运行时。最典型的是用 Union[list, tuple] 提示，却只检查 isinstance(x, list)，漏掉 tuple 分支。

另一个高危点：自定义类继承内置类型（如 class MyList(list): ...），类型提示写 List[int]，但运行时 isinstance(x, list) 为 True，isinstance(x, List) 却为 False（因为 List 是抽象类型，不能直接实例化或用于 isinstance）。

• 运行时判断优先用具体类型（list, dict），而非泛型别名（List, Dict）
• 需要兼容多种序列类型时，用 collections.abc.Sequence 替代 Union[list, tuple, str]，既准确又支持 isinstance
• 若函数接受 Union[A, B]，所有分支必须被 isinstance 或 match 覆盖，否则 mypy 会警告 Match incomplete（开启 --warn-unreachable）

类型提示不是装饰，是接口契约。最难的从来不是写对语法，而是让类型系统真正反映运行时行为——尤其当涉及泛型、继承、动态构造和第三方库交互时，类型检查器看到的和实际执行的，常常隔着一层没写出来的隐含假设。