# Python Mypy：从实际项目角度看静态类型检查
他到底是什么
每次跟人聊起Python的类型注解，总会遇到类似的困惑：这玩意儿是不是让Python变成Java了？其实不然。Mypy本质上就是个工具，一个能帮你发现代码里潜在问题的扫描器。
想象一下写代码时经常遇到的情况：一个函数接受参数，调用的时候传了个字符串进去，结果函数内部当成列表来操作。这种错误在运行时才暴露，而且往往出现在最不合时宜的时候。Mypy做的就是提前帮你看穿这类问题。它不是Python解释器，不会影响你的代码运行速度，它只是在开发阶段默默扫一遍你的代码，告诉你哪里可能有问题。
他能做什么
说几个实际项目中的场景。
第一个场景：重构代码。手头有个几年前写的模块，里面有个函数返回的是字符串列表，现在要改成返回字典。没有类型标注的情况下，改完满世界找调用处，生怕漏掉某个地方。有了Mypy，把返回类型改掉，跑一遍检查，所有不兼容的调用点全标出来，比自己翻代码靠谱多了。
第二个场景：API接口。团队维护的微服务，暴露出来的接口函数参数类型改动了，下游调用的人不见得都知道。Mypy在CI阶段就能堵住这类问题，而不是等到线上出bug才去排查。
第三个场景：新手入门。刚接触项目的新同事，不知道某个参数该传什么类型。看一眼函数签名就清楚，比翻文档快，而且是活的文档，跟着代码走的。
怎么使用
安装很简单，pip install mypy就行。但要真正用得顺手，得花点时间配置。
最常见的用法是在项目根目录下跑：
mypy your_project/不过这么直接跑往往会收到一堆报错，尤其是老项目。这时候需要--ignore-missing-imports参数，不然第三方库没类型注解就会报一堆。
更实际的做法是写个mypy.ini或者pyproject.toml配置：
[tool.mypy] python_version = 3.11 ignore_missing_imports = true strict_optional = true disallow_untyped_defs = false warn_return_any = true warn_unused_configs = true这里有个取舍：disallow_untyped_defs这个选项。设为true要求所有函数都有类型注解，对于从零开始的新项目可能是好事，但对老项目来说压力太大。一步步来，先跑起来，再慢慢增加检查的严格程度。
实际项目里，我更习惯用--strict模式跑关键模块，对其他模块放宽检查：
mypy core/--strictmypy utils/ --ignore-missing-imports最佳实践
说说这几年踩过的坑。
先从关键路径开始。别想着一次性把所有代码都加上类型注解。找项目中核心的业务逻辑模块，比如支付流程、认证系统，这些地方出问题代价大，值得先投入。其他辅助模块可以后处理。
不要滥用Any。Any是Mypy的逃生出口，用多了就没意义了。碰到不确定的类型，优先考虑Union或者重载。实在没办法再用Any，但得加个注释说明原因。
类型注解要跟随业务语义。比如用NewType区分用户ID和订单ID。虽然底层可能都是int，但混用就会出大问题。Mypy能帮你抓到这种低级但致命的错误。
配合函数文档使用。类型注解说的是参数类型和返回值类型，文档说明了业务含义。两者不冲突，互相补充。比如：
defcalculate_discount(price:float,user_level:int)->float:""" 计算商品折扣 参数: price: 商品原价 user_level: 用户等级 (1-5) """在CI里跑Mypy，但别阻塞所有提交。理想情况是全量检查通过才能合并，但现实往往是老代码改不动。一个折中方案是：只对新增和修改的文件跑Mypy，用--follow-imports=skip避免检查依赖模块。
关于TypedDict的使用。碰到字典结构固定但内容多变的情况，比如配置字典或API返回的数据，用TypedDict比用Dict[str, Any]强太多。缺点是Python 3.11之前版本支持不太好，但大部分项目应该已经升级了。
和同类技术对比
说到类型检查，Python生态里还有几个选择。
Pyright是微软开发的，VSCode的Pylance插件底层就是它。速度比Mypy快，检查结果更智能，尤其对泛型的推导更聪明。Mypy在有些情况下会报多余的错误，Pyright的处理往往更合理。但Mypy有个优势：它是Python的参考实现，PEP 484里的类型系统就是跟着Mypy走的。社区里新出的类型特性，Mypy支持得最快。
Pytype是Google的，它有个有意思的特性：不需要你在代码里写类型注解，它能推导出来。适合那些不想改大量代码但想用类型检查的项目。但准确度差一些，而且对一些高级类型特性的支持不如Mypy。
Pyre是Facebook的，性能很好，但社区相对小，文档也不如Mypy完善。
回到Mypy本身，它的优势在于生态成熟。大部分知名的Python类型库都有Mypy插件，比如pydantic，sqlalchemy。你遇到的大部分问题，网上基本都能找到解决方案。劣势是速度慢，大型项目跑一次要几十秒，得配合增量检查才能忍受。
一个实用的组合方案：开发阶段用Pyright（VSCode内置），享受快速反馈；CI阶段用Mypy做最终的严格检查，确保代码质量。
最后想说，类型检查不是银弹，它不能保证代码没有bug，也不能替代测试。它更像是给代码加上的安全网，能抓住那些最蠢的失误，让人能更放心地写代码，而不是整天担心低级错误。如果你还没开始用，找个周五下午，挑一个模块试试，可能会发现一些意想不到的收获。
