Python类型注解的三种基本写法：变量、参数与返回值

一、核心语法构成与速览

Python 是一门动态类型语言，类型注解的引入（PEP 484、PEP 526）并没有将 Python 变成强制静态编译的语言。注解的本质是“元数据”，为开发者、IDE 编辑器以及静态分析工具（如 mypy、Pyright）提供明确的类型提示。

在语法上，这三种基本写法分别使用了两个核心符号：

• 冒号 :：用于变量与参数的类型标注，紧跟在变量名或形参名之后；
• 瘦箭头 ->：专用于函数的返回值类型标注，位于形参括号与函数末尾冒号之间。

二、写法一：变量注解（Variable Annotations）

变量注解通过在变量名后添加英文冒号 : 和类型表达式来声明。最常见的使用场景是定义初始变量、容器数据结构，或者提前为类属性指定类型。

1. 标量类型与带初始值的变量

当变量被初始化时，常规写法如下：

# 基本标量类型注解
username: str = "Alice"
retry_count: int = 3
threshold: float = 0.85
is_active: bool = True

根据 PEP 8 规范，变量名与冒号之间不留空格，冒号与类型名称之间保留一个空格；如果有赋值等号，等号两边各保留一个空格。

2. 仅声明类型而不赋初始值

有时需要先定义变量或属性的类型，稍后在特定逻辑分支或初始化方法中赋值。Python 允许只做类型注解而不立即给变量绑定值：

# 仅声明变量类型，暂不分配具体值
connection_status: int

# 在后续逻辑分支中完成赋值
if server_ready:
    connection_status = 200
else:
    connection_status = 500

需要注意，只声明 connection_status: int 并没有在当前局部作用域中真正创建变量名。如果在赋值前读取它，Python 解释器依然会抛出 NameError。

3. 复杂容器类型的注解

在现代 Python（3.9 及以上版本）中，可以直接使用内置的集合类型名称配合方括号表示嵌套元素的类型：

# 列表、字典与集合的嵌套注解
tags: list[str] = ["python", "tutorial"]
user_scores: dict[str, float] = {"math": 95.5, "physics": 90.0}
unique_ids: set[int] = {101, 102, 103}

三、写法二：函数参数注解（Parameter Annotations）

函数参数注解用来指明函数调用时每个形参预期接收的类型。它直接声明在函数定义的小括号内部，紧跟在每个形参名称之后。

1. 必选位置参数

对于必选参数，在形参后直接加上冒号和对应类型即可：

def calculate_tax(amount: float, tax_rate: float):
    return amount * tax_rate

这样不仅能让阅读代码的人一目了然，IDE 也会在调用时直接展示期望传入的实参类型。

2. 包含默认值的形参（注意空格规范）

当参数带有默认值时，排版格式有一个容易被忽略的细节：

# 正确规范：冒号后有空格，等号两端也有空格
def create_user(name: str, role: str = "member", level: int = 1):
    pass

# 不符合规范的写法：
# def create_user(name:str, role: str="member"):  # 易混淆且不美观

在没有类型注解时，PEP 8 要求默认参数的等号两端不加空格（例如 role="member"）；但是在同时存在类型注解与默认值时，等号两边必须各保留一个空格。

3. 可变参数与关键字参数

对于 *args 和 **kwargs，注解表示的是单个元素的预期类型，而不是包裹它们的元组或字典自身：

def sum_all(*values: int):
    # values 在函数内部是 tuple[int, ...]，但注解只需写单个元素的类型 int
    return sum(values)

def configure(**options: str):
    # options 在内部是 dict[str, str]，注解只需声明 value 的类型 str
    for key, val in options.items():
        print(f"{key}: {val}")

四、写法三：函数返回值注解（Return Annotations）

函数返回值注解用于声明函数执行结束后返回的数据类型。它被放置在函数参数列表的右括号与定义末尾的冒号之间，通过一个“瘦箭头”-> 指向返回类型。

1. 常见返回值与无返回值的显式标注

函数的返回值既可以是基础标量、复杂对象，也可以是 None：

# 返回指定类型
def is_even(number: int) -> bool:
    return number % 2 == 0

# 显式标明没有返回值（返回 None）
def log_message(msg: str) -> None:
    print(f"[LOG]: {msg}")

如果一个函数只是执行某些操作而不返回任何有效数据（隐式返回 None），强烈建议显式标注 -> None。这样静态检查工具能够及时捕获类似 result = log_message("hi") 这种不合理的赋值尝试。

2. 多种可能返回值的联合类型

在实际业务中，函数可能在查不到结果时返回 None，或者返回多种可能的类型。在 Python 3.10+ 中，可以使用竖线 | 简洁表达联合类型：

# Python 3.10+ 使用竖线连接联合类型
def find_user_id(username: str) -> int | None:
    if username == "admin":
        return 1
    return None

五、常见认知误区：类型注解会强制校验类型吗？

初次接触类型注解的读者常常产生一种误解：“既然声明了 x: int，那么给它传入字符串时，Python 解释器就会抛出 TypeError 阻止运行”。

事实恰恰相反：标准 Python 解释器在运行时完全忽略类型注解。

def greet(name: str) -> str:
    return "Hello, " + str(name)

# 传入整数并不会导致运行时报错
result = greet(123)  # 输出 "Hello, 123"，运行完全正常！

六、综合实战示例

将上述三种基本写法组合在一起，形成一个完整的业务模块代码。以下函数同时包含了带有容器类型的变量注解、带有默认值的参数注解以及明确的返回值注解：

def process_user_records(
    users: list[dict[str, str]], 
    min_length: int = 3
) -> list[str]:
    """
    过滤用户列表中名称符合长度要求的有效用户。
    """
    valid_names: list[str] = []
    
    for item in users:
        name: str = item.get("name", "")
        if len(name) >= min_length:
            valid_names.append(name)
            
    return valid_names

# 准备测试数据并调用
raw_users: list[dict[str, str]] = [
    {"name": "Bo"},
    {"name": "Charlie"},
    {"name": "Alexander"}
]

# 调用并获得类型提示保障
filtered_list: list[str] = process_user_records(raw_users, min_length=4)
print(filtered_list)  # 示例输出: ['Charlie', 'Alexander']

七、总结

变量、参数与返回值构成了 Python 类型系统的三条基础支柱。在编写现代 Python 代码时，无需一开始就在所有地方强制加上注解，建议优先从公开函数的形参与返回值开始标注，为外部调用者确立明确的契约；随着项目规模扩大，再在复杂的中间数据变量上补充局部注解，并引入静态检查工具如 mypy 纳入提交检查或持续集成流程中，从而在享受 Python 动态开发效率的同时，获得静态语言级别的安全感与可维护性。