Python 中如何用 typing.overload 定义多个函数签名

`typing.overload` 是 Python 中专为静态类型检查设计的声明机制，它不改变运行时行为，而是通过在函数定义前添加多个无实现的 `@overload` 存根，向 mypy、PyCharm 等工具精准提示不同参数组合所对应的输入输出类型；实际逻辑仍需在唯一的真实函数体中手动用 `isinstance` 等方式分发处理，且所有重载声明必须按“从具体到宽泛”排序、紧贴函数名、不可与 `@lru_cache` 等装饰器共存——掌握它，就能让 IDE 补全更智能、类型错误更早暴露，真正实现“写时即知型”，大幅提升大型项目类型安全性和开发体验。

typing.overload 不是用于运行时重载，而是为类型检查器（如 mypy、PyCharm、VS Code 的 Pylance）提供多签名提示，让静态类型检查更精确。函数体本身仍只有一个实现，需手动处理不同参数组合的逻辑。

基本用法：声明多个 @overload 装饰的存根

必须把所有 @overload 声明放在最前面，且**不能有函数体**（只写 ... 或 pass），最后跟一个**未装饰的实际实现**（带完整逻辑）。

例如，定义一个根据输入类型返回不同结果的 parse 函数：

from typing import overload, Union, List, Optional

@overload
def parse(value: str) -> int: ...

@overload
def parse(value: List[str]) -> List[int]: ...

@overload
def parse(value: None) -> None: ...

def parse(value: Union[str, List[str], None]) -> Union[int, List[int], None]:
    if isinstance(value, str):
        return int(value)
    elif isinstance(value, list):
        return [int(x) for x in value]
    else:
        return None

类型检查器会根据调用时传入的参数类型，从上面的 @overload 中匹配最合适的签名，从而推断出返回类型。

关键规则：顺序、实现与类型检查协同

• @overload 函数必须严格按参数类型“从具体到宽泛”排列（比如 str 在前，Union[str, int] 在后），否则 mypy 可能匹配错误签名
• 实际实现函数**不能加 @overload**，且其签名必须能兼容所有重载声明（通常是用联合类型或 Any）
• 运行时不会触发任何分发逻辑——所有类型分支靠 isinstance、type() 等手动判断
• IDE 和 mypy 只看 @overload 声明做推导，不执行实现体；所以即使实现体写错，类型检查也可能通过（但运行时报错）

常见场景：可选参数 + 不同返回类型

比如一个读取配置的函数，支持传 key 返回值，或不传 key 返回整个 dict：

from typing import overload, Dict, Any, Optional

@overload
def config(key: str) -> Any: ...

@overload
def config(key: None = None) -> Dict[str, Any]: ...

def config(key: Optional[str] = None) -> Union[Any, Dict[str, Any]]:
    data = {"host": "localhost", "port": 8000}
    if key is None:
        return data
    return data.get(key)

调用 config("host") 时，类型检查器知道返回 Any；调用 config() 时，知道返回 Dict[str, Any]，补全和类型推导更准。

注意点：不是运行时多态，也不支持装饰器叠加

• 不能对同一个函数同时用 @overload 和 @lru_cache 等装饰器（@overload 必须紧贴函数名）
• 不支持基于返回类型重载（只看参数）
• 如果参数类型有重叠（如两个都接受 int），mypy 会选择第一个匹配项，容易误判——应避免歧义签名
• 纯运行时动态分发建议用 functools.singledispatch，它和 @overload 解决的是不同问题

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~