python 3.9起|是pep 604引入的原生联合类型运算符，非语法糖，直接改变类型检查器解析行为和ide准确性，混用union与|会导致mypy报错，应统一升级并确保工具链支持。
为什么 typing.Union 在 Python 3.9 里要换成 | 写法
Python 3.9 开始原生支持 PEP 604，允许用 | 表示联合类型，比如 str | None 替代 Union[str, None]。这不是语法糖——它直接影响类型检查器（如 mypy、pyright）的解析行为和 IDE 的跳转准确性。
常见错误是混用：在同一个项目里既有 Union[int, str] 又有 int | str，导致 mypy 报 error: Incompatible types in assignment，尤其在泛型嵌套时（如 Optional[Dict[str, Union[int, float]]]）更易出错。
实操建议：
- 统一升级到
|写法，但需确认所有协作者的 IDE 和 type checker 支持 Python 3.9+ 语法（VS Code + Pylance 默认支持；mypy 需 ≥ 0.910） - 旧代码迁移可用
pyupgrade --py39-plus自动替换Union、Optional等 -
typing.List、typing.Dict同理，改用内置list[]、dict[]（注意不是list，必须带方括号）
TypedDict 怎么写才不会被 mypy 报 Missing keys
TypedDict 是描述字典结构最实用的工具之一，但默认是“总全字典”（total=True），即所有字段都必须存在。实际中多数配置或 API 响应是部分可选的，硬写全会逼你加一堆 ... # type: ignore。
正确做法是显式声明 total=False：
from typing import TypedDict <p>class UserPayload(TypedDict, total=False): id: int name: str email: str </p>
这样 UserPayload() 就是合法空字典，UserPayload(id=1) 也合法。但要注意：
- 一旦某个字段被标注为
NotRequired（Python 3.11+），就强制要求total=False，否则 mypy 报错 - PyCharm 对
total=False的补全支持较弱，VS Code + Pylance 更稳 - 别用
Dict[str, Any]替代——它完全失去字段级校验能力
函数参数用 Protocol 还是 Callable？
当你要约束“传进来的函数长什么样”，Callable[[int, str], bool] 足够简单场景；但若需要多个方法、属性或支持鸭子类型（比如 mock 对象），就得用 Protocol。
典型误用：把本该是协议的接口硬塞进 Callable，结果类型检查器无法识别 .timeout 属性或 .retry() 方法，运行时报 AttributeError 却不报类型错。
实操建议：
- 只校验“调用签名” → 用
Callable；要校验“行为契约”（含属性、方法、甚至__len__）→ 用Protocol -
Protocol必须继承自typing.Protocol，且不能实例化；定义时避免循环引用（比如协议里引用自身类） - Python 3.9 没有
runtime_checkable装饰器的隐式支持，需手动加，否则isinstance(obj, MyProtocol)永远返回False
Literal 和 Enum 在配置项校验中怎么选
两者都能限制字符串取值范围，但语义和运行时行为不同：Literal["GET", "POST"] 是编译期字面量集合，零运行时开销；Enum 是真实对象，支持成员迭代、`.name`/`.value` 访问。
容易踩的坑：
- 用
Literal定义 HTTP 方法后，在 fastapi 路由装饰器里直接写@app.get("/x", methods=["GET"])，mypy 不报错，但运行时 fastapi 会因类型不匹配拒绝启动（它期望str，而Literal不是子类型） -
Enum成员值如果是整数，mypy 默认不校验赋值是否越界（比如Status(999)不报错），需配合enum.StrEnum（3.11+）或第三方库strenum - 配置文件（如 YAML）加载后是纯
str，用Literal校验需额外做字符串比对；用Enum则可直接Status(data["status"])触发异常
复杂点在于：类型提示只是静态契约，真正落地时得和运行时校验（如 pydantic v2 的 Literal 字段、或自定义 validator）对齐，否则 IDE 显示没问题，一跑就崩。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
