函数注解（Function Annotations）是 Python 3 引入的一项语法特性。它允许在函数的参数和返回值中添加类型提示或说明信息，以增强代码的可读性、可维护性和开发效率。
Python 是动态类型语言，函数注解不会改变运行时行为，仅提供元信息，供 IDE、静态检查器、文档工具或运行时反射使用。
一、基本语法
函数参数与返回值的注解语法：
def 函数名(参数名: 注解) -> 返回值注解:
函数体示例：
def greet(name: str, age: int = 18) -> str:
return f"{name} is {age} years old."name: str 表示参数 name 应该是字符串。
age: int = 18 表示参数 age 应该是整数，默认值为 18。
-> str 表示函数的返回值应该是字符串。
注解不局限于类型，还可以是任意表达式或对象：
def add(a: '数字类型', b: int = 0) -> '返回整数':
return a + b提示：
注解中的字符串、对象仅作为元信息标签，本身不会被解释器执行类型检查。
注解信息会存储在函数的 __annotations__ 属性中：
print(greet.__annotations__)
# {'name':
, 'return':
}
二、常见类型提示（typing 模块）
为了更精确地提示复杂类型，推荐使用 模块。
1、基本类型
用于标注参数或返回值为常见的内置数据类型。比如，str表示字符串，int表示整数。
def repeat(s: str, times: int = 2) -> str:
return s * times
2、容器类型
用于标注容器及其内部元素的类型：
from typing import List, Dict, Tuple, Set
def total(scores: List[int]) -> int: # 列表，元素是 int
return sum(scores)
def phone_book() -> Dict[str, str]: # 字典，键和值均是 str
return {"Alice": "1234", "Bob": "5678"}
def split_pair() -> Tuple[int, int]: # 固定长度的元组
return (1, 2)提示：
Python 3.9+ 支持原生类型提示（无需从 typing 导入）：
def func(data: list[int]) -> dict[str, int]:
return {str(i): i for i in data}3、Optional（可选类型）
用于表示一个值可能为某类型，也可能是 None。
from typing import Optional
def find(key: str) -> Optional[int]:
return NonePython 3.10 可用 | 表示二选一。
def find(key: str) -> int | None:
return None4、Union（联合类型）
用于表示值可能属于多种类型之一。
from typing import Union
def stringify(data: Union[str, int, float]) -> str:
return str(data)Python 3.10 可用 | 表示多选一：
def stringify(data: str | int | float) -> str:
return str(data)提示：
Optional[T] 是 Union[T, None] 的简写。
5、Any（任意类型）
表示可以是任意类型，适合需要最大灵活性的场景。
from typing import Any
def log_all(*args: Any, **kwargs: Any) -> None:
print(args, kwargs)6、Callable（可调用对象）
用于表示参数或返回值是函数、方法、lambda 等可调用对象。
from typing import Callable
def apply(f: Callable[[int, int], int], x: int, y: int) -> int:
return f(x, y)
print(apply(lambda a, b: a + b, 3, 4))Callable 的格式为：Callable[[参数类型...], 返回类型]
7、Literal（字面量类型）
用于限制值必须是固定的字面量之一，常用于配置值、枚举场景。
from typing import Literal
def get_status(code: int) -> Literal["ok", "error"]:
return "ok" if code == 0 else "error"8、TypeVar（泛型类型）
用于编写泛型函数或类，保持参数和返回值类型一致。
from typing import TypeVar
T = TypeVar("T")
def identity(x: T) -> T:
return x泛型使函数/类更通用，适用于多种类型。
9、其他常用提示
Self
（Python 3.11+）用于类方法，表示返回当前类实例，更直观：
from typing import Self
class Person:
def set_name(self, name: str) -> Self:
self.name = name
return selfAnnotated
（Python 3.9+）在类型提示中附加额外元信息（例如校验规则、文档说明）：
from typing import Annotated
def scale(x: Annotated[float, "must be positive"]) -> float:
return x * 2Self 让类方法返回值更清晰，Annotated 让类型提示更有语义性。
三、应用场景
1、静态类型检查
使用工具如 进行代码静态分析，提前发现类型错误。
安装与使用：
pip install mypy
mypy your_script.py示例：
def add(a: int, b: int) -> int:
return a + b
add("1", "2") # ⚠ mypy 报错，但 Python 仍能运行2、IDE 自动补全与提示
PyCharm、VSCode 等编辑器会根据注解提供智能提示。
3、代码文档生成
如 、 会利用注解生成更清晰的 API 文档。
4、运行时验证（配合第三方库）
如 、 实现运行时类型检查。
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
u = User(name="Alice", age="18") # 自动转为 int
print(u)小结
函数注解在 Python 中并不是“强制类型”的工具，而是一种增强代码语义的说明机制。在大型项目中，合理地使用函数注解配合工具链，可以有效提高代码质量、可读性和开发效率。
“点赞有美意，赞赏是鼓励”
热门跟贴