Python 静态类型检查：mypy 工具的使用

Python 是动态类型语言，变量类型在运行时才确定。这带来灵活性，但也容易因类型错误导致程序崩溃。安装并运行 mypy 可在不执行代码的情况下提前发现类型问题，提升代码健壮性。

安装 mypy

打开终端，执行以下命令安装 mypy：

pip install mypy

若项目使用虚拟环境，确保已激活该环境后再运行上述命令。

编写带类型注解的 Python 代码

mypy 依赖类型注解（Type Hints）进行检查。从 Python 3.5 起，语言原生支持类型注解。例如，编写一个简单函数：

def greet(name: str) -> str:
    return "Hello, " + name

result = greet("Alice")
print(result)

此处 name: str 表示参数 name 应为字符串，-> str 表示函数返回字符串。

再看一个可能出错的例子：

def add_numbers(a: int, b: int) -> int:
    return a + b

total = add_numbers(5, "10")  # 错误：第二个参数是字符串

虽然这段代码能运行（Python 允许 int + str 报错但不会静态阻止），但 mypy 会提前指出类型不匹配。

运行 mypy 检查

在终端中进入包含 Python 文件的目录，执行：

mypy your_script.py

将 your_script.py 替换为你的文件名。

以 add_numbers 示例为例，假设文件名为 example.py，运行：

mypy example.py

输出类似：

example.py:4: error: Argument 2 to "add_numbers" has incompatible type "str"; expected "int"
Found 1 error in 1 file (checked 1 source file)

mypy 明确指出第 4 行传入了错误类型，无需运行程序即可发现问题。

处理常见类型场景

可选参数与默认值

若参数可为空或有默认值，使用 Optional 或直接标注：

from typing import Optional

def process_item(item: Optional[str] = None) -> str:
    if item is None:
        return "default"
    return item.upper()

Optional[str] 等价于 Union[str, None]，表示 item 可以是字符串或 None。

列表、字典等容器类型

使用 List、Dict 等泛型标注：

from typing import List, Dict

def get_scores() -> Dict[str, int]:
    return {"Alice": 95, "Bob": 88}

def average(scores: List[int]) -> float:
    return sum(scores) / len(scores)

从 Python 3.9 起，可直接使用内置类型如 list[int]、dict[str, int]，无需导入：

def average(scores: list[int]) -> float:
    return sum(scores) / len(scores)

配置 mypy 行为

mypy 默认较严格。可通过配置文件调整规则。

创建配置文件 mypy.ini 或 setup.cfg 在项目根目录。

例如，mypy.ini 内容如下：

[mypy]
python_version = 3.10
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True

关键配置项说明：

若使用 setup.cfg，需放在 [mypy] 节下：

[mypy]
disallow_untyped_defs = True

在大型项目中使用

对于多文件项目，直接运行 mypy 并指定目录或文件列表：

mypy src/

或

mypy module1.py module2.py

mypy 会递归检查 src/ 下所有 .py 文件。

为提升效率，结合 pre-commit 钩子自动检查：

1. 安装 pre-commit：

pip install pre-commit

2. 创建 .pre-commit-config.yaml：

repos:
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.8.0
    hooks:
      - id: mypy
        args: [--config-file=mypy.ini]

3. 安装钩子：

pre-commit install

此后每次 git commit 前，自动运行 mypy 检查，若类型错误则阻止提交。

处理 mypy 无法推断的情况

有时 mypy 无法确定变量类型，可显式声明：

from typing import cast

data = get_unknown_data()  # 返回 Any
numbers = cast(list[int], data)  # 告诉 mypy 这是整数列表

或使用变量注解：

items: list[str] = []
items.append("test")

避免写成：

items = []  # mypy 推断为 list[Unknown]
items.append("test")  # 后续操作可能报错

忽略特定行的检查

若某行确实需要绕过类型检查（如与旧代码兼容），在行尾添加 # type: ignore：

legacy_func(x)  # type: ignore

可附加原因：

legacy_func(x)  # type: ignore[attr-defined]

但应尽量减少使用，仅作为临时方案。

验证类型注解是否生效

运行 mypy 时添加 --strict 参数启用最严格模式：

mypy --strict your_file.py

该模式开启多项检查，包括禁止隐式 Any、要求函数返回类型等，适合新项目。

若已有项目难以一步到位，逐步启用规则：先修复明显错误，再在配置中逐项开启严格选项。

与 IDE 集成

主流编辑器（如 VS Code、PyCharm）支持 mypy 实时提示。

以 VS Code 为例：

1. 安装 Python 扩展
2. 在设置中搜索 "mypy"
3. 启用 "Python › Analysis: Type Checking Mode" 并选择 "basic" 或 "strict"

此后编辑代码时，类型错误会直接在编辑器中高亮显示，无需手动运行命令。

常见错误及解决方法

遇到 error: Skipping analyzing "xxx": found module but no type hints or library stubs 时，表示第三方库无类型信息。可在配置中添加：

[mypy]
ignore_missing_imports = True

或为该库安装类型存根包（如 types-requests）：

pip install types-requests

最佳实践总结

1. 新项目从第一天起启用 mypy，配置 disallow_untyped_defs = True
2. 为所有函数和关键变量添加类型注解
3. 使用 --strict 模式持续保持代码质量
4. 通过 pre-commit 或 CI 流程强制类型检查
5. 优先修复类型错误，而非使用 # type: ignore

# 正确示例：完整类型注解
from typing import List

def calculate_total(prices: List[float]) -> float:
    return sum(prices)

items: List[float] = [10.5, 20.0, 15.75]
total: float = calculate_total(items)