Type Hints 仅在静态检查阶段生效，运行时完全忽略；必须配合 mypy 或 pyright 等工具主动检查才能提前发现类型错误，否则无法防止运行时错误。
Type Hints 本身不阻止运行时类型错误——它只在静态检查阶段起作用，运行时完全忽略。想靠它“防止报错”，必须配合 mypy 或 pyright 等工具做主动检查，否则等于没写。
哪些地方加 Type Hints 最容易见效？
重点不是全覆盖，而是堵住高频出错路径：函数输入输出、类属性、关键数据结构字段。比如一个处理 JSON 的函数，parse_user(data: dict) 比 parse_user(data) 能早暴露 data 是 str 或 None 的问题。
- 函数参数和返回值（尤其公共接口）必须标注，这是
mypy检查最稳的部分 -
Optional[T]要显式写，别依赖注释或文档说“可能为 None” -
Union[int, str]在 Python 3.10+ 可用int | str，但团队若混用旧版本，统一用Union更安全 - 避免对局部变量过度标注——
mypy通常能推导，强行写反而增加维护负担
为什么写了 Type Hints 还报 error: Argument 1 to "foo" has incompatible type？
常见原因是类型声明和实际传入值不匹配，且未触发类型检查。这个错误来自 mypy，不是 Python 运行时报的——如果你直接 python script.py，它根本不会出现。
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- 确认已安装并运行
mypy your_script.py，不是只靠 IDE 小波浪线（有些 IDE 默认关掉严格模式） - 检查是否漏了
from typing import *——比如用了Dict却没导入，mypy会当成Any导致误报 -
Literal、TypedDict这类精细类型，拼错字符串或键名就会直接报错，建议搭配pyright的快速反馈使用 - 第三方库缺失 stub 文件（如
requests），mypy默认按Any处理，可装types-requests补齐
Pydantic 和 Type Hints 是什么关系？
Pydantic 不是 Type Hints 的替代品，而是运行时校验层。Type Hints 告诉你“应该是什么”，Pydantic 在运行时强制“必须是什么”。两者叠加才真正降低类型错误概率。
立即学习“Python免费学习笔记（深入）”；
- 定义模型时直接复用类型提示：
class User(BaseModel): name: str; age: int——这既是 Pydantic schema，也是有效 Type Hint - 用
model_validate()替代手动dict解包，避免KeyError或类型错位 - 注意
BaseModel默认把字段转成实例属性，而纯 dataclass + Type Hints 不做运行时校验，这点常被忽略 - 如果项目已有大量
dict流转逻辑，别一上来全改成BaseModel，先从 API 输入/输出入口加Pydantic校验更实际
最易被忽略的一点：Type Hints 对动态构造的数据（比如 getattr(obj, field_name)、json.loads() 返回的 dict）几乎无效——这些地方必须靠 Pydantic、typeguard 或手动 isinstance 补位，不能指望标注后就万事大吉。
