如何在Python中通过typing.overload定义函数的重载签名？-Python教程-PHP中文网

typing.overload仅用于类型检查，不参与运行时；必须在所有@overload声明后提供唯一未装饰的实现函数，其签名需宽泛且返回类型兼容各重载声明，运行时完全忽略重载逻辑。

如何在python中通过typing.overload定义函数的重载签名？

typing.overload 只是声明，不是实现

typing.overload 本身不执行任何运行时逻辑，它只是告诉类型检查器（如 mypy、PyCharm、VS Code 的 Pylance）：这个函数有多个合法的调用方式。真正被调用的，永远是下面那个**未加装饰器的函数体**。

常见错误是写完几个 @overload 就以为重载完成了，结果运行时报 TypeError: multiple overloads defined 或者类型检查器完全没报错但实际调用出错——因为漏掉了非装饰的实现函数。

必须在所有 @overload 声明之后，提供且仅提供一个**没有 @overload 装饰的函数定义**
这个实现函数的签名通常要足够宽泛（比如参数用 Union 或 Any），否则类型检查器可能无法匹配到它
运行时不会校验你写的 @overload 是否覆盖了所有情况；它只校验「调用是否匹配任一声明 + 实现是否能跑通」

参数类型冲突时，mypy 会拒绝调用

当你写了两个 @overload，而它们的参数类型存在交集（比如都接受 str），mypy 会报 Overloaded function signatures cannot overlap。

例如下面这段会失败：

@overload
def process(x: str) -> int: ...
@overload
def process(x: object) -> str: ...  # ❌ 与上一条重叠：str 是 object 的子类
def process(x): ...

解决办法是调整顺序或细化类型：

把更具体的签名放前面（str 在 object 前）
避免用太宽泛的类型如 object、Any 做 overload 参数，改用 Union[str, int] 等显式枚举
必要时用 Literal 区分字符串字面量分支，比如 mode: Literal["json", "xml"]

返回类型必须与实现函数兼容

每个 @overload 声明的返回类型，必须能被底层实现函数的返回值“安全地”赋值。如果实现函数返回 int，但某个 @overload 声明返回 str，mypy 就会报错。

python全能编程助手

SkillSub Pro - Python 题解与代码注释双功能技能功能概述SkillSub Pro - Python 题解与代码注释双功能技能是一项面向实际任务的技能，主要用于SkillSub Pro 是一个 Python 题解生成与代码注释的双功能合体技能，专为学生、算法学习者和开发者设计；✅ 一个技能，两种用途：；核心要点📝 题解模式：输入题目/题号，自动生成完整 Python 题解（含详细注释、解题思路、复杂度分析）；💬 注释模式：输入 Python 代码，自动添加详细中。它将相关步骤、

下载

典型反例：

@overload
def fetch(key: str) -> str: ...
@overload
def fetch(key: int) -> bytes: ...
def fetch(key):  # ✅ 实现里必须能同时返回 str 和 bytes
    if isinstance(key, str):
        return "ok"
    else:
        return b"ok"

注意点：