Python函数类型注解怎么写：参数与返回值的符号规范

Python 函数类型注解核心语法卡片

在 Python 中，函数类型注解（Type Hints）通过冒号 : 为参数标注类型，通过箭头符号 -> 为返回值标注类型。标准语法形式为 def 函数名(参数: 类型 = 默认值) -> 返回值类型:。掌握这套符号的核心不仅在于记住符号本身，还在于严格遵循 PEP 8 的空格与排版规范，理清带默认值、可变参数时的书写顺序，并准确理解静态类型检查与运行时执行的本质区别。本文将拆解参数与返回值注解的标准符号写法、常见使用场景及易错清单。

一、核心符号基础：参数冒号与返回值箭头

类型注解最早由 PEP 484 引入，目的是为静态代码分析工具（如 mypy、PyCharm、VS Code 语言服务）以及代码阅读者提供明确的接口契约。它不改变函数的执行逻辑，但有着严格的书写符号规范。

1. 参数注解规范：紧贴冒号与单空格

为普通参数指定类型时，在参数名称后直接紧跟半角英文冒号 :，冒号后空一个半角空格，再写出类型名称。多个参数之间使用英文逗号分隔，逗号后同样遵循常规留一个空格：

def greet(name: str, repeat_count: int) -> None:
    for _ in range(repeat_count):
        print(f"Hello, {name}")

根据 PEP 8 风格指南，严禁在参数名与冒号之间插入空格（例如写成 name : str 是不合规的），也不应省略冒号后的空格（如 name:str 会降低可读性）。

2. 返回值注解规范：右括号后箭头接末尾冒号

声明函数返回值类型时，箭头符号 ->（由半角减号和大于号组成）放置在参数列表的闭合右括号 ) 与函数体末尾冒号 : 之间。箭头前后两端均需保留一个空格：

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

对于执行操作而不显式返回业务数据的函数，或者显式返回 None 的函数，规范做法是显式标注 -> None，而不是省略返回值注解。显式标注 -> None 能让类型检查工具明确知晓该函数“没有返回值”，一旦函数体内误写了 return value，静态检查器便能立即给出警告。

图 1：函数类型注解各要素与空格排版规范拆解

二、默认值与特殊参数的符号顺序规范

当函数参数带有默认值，或者包含动态可变参数时，符号的先后顺序和空格规则会有进一步的讲究。

1. 带默认值参数的书写顺序与空格规则

如果参数既有类型注解又有默认值，其符号排列顺序固定为：参数名 → 冒号 → 空格 → 类型名 → 空格 → 等号 → 空格 → 默认值。例如：

# 正确规范：等号两边均有空格
def setup_connection(host: str, port: int = 8080, timeout: float = 5.0) -> bool:
    # 业务连接逻辑
    return True

这里存在一个容易被忽视的格式对比：在未声明类型注解的原生函数参数中，PEP 8 要求默认参数的等号两边不加空格（如 def connect(port=8080):）；但只要加入了类型注解，等号两侧就必须各保留一个空格（如 port: int = 8080）。这一规则确保了密集符号在视觉上的清晰度。

2. 可变参数（*args 与 **kwargs）的注解规则

在为可变位置参数 *args 和可变关键字参数 **kwargs 编写注解时，星号直接紧贴参数名，其后跟随冒号与类型：

def calculate_sum(*numbers: float) -> float:
    return sum(numbers)

def log_attributes(**metadata: str) -> None:
    for key, value in metadata.items():
        print(f"{key}: {value}")

这里的关键规范在于：注解所表达的是容器内单个元素的类型，而不是容器类型本身。在 *numbers: float 中，虽然函数内部接收到的 numbers 是一个元组，但注解应写为每个元素的类型 float，切勿写成 *numbers: tuple[float, ...]。同理，**metadata: str 标注的是字典值的类型 str，而不是字典类型 dict。

图 2：参数与返回值类型注解书写判定推导流程

