如何实现Python函数的类型注解提示_使用typing模块标注参数与返回值

你写 Python 函数的时候，有没有遇到过这种情况：代码跑起来没问题，但过两周回头看，完全忘了参数该传什么类型，返回值是字符串还是列表？或者在团队协作时，别人调你的函数，传了个 int 进来，结果里面全是字符串操作，一运行就报错？

类型注解就是来解决这个问题的。它不是运行时强制检查的机制——Python 的动态类型特性不会因此改变——而是给 IDE、mypy、VS Code 这些工具看的。加上注解，它们就能在你写代码的时候就发现参数传错、返回值误用这类问题。不加注解，str 和 int 混传可能到运行才报错；加了，写代码时就标红提醒，效率提升不是一点半点。

怎么给普通函数写基础类型注解

语法其实很简单：参数名后面加 : 类型，函数末尾用 -> 返回类型。Python 3.5+ 原生支持，不需要额外安装库（不过 typing 模块在复杂场景下还是得导入）。

这里有个常见的坑：有人会把字符串字面量当成类型写，比如 def f(x: "int") -> "str"。这玩意儿静态检查工具根本不认。必须用真实类型，或者用 from __future__ import annotations（Python 3.7+ 推荐）来做延迟求值。

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

• name: str 表示只接受 str 实例，传 None 或 list 会被 mypy 标出来
• -> str 意味着调用方可以安全地把它当作 str 使用，比如直接调用 .upper()
• 如果函数可能返回 None，必须显式写成 -> str | None（Python 3.10+）或 -> Optional[str]（旧版本）

处理可选值、联合类型和空值

现实中的函数，经常会出现“可能没结果”的情况——查字典、读配置、API 调用失败，都是家常便饭。不能默认假设返回非空，否则 AttributeError 会在你意想不到的地方冒出来。

Python 3.10+ 推荐用 | 操作符；旧版本则必须从 typing 导入 Optional、Union。

from typing import Optional, Union

def find_user(user_id: int) -> Optional[str]:  # 等价于 str | None
    return "alice" if user_id == 1 else None

def parse_input(data: str) -> Union[int, float, bool]:  # Py3.10+ 可写为 int | float | bool
    if data.isdigit():
        return int(data)
    elif "." in data:
        return float(data)
    else:
        return data.lower() == "true"

• Optional[T] 就是 Union[T, None] 的简写，别手写 Union[str, None]
• 尽量避免用 Any——它等于放弃了类型检查，IDE 提示会全部失效
• Union 成员超过 3 个时，考虑封装成 TypedDict 或 NewType，可读性会好很多

标注容器类型（list/dict/Callable）要带泛型参数

只写 list 或 dict 基本等于没写——它们等价于 list[Any] 和 dict[Any, Any]，起不到任何约束作用。必须说明里面装的是什么类型。

这里有个容易踩的坑：用 list 当类型提示，结果传了个 tuple 也能通过。因为 tuple 不是 list 的子类，但类型检查器看到裸 list 时，根本懒得校验具体内容。

from typing import List, Dict, Callable, Tuple

def process_users(users: List[str]) -> Dict[str, int]:
    return {u: len(u) for u in users}

def apply_func(fn: Callable[[int, str], bool], x: int, y: str) -> bool:
    return fn(x, y)

def get_coords() -> Tuple[float, float, float]:
    return (1.0, 2.0, 3.0)

• List[str] 表示“元素全是 str 的列表”，传 [1, "a"] 会被 mypy 拒绝
• Dict[str, int] 要求 key 是 str、value 是 int，{"a": "1"} 不合法
• Callable[[int, str], bool] 这个语法是固定的：外层方括号是函数签名，内层方括号是参数类型列表

为什么有时候写了注解 IDE 还不提示？

最可能的原因就是没启用类型检查工具，或者 Python 解释器路径、环境没配对。VS Code 默认只靠语言服务器（Pylance）做轻量推断，不依赖注解。想让注解真正起作用，得配合 mypy，或者开启 Pylance 的 typeCheckingMode: basic。

• 确认已安装 mypy：pip install mypy，然后在命令行跑 mypy your_script.py
• VS Code 里检查设置是否启用了 "python.typeChecking.enabled": true
• 如果用了 from __future__ import annotations，确保项目 Python 版本 ≥ 3.7，且 mypy 配置中 python_version = "3.7" 或更高
• 第三方库没加注解？可以安装 types-xxx 包（比如 types-requests），或者用 # type: ignore 临时跳过（不太建议长期用）

类型注解本身不改变代码的运行行为，但它把隐含的契约显性化了。这里最关键的一点是：函数边界处的类型声明，比函数内部怎么实现要重要得多——哪怕 body 里全是 pass，只要签名清晰，调用方就能安全使用。