mypy 是什么
mypy 是 Python 的静态类型检查器：它读取代码里的类型注解，在不运行程序的情况下找出类型不匹配、可能为空的取值、调用参数错误等问题。它支持增量检查与类型存根包，适合渐进式类型化——先对新增代码开严格模式，再逐目录扩大范围。
基本信息
| 定位 | 基于类型注解的静态检查，不运行代码 |
|---|---|
| 严格档 | 开启一组严格检查选项 |
| 缓存 | 增量检查，缓存目录用于加速重复运行 |
| 配套 | 第三方库缺失类型信息时可安装类型存根包 |
| 配置位置 | 通常写在 pyproject.toml 或项目配置文件里 |
常用命令
常用命令
mypy --strict src/ # 对指定目录启用严格检查
mypy src/ # 按配置文件执行
mypy --install-types # 缺少类型存根时安装对应包
mypy --show-error-codes src/ # 带错误码输出，便于按规则忽略落地要点
- 从新增代码开始严格：历史代码逐步纳入，避免一次改动过大。
- 按错误码逐类处理：先解决影响正确性的类别，再处理风格类提示。
- 第三方边界先补存根或包一层适配，而不是全局忽略。
- CI 与本地使用同一版本与配置，避免结论不一致。
- 忽略要写在具体位置并附原因，避免整文件级别的忽略。
常见问题与处理
| 问题 | 处理方式 |
|---|---|
| 第三方库没有类型信息 | 安装类型存根，或局部包一层适配代码 |
| 历史代码大量报错 | 按目录或模块逐步纳入检查范围 |
| 注解与运行时不一致 | 先修正注解，让检查反映真实行为 |
| 过度使用忽略 | 把行内忽略换成具体错误码并写明原因 |
| 可选依赖的类型 | 用条件导入配合类型检查开关处理 |
落地顺序：先对新增代码开严格，再逐目录扩大；全局忽略只作临时手段，并记录清理计划。
类型注解写清楚本身就是文档：调用方不必读实现就能知道参数与返回值的含义。