Python 类型提示实战：告别 Any，写出更健壮的代码

Python 3.5 引入类型提示Type Hints以来经过近十年的发展类型提示已经成为生产级 Python 项目的标配。PEP 484、PEP 526、PEP 544、PEP 585……一系列 PEP 不断完善类型系统。到了 2026 年mypy、pyright等类型检查工具已经非常成熟大型项目几乎都在使用类型提示。但很多 Python 开发者还在写老派代码——要么完全不写类型要么通篇Any把类型系统当摆设。这篇文章不讲基础语法直接从真实场景出发讲清楚类型提示到底怎么用、什么时候用、什么时候不该用。一、Any是万恶之源尽量避免pythonfrom typing import Any def process(data: Any) - Any: # 处理逻辑... return result这跟没写类型有什么区别Any会关闭该变量的所有类型检查类型检查器会直接跳过。更好的做法是用Union或TypeVar缩小范围pythonfrom typing import Union # 至少限定到 str 或 int def process(data: Union[str, int]) - Union[str, int]: return data # Python 3.10 推荐用 | def process(data: str | int) - str | int: return data如果确实不知道会传什么object比Any更安全——object至少不允许你随意调用不存在的方法pythondef process(data: object) - object: # data.anything() # 类型检查器会报错 return data二、泛型让容器类型更精确List、Dict、Set不加类型参数等于白写python# ❌ 不够精确 def get_users() - list: return [{id: 1, name: 张三}] # ✅ 精确指定元素类型 from typing import TypedDict class User(TypedDict): id: int name: str def get_users() - list[User]: return [{id: 1, name: 张三}]Python 3.9 已经支持用list[str]代替List[str]标准库的泛型直接用内置类型即可不需要从typing导入List、Dict、Tuplepython# Python 3.9 推荐写法 def process_items(items: list[str]) - dict[str, int]: return {item: len(item) for item in items}自定义泛型当函数需要接收多种类型但保持类型一致性时pythonfrom typing import TypeVar T TypeVar(T) def first(items: list[T]) - T: return items[0] # 调用时自动推断 first([1, 2, 3]) # 返回 int first([a, b]) # 返回 strTypeVar还可以加约束pythonfrom typing import TypeVar # 只能是 str 或 int T TypeVar(T, str, int) def identity(value: T) - T: return value identity(1) # OK identity(a) # OK identity(1.0) # 类型检查报错三、TypedDict字典的结构化定义字典是 Python 中最常用的数据结构之一但普通字典无法表达这个 key 必须存在、那个 value 必须是 int这种约束。TypedDict解决了这个问题pythonfrom typing import TypedDict, Optional class User(TypedDict): id: int name: str email: Optional[str] # 可选字段 class Config(TypedDict, totalFalse): # totalFalse 表示所有字段都可选 debug: bool timeout: int retry_count: int def get_user_info(user: User) - str: return f{user[id]}: {user[name]} # 类型检查器会校验字段是否齐全、类型是否正确使用场景API 响应解析、配置文件读取、数据库查询结果映射。TypedDict让字典也能享受类级别的类型检查。四、Protocol鸭子类型的接口定义Protocol让你可以定义接口而不依赖继承——只要一个对象实现了指定的方法就被认为是该类型。pythonfrom typing import Protocol class HasName(Protocol): name: str class Person: def __init__(self, name: str): self.name name class Product: def __init__(self, title: str): self.title title # 属性名不同不满足协议 def greet(obj: HasName) - str: return fHello, {obj.name} greet(Person(张三)) # OK greet(Product(书)) # 类型检查报错缺少 name 属性这个特性对库开发者特别友好——用户不需要继承你的基类只要实现了约定的方法就行。更复杂的协议pythonfrom typing import Protocol, runtime_checkable runtime_checkable # 支持运行时 isinstance 检查 class SupportsAdd(Protocol): def __add__(self, other): ... def double(x: SupportsAdd): return x x double(5) # OKint 实现了 __add__ double(a) # OKstr 实现了 __add__ double([1, 2]) # OKlist 实现了 __add__五、Optional与None的处理Optional表示这个值可能是 None但很多开发者用错了pythonfrom typing import Optional # ❌ 不好表示 a 要么是 str要么是 None def get_name(a: Optional[str]) - str: return a.upper() # 类型检查器会报错a 可能是 None # ✅ 好明确处理 None 的情况 def get_name(a: Optional[str]) - str: if a is None: return 未知 return a.upper()Python 3.10 推荐用str | None代替Optional[str]pythondef get_name(a: str | None) - str: if a is None: return 未知 return a.upper()Optional不等于可以不传——函数参数有默认值时类型提示要与默认值一致pythondef greet(name: str 世界) - str: # 默认值是 str不需要 Optional return fHello, {name} def greet(name: str | None None) - str: # 可以是 None也可以是 str if name is None: name 世界 return fHello, {name}六、overload多个函数签名当函数在不同条件下接收不同类型参数时可以用overload声明多个签名pythonfrom typing import overload overload def parse(data: str) - dict: ... overload def parse(data: bytes) - dict: ... overload def parse(data: int) - str: ... def parse(data: str | bytes | int) - dict | str: if isinstance(data, str): return {type: string, value: data} elif isinstance(data, bytes): return {type: bytes, value: data.decode()} else: return str(data)类型检查器会根据传入参数的类型选择匹配的签名进行校验。七、Final与final不可变约束防止变量被重新赋值或方法被覆写pythonfrom typing import Final from typing import final # 常量 MAX_RETRY: Final 3 MAX_RETRY 5 # 类型检查器报错 # 类的 final 方法 class Base: final def run(self): pass class Child(Base): def run(self): # 类型检查器报错不能覆写 final 方法 pass八、实际项目中的类型策略策略一从公共接口开始不用一次性给所有函数加类型先从对外暴露的公共 API 开始逐步向内渗透。python# public_api.py def fetch_user(user_id: int) - User | None: ... # 内部函数可以暂时不加 def _parse_response(raw: dict): ...策略二第三方库缺少类型怎么办使用types-前缀的存根包bashpip install types-requests types-pyyaml types-redis如果存根包不存在可以自己写一个.pyi文件或者在调用处用# type: ignore临时绕过pythonimport some_old_lib result some_old_lib.do_something() # type: ignore策略三配置 pre-commit 自动检查在.pre-commit-config.yaml中加入yaml- repo: https://github.com/pre-commit/mirrors-mypy rev: v1.5.0 hooks: - id: mypy args: [--strict]让类型检查在 commit 前自动执行避免问题流入代码仓库。九、什么时候不该写类型提示场景原因一次性脚本用完就扔的代码加类型的收益低于成本原型验证需求未定类型约束会限制快速迭代动态性极强的元编程装饰器、动态属性等场景类型提示很难准确表达与 C 扩展交互很多 C 扩展没有类型信息写了也是摆设总结Python 的类型系统在 2026 年已经足够成熟。用上类型提示你至少能获得更早发现 bugmypy/pyright 在运行前就能捕获类型错误更好的开发体验IDE 自动补全准确率大幅提升更清晰的代码文档类型本身就是一份可执行的文档更放心的重构改完代码跑一遍类型检查就能发现遗漏记住一条原则类型提示应该帮助人理解代码而不是让人读懂类型系统本身。如果一个类型注解写得太复杂以至于别人看不懂那它可能弊大于利。本文为纯技术分享不涉及任何品牌或产品。