Python 核心

类型注解实战:从 Any 到严格模式

类型注解不是给同事看的注释,而是给工具看的契约。本文用最小改动把 Python 项目推进到可检查、可重构的状态。

约 4 分钟1348 字

很多项目的类型注解停留在「写了但没人检查」的阶段:参数标了 dict,返回标了 Any,运行期出了错才发现注解全是装饰。类型系统真正的价值,是让编辑器、检查器和 AI 编码助手都能看懂你的边界。

第一步:先打开检查,再逐步收口

不必一次改完全部文件。先让检查器跑起来,把最外层接口标对,内部再慢慢收紧。

from __future__ import annotations

from typing import Any, Protocol

class Repository(Protocol):
    def get(self, key: str) -> dict[str, Any] | None: ...

def load(repo: Repository, key: str) -> dict[str, Any]:
    data = repo.get(key)
    if data is None:
        raise KeyError(key)
    return data

Protocol 让依赖倒置不需要继承任何基类,测试时传入一个假实现即可。这是把「大泥球」拆开成本最低的一刀。

第二步:边界用 Pydantic,内部用普通类型

HTTP 请求、配置文件、消息队例 payload 都是不可信输入。这些地方适合用 Pydantic v2 做解析与校验,校验通过后进入内部代码的就是确定的类型。

from pydantic import BaseModel, Field

class CreateOrder(BaseModel):
    user_id: int = Field(gt=0)
    amount: int = Field(gt=0, le=10_000_000)
    note: str = Field(default="", max_length=200)

def submit(payload: CreateOrder) -> str:
    return f"order:{payload.user_id}:{payload.amount}"

不要在业务逻辑深处反复 isinstance。校验放在边界,内部只处理已经验证过的结构。

第三步:让 Any 只出现在少数地方

  • 第三方库没有存根时,给它写一个最小的 .pyi,比满屏 # type: ignore 好维护。
  • 泛型容器要写元素类型:list[str] 而不是 list。
  • TypedDict 描述外部 JSON 的形状,代价小、收益大。
  • 对确实动态的代码,用 cast() 明确表达「这里我知道类型」,并写下理由。

把检查接进日常

# pyproject.toml 片段
[tool.mypy]
python_version = "3.14"
strict = true
warn_unused_ignores = true
disallow_any_explicit = true

在 CI 里把类型检查设为必过项,配合 ruff 做格式与静态问题检查。类型注解写得越准,AI 帮你生成的代码越可靠——因为它能读到契约,而不是靠猜。