mypy 默认只检查显式标注类型的函数和变量，未标注处直接跳过；需用--disallow-untyped-defs强制标注，配合泛型（如list[int]）、Pydantic mypy插件及版本锁定保障效果。
为什么 mypy 检查不到我写的 def foo(x: int) -> str: 里的错误？
因为 mypy 默认只检查「显式标注了类型」的函数和变量，没加 : int 或 -> str 的地方直接跳过——它不是在猜你心里想的是什么，而是在验证你写出来的类型声明是否自洽。
常见错误现象：mypy 对空参数列表、无返回值标注、裸 list 或 dict 类型完全沉默；甚至传入 str 给 int 参数也不报错。
- 必须给所有关键函数加上完整类型标注，包括参数和返回值
- 基础容器类型要带泛型，比如用
list[int]而不是list，否则mypy当作Any处理 - 如果项目里混着大量未标注代码，建议先用
mypy --disallow-untyped-defs强制定义必须标注，再逐步放开
mypy 报 Argument 1 to "bar" has incompatible type "str"; expected "int" 但运行时没出错
这恰恰是 mypy 在起作用：它在运行前就发现了逻辑矛盾。Python 运行时靠鸭子类型糊弄过去，不代表逻辑正确——比如你传 "42" 给一个内部做 x + 1 的函数，运行时报 TypeError 才去修，不如让 mypy 提前拦住。
使用场景：尤其适合处理外部输入（如 JSON 解析结果、命令行参数），这些值从字符串来，但业务逻辑需要数字，不标类型就容易漏掉转换步骤。
立即学习“Python免费学习笔记（深入）”；
- 别依赖“反正能跑通”，
mypy的价值就在暴露这种隐性假设 - 如果确实需要动态类型（比如配置字典），用
typing.Dict[str, Any]明确表达意图，而不是留空 - 注意
Optional[T]和T | None等价，但前者兼容性更好（尤其老版本 Python）
Pydantic 模型里写了 age: int，为什么 mypy 还是不检查传入的字典字段？
因为 Pydantic 的运行时校验和 mypy 的静态分析走的是两套机制。mypy 不会自动理解 BaseModel 字段声明等价于类型约束，除非你用 pydantic.v1 或 pydantic.v2 对应的 mypy 插件，并且配置启用。
性能 / 兼容性影响：插件会略微拖慢 mypy 启动速度，但换来的是对 Field(default_factory=...)、model_config 等高级特性的支持。
- 安装插件：
pip install pydantic[mypy]（v2）或pydantic-v1[mypy]（v1） - 在
mypy.ini或pyproject.toml中启用：plugins = pydantic.mypy - 确保 Pydantic 模型类继承自
BaseModel，且字段有明确类型（不能只靠Field(...)推断）
CI 里跑 mypy 总是失败，本地却 OK
大概率是 Python 版本或 mypy 版本不一致。比如你在本地用 Python 3.11 + mypy==1.10，CI 用的是 3.9 + mypy==0.910，后者根本不认识 list[int] 这种语法，直接报错。
另一个常见原因是路径问题：mypy 默认只检查当前目录下有 .py 文件的包，如果 CI 构建路径和本地不同，可能漏掉模块，或者误把测试文件夹当源码扫描。
- 在
pyproject.toml锁定mypy版本，例如mypy = "==1.10.0" - 用
mypy --show-traceback查看具体哪行触发了不兼容语法 - 显式指定检查路径：
mypy src/ tests/ --exclude migrations/，避免依赖默认行为
类型检查不是越严越好，而是要在“发现真实缺陷”和“不过度约束开发节奏”之间找平衡点。最常被忽略的是：团队里有人改了类型标注但忘了跑 mypy，或者把 Any 当万金油塞得到处都是——这时候报错不是工具的问题，是协作边界没对齐。
