Python 类型注解与 mypy：提升代码可维护性
掘金本周最热 · 软件开发
1. 引言：为什么需要类型注解 Python 是一门动态类型语言，变量在运行时才确定类型。这种灵活性带来了开发效率，也埋下了隐患：函数参数传错类型、返回值被误用、重构后调用方没同步修改……这些问题往往要等到运行时甚至线上才暴露。 类型注解（Type Hints）在 PEP 484 中被正式引入，它让开发者可以在源码中声明变量、参数和返回值的类型。注解本身不影响运行时行为，但配合静态检查工具 mypy，就能在编码阶段发现大量类型错误。 def greet ( name: str ) -> str : return f"Hello, {name} " greet( 42 ) # mypy 会报错：Argument 1 has incompatible type "int"; expected "str" 类型注解带来的收益主要有三点： 可读性 ：函数签名即文档，调用方无需阅读实现就能知道该传什么、会得到什么。 可维护性 ：重构时静态检查能快速定位所有受影响的位置。 协作效率 ：团队对接口契约有统一认知，减少口头沟通成本。 下图展示了类型注解在开发流程中发挥作用的位置： flowchart LR A[编写代码添加类型注解] --> B[IDE实时提示Pylance或PyCharm] A --> C[mypy静态检查] C --> D{类型是否匹配} D -->|匹配| E[合入主干] D -->|不匹配| F[报错并定位行号] F --> A B --> E 2. 基础类型注解 2.1 变量注解 Python 3.6 起支持变量注解语法： name: str = "Alice" age: int = 30 height: float = 1.68 is_active: bool = True 注解也可以只声明不赋值，此时变量处于「已声明未定义」状态，直接使用会引发 NameError ： count: int print (count) # NameError: name 'count' is not defined 2.2 函数参数与返回值 def add ( a: int , b: int ) -> int : return a + b def log ( message: str ) -> None : print (message) -> None 表示函数不返回有意义的值。注意它与「没有返回值注解」不同：后者意味着 mypy 不会检查返回值类型。 2.3 常用内置类型 注解 含义 示例 int 整数 x: int = 1 float 浮点数 y: float = 1.0 str 字符串 s: str = "a" bool 布尔值 b: bool = True bytes 字节串 data: bytes = b"abc" None 空值 n: None = None Any 任意类型（放弃检查） v: Any = object() Any 是一把双刃剑：它能快速消除报错，但也会让类型检查在该处失效，应谨慎使用。 3. 容器类型：List、Dict、Optional、Union 3.1 泛型容器 Python 3.9 之前需要从 typing 导入大写形式的容器类型；3.9 起可以直接使用内置类型作为泛型： # Python 3.9+ names: list [ str ] = [ "Alice" , "Bob" ] scores: dict [ str , int ] = { "Alice" : 95 , "Bob" : 88 } point: tuple [ int , int ] = ( 1 , 2 ) tags: set [ str ] = { "python" , "typing" } # Python 3.8 及更早 from typing import List , Dict , Tuple , Set names: List [ str ] = [ "Alice" , "Bob" ] scores: Dict [ str , int ] = { "Alice" : 95 } 推荐在新项目中统一使用小写内置泛型，老项目保持与现有风格一致即可。 3.2 Optional：可能为 None Optional[T] 等价于 T | None ，表示值要么是 T ，要么是 None ： from typing import Optional def find_user ( user_id: int ) -> Optional [ str ]: if user_id == 1 : return "Alice" return None # Python 3.10+ 写法 def find_user ( user_id: in