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