Python 核心
类型注解实战:从 Any 到严格模式
类型注解不是给同事看的注释,而是给工具看的契约。本文用最小改动把 Python 项目推进到可检查、可重构的状态。
很多项目的类型注解停留在「写了但没人检查」的阶段:参数标了 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 帮你生成的代码越可靠——因为它能读到契约,而不是靠猜。
