DevNull 知识库

Appearance

33｜类型注解 ​

Python 是动态类型语言，变量类型在运行时确定。但给代码加上类型注解后，函数签名就变成了一份接口文档——调用方一眼就知道该传什么类型、会返回什么类型。IDE 也能根据注解提供自动补全和错误检查。

类型注解不影响程序运行，Python 解释器不会在运行时检查类型。

一、基础注解 ​

python
def greet(name: str) -> str:
    return f"hello, {name}"


def add(a: int, b: int) -> int:
    return a + b


def is_active(status: bool) -> bool:
    return status

name: str 表示参数 name 应该是字符串，-> str 表示返回值是字符串。这些都是提示，传入其他类型不会报错：

python
greet(123)   # 能运行，但类型检查工具会报 warning

二、容器类型 ​

python
from typing import List, Dict, Set, Tuple, Optional

def process_scores(scores: List[int]) -> float:
    return sum(scores) / len(scores)


def get_user(name: str) -> Dict[str, str]:
    return {"name": name, "role": "admin"}


def find_pair(items: List[str]) -> Tuple[str, str]:
    return (items[0], items[1])

Python 3.9+ 可以直接用内置类型做注解，不需要从 typing 导入：

python
def process_scores(scores: list[int]) -> float:
    ...


def get_user(name: str) -> dict[str, str]:
    ...

三、Optional 与 Union ​

参数或返回值可能是多种类型之一：

python
from typing import Optional, Union

# Optional[X] 等价于 Union[X, None]
def find_user(name: str) -> Optional[dict]:
    ...

# Union 表示多种可能
def parse_value(value: str) -> Union[int, float, str]:
    ...

Python 3.10+ 用 | 代替 Union：

python
def find_user(name: str) -> dict | None:
    ...


def parse_value(value: str) -> int | float | str:
    ...

四、Callable ​

参数或返回值是函数：

python
from typing import Callable

def apply_operation(a: int, b: int, op: Callable[[int, int], int]) -> int:
    return op(a, b)


def add(x: int, y: int) -> int:
    return x + y


apply_operation(2, 3, add)   # 5

Callable[[参数类型], 返回值类型] 描述函数签名。

五、变量注解 ​

变量也可以加类型注解：

python
name: str = "Alice"
count: int = 0
items: list[str] = []

不赋值时：

python
name: str    # 声明变量类型，值为 None（不推荐）

六、类中的类型注解 ​

python
class Person:
    def __init__(self, name: str, age: int) -> None:
        self.name = name
        self.age = age

    def introduce(self) -> str:
        return f"{self.name}, {self.age}岁"

七、类型检查工具 ​

类型注解本身不检查，需要外部工具：

  • mypy：最常用的静态类型检查器
  • pyright：Microsoft 开发的类型检查器
  • pytype：Google 开发的类型检查器

安装 mypy：

bash
pip install mypy
mypy script.py

mypy 会分析代码中的类型注解，发现类型不匹配时给出警告。

八、何时使用类型注解 ​

场景建议
公共 API / 库函数强烈建议，调用方依赖签名理解接口
团队项目建议，减少沟通成本
个人脚本可选，简单脚本可以不加
复杂数据结构建议，容器嵌套时注解特别有价值
快速原型可选，稳定后再补

类型注解是渐进式的——可以从核心函数开始，逐步覆盖。不需要一次性给所有代码加注解。

记忆锚点：类型注解不影响运行，是给人和工具看的；参数: 类型 -> 返回值；Python 3.9+ 直接用 list[int]；X | None 表示可能为空（Python 3.10+）；Callable[[参数], 返回] 描述函数；mypy 是常用类型检查工具；类型注解渐进式添加，从公共 API 开始。