Python 类型注解进阶

Python类型typing

用结构化类型表达接口

Protocol 描述“能做什么”，不要求对象继承特定基类。它适合注入 logger、存储或可序列化对象等行为接口。

from typing import Protocol, TypedDict, TypeVar, overload

class Cache(Protocol):
    def get(self, key: str) -> str | None: ...

class UserPayload(TypedDict):
    id: int
    name: str

TypedDict 用于固定键的字典数据，尤其适合 API payload；它只存在于类型检查阶段，运行时仍是普通 dict。

泛型与重载

T = TypeVar('T')

def first(items: list[T]) -> T:
    return items[0]

@overload
def parse(raw: bytes) -> bytes: ...
@overload
def parse(raw: str) -> str: ...

overload 只声明给类型检查器看，仍需提供一个真实实现。
不要为了消除一个警告滥用 Any，它会让错误穿过整段调用链。
类型是设计反馈：若注解复杂得难读，通常是接口职责太多。

静态检查器不会替代运行时校验：外部 JSON、环境变量和用户输入仍要在边界处验证。

逐步给核心模块加类型比一次性覆盖全仓库稳妥，优先覆盖公开接口和易出错的数据转换。

用结构化类型表达接口

泛型与重载

相关笔记