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
自定义类型与别名，让提示更语义化
避免重复写冗长类型，也便于统一修改：
立即学习“Python免费学习笔记（深入）”；
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）和类型提示互补：前者说明用途和边界条件，后者约束数据形态
