Mypy 实战：利用 Python 类型提示提升代码质量

Python 的动态类型特性虽灵活，但大型项目中易引发隐蔽错误。Mypy 作为静态类型检查器，通过强制执行类型提示（Type Hints）显著提升代码健壮性。以下为实战指南：

1. 核心价值

• 错误预防：在运行前捕获类型不匹配错误
• 文档增强：类型提示即代码文档
• 重构安全：减少修改代码时的意外破坏
• 性能优化：为 PyPy 等 JIT 编译器提供优化线索

2. 基础类型提示

# 变量注解
name: str = "Alice"
score: float = 95.5
is_passed: bool = True

# 函数注解
def calculate_total(items: list[int], discount: float = 0.1) -> float:
    subtotal = sum(items)
    return subtotal * (1 - discount)

3. 复合类型

from typing import Union, Optional, Tuple

# 联合类型
def parse_input(value: Union[int, str]) -> int:
    return int(value)

# 可选类型
def find_user(id: int) -> Optional[str]:
    return user_db.get(id)

# 元组类型
def get_coordinates() -> Tuple[float, float]:
    return (40.7128, -74.0060)

4. 自定义类型

from typing import TypedDict

# 类型别名
UserId = int

# 类型字典
class UserProfile(TypedDict):
    name: str
    age: int
    email: Optional[str]

def create_profile(data: UserProfile) -> None:
    ...

5. Mypy 工作流

# 安装
pip install mypy

# 检查单个文件
mypy app/core.py

# 检查整个项目
mypy .

# 常见错误处理
error: Argument 1 to "sum" has incompatible type "List[str]"; expected "Iterable[int]"
  → 需确保列表元素类型一致

6. 实战技巧

• 渐进迁移：在现有项目添加 # type: ignore 逐步改造
• 严格模式：启用 --strict 标志强化检查
• 配置文件：使用 mypy.ini 定制规则

[mypy]
strict = True
ignore_missing_imports = True

7. 高级场景

# 泛型容器
from typing import TypeVar, Generic
T = TypeVar('T')

class Stack(Generic[T]):
    def __init__(self) -> None:
        self.items: list[T] = []
    
    def push(self, item: T) -> None:
        self.items.append(item)

# 回调类型
from typing import Callable
Processor = Callable[[list[int]], float]

def batch_process(data: list[int], fn: Processor) -> float:
    return fn(data)

关键收益：使用 Mypy 的项目错误率平均降低 15%-30%（根据 Dropbox 工程实践）。类型提示不仅是约束，更是与未来维护者的关键契约。