为何mypy不检查重载函数实现？如何实现全签名检查？

一、mypy不直接检查重载签名与实现一致性的原因 #

mypy对重载函数的检查逻辑是：只验证对外暴露的重载签名是否符合类型规范，而不对实现体和每个重载签名做逐一绑定检查。核心原因有两点：

1. 重载是对外的接口契约，实现体是一个统一的逻辑集合，mypy无法自动将实现的代码分支与每个重载签名一一对应，这涉及复杂的分支路径分析，目前类型检查器难以做到精准匹配。
2. 如果强制要求实现注解完全覆盖所有重载的输入输出组合，会导致注解过于宽泛（比如x: str|int, y: str|int），但这种宽泛注解无法体现重载中“特定输入组合对应特定输出”的关联关系——重载承诺了int+str一定返回str，而宽泛注解只表示输入是两种类型的组合、输出是两种类型之一，mypy会认为这种实现注解与重载签名的约束不匹配，因此报错。

二、让mypy检查重载函数实现的解决方案 #

方案1：给实现添加精确的联合注解，结合类型窄化验证分支 #

给实现函数添加覆盖所有合法输入输出的联合注解，再通过isinstance等类型窄化手段，让mypy能跟踪每个分支的类型，从而检查代码是否符合重载的约束。

修改后的代码如下：

from typing import overload, Union

@overload
def foo(x: int, y: str) -> str: ...

@overload
def foo(x: str, y: int) -> str: ...

@overload
def foo(x: str, y: str) -> int: ...

def foo(x: Union[int, str], y: Union[int, str]) -> Union[str, int]:
    if isinstance(x, int):
        # 通过重载约束，此时y必须是str，若实现中错误地用y做数值运算，mypy会报错
        return str(x - 2) + y
    if isinstance(y, int):
        # 同理，此时x必须是str
        return str(y - 2) + x
    # 此时x和y均为str，若返回值不是int，mypy会报错
    return int(x + y)

此时如果实现中存在错误（比如在第一个分支里写return x + y，即int + str），mypy会直接检测到类型不兼容的问题。

方案2：用TypeVar关联输入输出的类型关系（更严谨的方式） #

如果希望更清晰地表达输入输出的类型关联，可以使用带约束的TypeVar，结合重载实现更严谨的类型检查：

from typing import overload, TypeVar

T = TypeVar('T', int, str)
U = TypeVar('U', int, str)

@overload
def foo(x: int, y: str) -> str: ...

@overload
def foo(x: str, y: int) -> str: ...

@overload
def foo(x: str, y: str) -> int: ...

def foo(x: T, y: U) -> Union[str, int]:
    if isinstance(x, int):
        assert isinstance(y, str), "Invalid type combination for overload"
        return str(x - 2) + y
    if isinstance(y, int):
        assert isinstance(x, str), "Invalid type combination for overload"
        return str(y - 2) + x
    assert isinstance(x, str) and isinstance(y, str), "Invalid type combination for overload"
    return int(x + y)

这里的assert语句不仅能在运行时保证类型安全，还能帮助mypy进一步窄化类型，确保每个分支的代码符合重载的约束。

补充说明 #

需要注意的是，重载函数的实现必须处理所有重载签名覆盖的输入组合，不能出现重载中未定义的输入（比如int+int），否则不仅运行时会出错，mypy也会通过类型检查提示问题。

内容的提问来源于stack exchange，提问作者FooBar