17370845950

Python函数注解是为开发者和工具提供类型信息的语法，不改变运行行为；基础写法为参数后加冒号类型、函数后加箭头返回类型；支持Optional、联合类型、泛型容器、自定义别名与TypedDict；建议新函数优先添加、API函数必须完整标注，并配合mypy和IDE进行静态检查。

Python函数注解（即类型提示）不是装饰器，也不是运行时强制检查的语法，而是为开发者和工具（如IDE、mypy、pyright）提供可读、可校验的类型信息。写得清楚，能显著提升代码可维护性、减少参数误用，还能让自动补全更准。

基础语法：用 -> 和 : 标注返回值与参数

在函数定义中，参数名后加冒号 + 类型，函数括号后加箭头 + 返回类型：

def greet(name: str, age: int) -> str:
    return f"Hello {name}, you are {age} years old"

• name: str 表示 name 参数应为字符串
• age: int 表示 age 应为整数
• -> str 表示函数返回值预期是字符串
• 类型提示不改变运行行为——Python仍会照常执行，哪怕传入 float 或 None

常用内置类型与组合写法

除了 int、str、bool、float 等基础类型，还需掌握这些高频写法：

• 可选值：用 Optional[str] 或简写 str | None（Python 3.10+）
• 联合类型：如 int | str 表示“可以是整数或字符串”
• 列表/字典：用 list[int]、dict[str, float]（注意大小写，需从 typing 导入或使用内置泛型，Python 3.9+ 支持内置）
• 可变参数：*args: tuple[int, ...] 表示任意多个整数；**kwargs: dict[str, Any] 需导入 Any

自定义类型与别名，让提示更语义化

避免重复写冗长类型，也便于统一修改：

from typing import Dict, List, TypedDict

UserId = int
UserName = str
UserRecord = Dict[UserId, UserName]

class User(TypedDict):
    id: int
    name: str
    active: bool

def get_users() -> List[User]:
    ...

• UserId 是类型别名，提升可读性，也方便后续改成 str（如 UUID）时批量替换
• TypedDict 适合结构固定、字段明确的字典，支持 IDE 精准提示字段名
• 避免用 dict 或 list 这类裸类型——它们不带元素类型信息，工具无法校验

真实项目中的实用建议

• 从新函数开始加注解，老代码可逐步补，不必一步到位
• 对 public API 函数（导出给其他模块调用的）务必标注完整，这是接口契约
• 用 mypy 做静态检查：安装后运行 mypy your_script.py，它会指出类型不匹配处
• VS Code + Pylance 默认支持类型提示，写错参数类型时会红色波浪线提醒
• 函数文档字符串（docstring）和类型提示互补：前者说明用途和边界条件，后者约束数据形态