该用optional而非none标注可选类型，因none仅表示none类型，而optional[str]明确表达“str或none”；参数默认为none时也需标注optional；python 3.10+可用str | none替代，但协作项目建议统一用optional。
什么时候该用 Optional，而不是直接写 None
Python 类型提示里写 None 不代表“可为空”，它只表示“就是 None 类型”。真想表达“可能是 str，也可能是 None”，必须用 Optional[str]（等价于 Union[str, None]）。
常见错误现象：def parse_name(data: dict) -> str:，但实际返回可能是 None，mypy 会静默通过，运行时却抛 TypeError；换成 -> Optional[str] 后，类型检查器才能捕获逻辑漏洞。
-
Optional是语法糖，不是运行时强制约束，但它是类型检查的唯一可靠信号 - 函数参数带默认值为
None时，别忘了同步标注Optional，比如def load_config(path: Optional[str] = None) - Python 3.10+ 可用
str | None替代Optional[str]，但老项目或跨团队协作建议统一用Optional，避免兼容性问题
Any 和 Union 混用导致 mypy 报错的实际原因
Any 是类型检查的“逃生舱”，一旦出现，相关变量后续操作几乎不校验；而 Union 是显式枚举所有可能类型，mypy 会逐一分支检查。两者语义完全不同，混用常引发误报或漏报。
使用场景：读取 JSON 配置时字段类型不确定，有人写 data: Union[dict, list, Any]——这等于告诉 mypy：“这个东西可能是字典、列表，也可能完全不管”，结果 mypy 放弃对 data.keys() 的检查，反而掩盖了 list 没有 keys 方法的真实错误。
立即学习“Python免费学习笔记（深入）”；
95Shop可以免费下载使用，是一款仿醉品商城网店系统，内置SEO优化，具有模块丰富、管理简洁直观，操作易用等特点，系统功能完整，运行速度较快，采用ASP.NET(C#)技术开发，配合SQL Serve2000数据库存储数据，运行环境为微软ASP.NET 2.0。95Shop官方网站定期开发新功能和维护升级。可以放心使用！ 安装运行方法 1、下载软件压缩包； 2、将下载的软件压缩包解压缩，得到we
- 优先用具体
Union[A, B]，而非Union[A, B, Any] - 需要动态类型时，考虑
typing.cast或更细粒度的协议（Protocol），而不是塞Any -
Any在函数返回值中尤其危险：一个-> Any的函数，调用方所有后续操作都失去类型保护
为什么 TypedDict 的键名必须是字符串字面量
TypedDict 不是普通字典子类，它在类型检查阶段就固化键名和对应类型，运行时退化为普通 dict。所以键不能是变量、表达式或 f-string，否则 mypy 直接报 Invalid TypedDict key。
错误示例：key = "user_id"; User = TypedDict("User", {key: int}) → mypy 报错；正确写法是 User = TypedDict("User", {"user_id": int})。
- 键名拼写错误不会在运行时报错，但 mypy 能立刻指出
"user_id"键不存在，前提是定义时用的是字面量 - Python 3.12+ 支持更灵活的
NotRequired和Required，但键名仍需字面量 - 如果键名来自配置或环境，说明你其实需要的是
Dict[str, int]，而不是TypedDict
cast 不是绕过检查的快捷键，而是责任移交
typing.cast 不改变运行时对象，也不做任何转换，它只是告诉 mypy：“我确认这个值符合目标类型，请按此处理”。一旦用错，类型检查器就不再提醒你，错误会直接落到运行时。
典型误用：从 JSON 解析后硬 cast 成 User 类型，但数据结构实际不匹配，mypy 安静通过，运行时访问 user.name 报 KeyError。
- 只在你 100% 确认运行时类型且无法用其他方式（如
isinstance+ 类型守卫）表达时才用cast - 避免在函数返回值上链式
cast，比如cast(str, get_value()).upper()，应先赋值再 cast，方便调试和审查 - 比起
cast，更推荐用assert isinstance(x, SomeClass)，它既提供运行时防护，又能让 mypy 推导类型
类型提示不是装饰，是接口契约。写错 Optional、滥用 Any、硬 cast，看起来省事，实则把问题从编辑器挪到了凌晨三点的线上日志里。
