062、类型注解体系Type Hints、mypy 静态检查、TypedDict 与 Protocol一个让我凌晨三点还在翻日志的bug去年接手一个老项目数据管道里有个函数接收一个字典里面装着用户信息。代码大概长这样defprocess_user(data):namedata[name]agedata[age]# 后面还有几十行处理逻辑调用方传进来的字典结构五花八门——有人传了{name: 张三, age: 25}有人传了{name: 李四, age: 25, email: ...}还有人传了{username: 王五, age: 30}。结果呢生产环境半夜报警KeyError、TypeError轮着来。我盯着日志里那个name拼写错误心想要是当初写了类型注解mypy 早就在 CI 阶段把这个坑堵死了。从那以后我写 Python 代码必加类型注解不是给解释器看的是给我自己和其他开发者看的——尤其是三个月后的自己。Type Hints不是强制约束是契约文档很多人觉得 Python 类型注解是“脱裤子放屁”动态语言就该动态着用。但现实是项目一旦超过 5000 行没有类型信息的代码就像没有地图的迷宫。基础写法别写错# 变量注解name:strPythoncount:int42# 这里踩过坑float 类型别写成 flaotmypy 不会报错但可读性差price:float19.99# 函数注解defgreet(name:str,age:int18)-str:returnfHello{name}, you are{age}# 复杂类型要导入 typing 模块fromtypingimportList,Dict,Tuple,Optional,Union# 别这样写List 首字母大写不是 listdefprocess_items(items:List[str])-None:foriteminitems:print(item)# Optional 表示可能为 Nonedeffind_user(user_id:int)-Optional[Dict[str,str]]:# 如果找不到返回 Noneifuser_idnotindatabase:returnNonereturn{name:Alice,email:aliceexample.com}一个让我抓狂的坑Union 和 Optional 的混用# 错误写法Optional[str] 等价于 Union[str, None]# 但有人写成 Optional[str, int] —— 这是语法错误defparse_value(val:Optional[str])-Union[str,int]:ifvalisNone:return0returnval# 正确写法Union 里包含 Nonedefparse_value(val:Union[str,None])-Union[str,int]:...mypy 静态检查把 bug 扼杀在编辑器里mypy 不是 Python 标准库的一部分但它是类型检查的事实标准。安装很简单pipinstallmypy基本用法# 检查单个文件mypy my_script.py# 检查整个项目mypy my_project/# 严格模式推荐生产环境用mypy--strictmy_script.py实战中常见的 mypy 报错# 场景一类型不匹配defadd(a:int,b:int)-int:returnab resultadd(1,2)# mypy 报错Argument 1 to add has incompatible type str; expected int# 场景二None 检查遗漏defget_name(user:Optional[Dict[str,str]])-str:# 这里踩过坑直接 return user[name] 会报错因为 user 可能为 NoneifuserisNone:returnUnknownreturnuser[name]# 场景三类型别名让代码更清晰fromtypingimportTypeAlias UserID:TypeAliasintUserData:TypeAliasDict[str,str]deffetch_user(uid:UserID)-UserData:...配置文件.mypy.ini的坑别把配置写在命令行参数里项目大了根本记不住。用配置文件[mypy] python_version 3.10 strict True ignore_missing_imports True # 第三方库没类型注解时忽略 warn_unused_ignores True # 发现没用的 # type: ignore 会警告TypedDict给字典加上结构约束普通字典的类型注解只能写Dict[str, str]但实际业务中字典是有固定结构的。TypedDict 就是干这个的。基本用法fromtypingimportTypedDictclassUser(TypedDict):name:strage:intemail:str# 现在可以这样用defcreate_user(user:User)-None:print(fCreating user:{user[name]})# 调用时 mypy 会检查字段是否存在user_data:User{name:Alice,age:30,email:aliceexample.com}create_user(user_data)# 别这样写缺少字段 mypy 会报错# user_data: User {name: Bob} # 缺少 age 和 email实战中的 TypedDict 坑# 坑一TypedDict 是运行时普通的 dict不是类实例user:User{name:Alice,age:30,email:aliceexample.com}# user.name 这样写会报 AttributeError必须用 user[name]# 坑二可选字段用 totalFalseclassPartialUser(TypedDict,totalFalse):name:strage:intemail:str# 现在可以只传部分字段defupdate_user(user_id:int,updates:PartialUser)-None:...update_user(1,{name:Bob})# 合法# 坑三继承 TypedDict 要小心classAdminUser(User):role:str# 继承 User 的所有字段并新增 roleProtocol鸭子类型的类型注解Python 讲究鸭子类型——“如果它走路像鸭子叫起来像鸭子那它就是鸭子”。Protocol 让你在类型检查时也能用鸭子类型。为什么需要 Protocol# 传统做法用抽象基类fromabcimportABC,abstractmethodclassDrawable(ABC):abstractmethoddefdraw(self)-None:...classCircle(Drawable):defdraw(self)-None:print(Drawing circle)defrender(obj:Drawable)-None:obj.draw()# 问题必须显式继承 Drawable第三方库的类没法用Protocol 的优雅解法fromtypingimportProtocolclassDrawable(Protocol):defdraw(self)-None:...classCircle:defdraw(self)-None:print(Drawing circle)classSquare:defdraw(self)-None:print(Drawing square)# 不需要继承只要实现了 draw 方法就行defrender(obj:Drawable)-None:obj.draw()render(Circle())# 合法render(Square())# 合法实战中的 Protocol 应用# 场景数据序列化classSerializable(Protocol):defto_dict(self)-dict:...classUser:def__init__(self,name:str,age:int):self.namename self.ageagedefto_dict(self)-dict:return{name:self.name,age:self.age}classProduct:def__init__(self,title:str,price:float):self.titletitle self.pricepricedefto_dict(self)-dict:return{title:self.title,price:self.price}defsave_to_db(obj:Serializable)-None:dataobj.to_dict()# 保存到数据库...save_to_db(User(Alice,30))# 合法save_to_db(Product(Laptop,999.99))# 合法Protocol 的坑# 坑一Protocol 不能用于 isinstance 检查# isinstance(obj, Drawable) 会报错Protocol 只在静态检查时生效# 坑二运行时 Protocol 没有魔法classDrawable(Protocol):defdraw(self)-None:...# 这个类没有实现 draw但 mypy 不会报错因为 Protocol 是结构子类型classNotDrawable:pass# 只有当你把 NotDrawable 传给需要 Drawable 的函数时mypy 才会报错个人经验类型注解的最佳实践从关键接口开始别一上来就给所有函数加注解先给公共 API、数据管道、核心业务逻辑加。内部辅助函数可以慢慢补。mypy 配置要严格--strict模式虽然烦人但能帮你发现很多隐藏问题。我见过太多因为Optional没处理导致的AttributeError。TypedDict 比普通字典好十倍只要字典结构固定就用 TypedDict。它让代码自文档化mypy 还能帮你检查字段拼写错误。Protocol 是接口的未来别再用 ABC 了除非你需要运行时检查。Protocol 更灵活更 Pythonic。别过度设计类型注解是工具不是枷锁。如果某个类型注解让代码变得难以理解那就简化它。记住类型注解是为了让人更容易理解代码而不是相反。CI 里一定要跑 mypy本地开发可以偷懒但 CI 必须强制检查。我见过太多“本地能跑上线就挂”的案例mypy 能拦截大部分低级错误。最后说一句类型注解不是银弹但它是我见过性价比最高的代码质量提升手段。花 10% 的时间写注解能省下 90% 的调试时间。这笔账怎么算都划算。