三、关键认知：类型注解在静态检查与运行时的关键差异

为了在实际项目中正确运用类型注解，必须理解它在不同执行阶段中的表现差异。我们可以通过一个相同的函数与传参场景来观察这一机制。

一致条件下的行为对比

设想我们定义了如下计算函数，并在后续代码中错误地将字符串当成整数传入：

def scale_value(val: int, factor: int) -> int:
    return val * factor

# 错误调用：第一参数传入了 str 而非 int
result = scale_value("A", 3)

为什么这一差异至关重要？ Python 是一门动态类型语言，PEP 484 设立类型注解的初衷是提供“渐进式类型支持（Gradual Typing）”，而非将 Python 强制转变为静态语言。Python 解释器在执行字节码时对参数注解完全视而不见，因此类型注解的性能开销几乎为零。

图 3：同一测试代码在静态检查与运行时环境的双轨机制对比

四、现代 Python 中的复合与联合类型符号写法

从 Python 3.9 和 Python 3.10 开始，类型注解的符号表达得到了显著精简，不再强制要求从标准库 typing 中导入大量大写容器类型。

1. 原生集合类型直接注解（Python 3.9+）

现代 Python 支持直接使用内置类型（小写）进行泛型注解：

• 列表：使用 list[str]，替代旧式的 from typing import List; List[str]。
• 字典：使用 dict[str, int]，替代旧式的 Dict[str, int]。
• 集合：使用 set[int]，替代旧式的 Set[int]。
• 元组：定长元组写为 tuple[int, str]，不定长同类型元组写为 tuple[int, ...]。

2. 联合类型管道符（Python 3.10+）

在表达“可以是类型 A 也可以是类型 B”时，直接使用管道符号 | 拼接，符号两边各空一格：

# 表示可以传入整数或浮点数，返回值可能是浮点数也可能是 None
def parse_ratio(raw_val: int | float, allow_zero: bool = True) -> float | None:
    if raw_val == 0 and not allow_zero:
        return None
    return float(raw_val)

在旧版本中，这通常需要使用 Union[int, float] 和 Optional[float]。使用管道符 | 更加直观简练。需要注意，当参数默认值为 None 时，其类型注解必须显式包含 | None（例如 config: dict[str, str] | None = None），而不能仅写 config: dict[str, str] = None，后者在开启严格模式的静态类型检查器中会被判定为类型不匹配。

五、常见书写错误与排查清单

在日常编写过程中，容易由于手误或对符号语法理解不清而导致语法报错或检查告警。以下是几类典型错误及其纠正方式：

图 4：Python 函数类型注解规范排查与速查清单

1. 返回值箭头放错位置或漏掉末尾冒号：
   错误写法：def process(): -> int 或 def process() -> int
   正确规范：def process() -> int:。箭头必须在括号外、冒号前，函数定义最终必须以半角冒号结束。
2. 默认值赋值与类型顺序颠倒：
   错误写法：def run(limit = 10: int):
   正确规范：def run(limit: int = 10):。必须先通过冒号标明类型，再通过等号赋予默认值。
3. 带注解时等号缺少空格：
   错误写法：def search(keyword: str, max_results: int=20):
   正确规范：def search(keyword: str, max_results: int = 20):。遵从 PEP 8 规则，有类型注解时等号两边保留空格。
4. 无返回值函数遗漏返回注解：
   不推荐：def save_to_db(data: dict): pass
   标准规范：def save_to_db(data: dict[str, Any]) -> None: pass。显式声明 -> None 有助于静态检查器捕捉函数内意外的 return 语句。

总结

规范的函数类型注解能够让 Python 代码既保持动态语言的简洁优雅，又拥有工业级项目的严谨与可维护性。在书写时，只要牢记：参数冒号紧跟变量名、注解默认值等号双侧空格、返回值箭头位于括号与尾部冒号之间，并善用现代 Python 的 | 与内置泛型，就能写出结构清晰、符合 PEP 8 工业级规范的高质量代码。