类型提示是渐进式契约，仅作用于静态分析工具而非运行时校验；应优先标注高频入口、外部输入、复杂返回值及跨模块函数；Union与Optional写法差异影响mypy行为；TypedDict是校验固定结构dict的唯一可靠方式；Protocol配合泛型实现解耦依赖。
类型提示不是装饰，是渐进式契约
类型提示在 Python 3.5+ 中不改变运行时行为，也不会自动校验传入值——它只对静态分析工具（如 mypy、pyright）和 IDE 有效。你写 def f(x: int) -> str:，Python 解释器照常接受 f("hello")，但 mypy 会报错。这点必须先确认，否则容易误以为“加了类型就安全了”。
实际落地时，建议从高频调用的函数入口和公共接口开始标注，而非一次性给整个代码库补全。尤其优先覆盖：
• 接收外部输入的函数（如 API handler、CLI 参数解析）
• 返回值结构复杂的函数（如返回嵌套 dict 或自定义类实例）
• 跨模块调用的函数（避免因参数含义模糊导致的隐性 bug）
Union 和 Optional 的写法差异直接影响 mypy 行为
Optional[str] 等价于 Union[str, None]，但两者在 mypy 检查逻辑中触发的规则略有不同；更关键的是，Union 在 Python 3.10+ 支持新语法 str | None，但旧版本仍需导入 Union。混用会导致 mypy 报 error: Invalid type annotation。
常见踩坑点：
• 在 Python 3.9+ 中直接写 list[str] 是合法的，但 mypy 默认不启用 PEP 585 支持，需加配置 python_version = "3.9" 或显式启用 implicit_reexport = true
• Union[A, B, C] 里如果某个类型是字符串字面量（如 "A"），mypy 会当作前向引用处理，需加引号或使用 from __future__ import annotations
• Optional[Dict[str, Any]] 不等于 Dict[str, Any] | None：前者允许 None，后者要求字典键值类型完全匹配，mypy 对后者检查更严格
立即学习“Python免费学习笔记（深入）”；
TypedDict 是处理固定结构 dict 的唯一可靠方式
用 Dict[str, Any] 描述一个有明确字段的 API 响应（如 {"id": 123, "name": "foo", "active": True}），mypy 根本无法检查字段是否存在或类型是否匹配。此时必须用 TypedDict：
图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
from typing import TypedDict <p>class UserResponse(TypedDict): id: int name: str active: bool</p><p>def parse_user(data: UserResponse) -> str: return data["name"] # mypy 知道 data 一定有 "name" 且是 str
注意：
• TypedDict 是运行时无开销的纯类型构造，不生成类实例
• 若字段可选，要用 NotRequired（Python 3.11+）或继承 TypedDict 并设 total=False
• 不要试图用 dataclass 替代：它生成实例对象，且字段默认可变，与 dict 的语义不符
泛型类和 Protocol 是解耦依赖的关键杠杆
当多个模块依赖同一个“行为契约”（比如都调用 .save() 和 .to_dict()），用抽象基类（ABC）会强制继承关系，而 Protocol 允许鸭子类型——只要对象有对应方法签名，就满足类型约束。
例如：
from typing import Protocol <p>class Storable(Protocol): def save(self) -> None: ... def to_dict(self) -> dict: ...</p><p>def backup(item: Storable) -> None: item.save() # mypy 确保 item 有 save 方法 print(item.to_dict())
这样，数据库模型、缓存包装器、测试 mock 都可以独立实现 Storable，无需共享父类。配合泛型类（如 class Repository[T: Storable]:），能进一步把类型约束传导到容器层。
但要注意：
• Protocol 是 structural typing，mypy 默认只做静态结构检查，不验证运行时是否真有该方法
• 泛型参数 T 必须用 TypeVar 显式声明，并带约束（如 T = TypeVar("T", bound=Storable)），否则会被当作任意类型
• 复杂泛型嵌套（如 Dict[str, List[T]]）可能让 mypy 推导超时，必要时加 # type: ignore 并补上显式注解
真正难的不是写类型，而是判断哪些地方值得花时间加、加到什么粒度。一个函数参数要不要标 Literal["GET", "POST"]，取决于它是否被多处 switch 分支消费；一个返回值用不用 NamedTuple 而非 tuple，取决于下游是否频繁按索引取值——类型提示的价值，永远绑定在具体协作路径上。
