Python类型提示仅为静态注解，需mypy等工具检查；应将mypy接入CI，对关键函数强制标注，用TypedDict替代Dict[str, Any]，状态字段优先Literal，动态操作须隔离并运行时校验。
Python 类型提示不是类型检查，typing 不会阻止运行时错误
加了 def foo(x: int) -> str: 并不意味着传入字符串就会报错——Python 解释器完全忽略它。类型提示只是注解，需要靠外部工具（如 mypy）做静态分析。很多团队误以为加了提示就“有类型安全”，结果上线后仍因 None 或错误类型触发 AttributeError 或 TypeError。
实操建议：
- 把
mypy加进 CI 流程，配置--disallow-untyped-defs和--disallow-any-expr防止漏标 - 对关键函数（如 API 输入解析、数据库模型序列化）强制标注，而非全量补全
- 用
cast()或assert isinstance(...)在运行时兜底动态来源的数据（比如 JSON 解析结果） - 避免过度依赖
Any；改用Union或更具体的协议（Protocol）表达可变行为
什么时候该用 TypedDict 而不是 Dict[str, Any]
当字典结构固定、字段名和类型已知（比如 API 响应格式），用 TypedDict 能让 mypy 检查键是否存在、值是否匹配类型；而 Dict[str, Any] 会放行任意键访问，失去所有静态保障。
常见错误现象：写 resp["user_id"] + 1，但 "user_id" 实际是字符串，mypy 却不报错——因为用了 Dict[str, Any]。
立即学习“Python免费学习笔记（深入）”；
实操建议：
- 用
class UserResp(TypedDict): user_id: int; name: str替代字典字面量标注 - 若字段可选，用
total=False和NotRequired（Python 3.11+）或Optional字段 - 从 JSON 加载后，用
isinstance(data, dict)+ 手动校验再转成TypedDict实例，别直接 cast - 避免嵌套过深的
TypedDict，超过两层建议拆成独立类或使用dataclass+__post_init__校验
Literal 和 Enum 在状态字段上的取舍
表示有限状态（如 "pending" / "done"）时，Literal["pending", "done"] 更轻量、无运行时开销，适合简单场景；Enum 支持方法、迭代、反向查找，适合需逻辑扩展的状态机。
性能与兼容性影响：
-
Literal在 Python 3.8+ 可用，但mypy对嵌套Literal推导较弱（比如list[Literal["a"]] + list[Literal["b"]]推不出list[Literal["a", "b"]]） -
Enum的成员值在运行时可被反射、序列化，但需额外处理 JSON 序列化（重写__str__或用enum.EnumEncoder） - 若状态要存数据库并映射到 Django/SQLModel 字段，
Enum更易集成；纯内部逻辑校验优先Literal
动态代码（eval、getattr、__import__）如何保类型信息
这些操作天然绕过类型检查，mypy 会标记为 Any。强行标注容易失效，正确做法是隔离动态边界，只在必要处做显式转换。
实操建议：
- 用
getattr(obj, field_name, default)后立刻用isinstance(..., expected_type)断言，再标注变量类型 - 对
eval结果，用cast(ExpectedType, result)+ 单元测试覆盖输入范围，而非信任字符串内容 - 避免在类型敏感路径（如数据验证、ORM 操作）中使用
__import__动态加载模块；改用工厂函数 + 显式类型注解 - 如果必须动态构造类型（如泛型参数），用
TypeVar+ParamSpec（Python 3.10+）替代字符串拼接
真正难的不是加类型提示，而是识别哪些地方动态性不可消除——比如插件系统、用户自定义规则、配置驱动逻辑。这些地方得靠运行时校验+清晰的错误上下文，而不是硬塞类型注解。
