通过 @overload 为不同调用签名（无参、仅 *args、仅 **kwargs）分别声明类型，可使类型检查器（如 mypy）准确推断返回值类型，避免 Union 模糊类型。
通过 `@overload` 为不同调用签名（无参、仅 `*args`、仅 `**kwargs`）分别声明类型，可使类型检查器（如 mypy）准确推断返回值类型，避免 `union` 模糊类型。
在 Python 类型提示中，当函数支持多种调用方式（如不传参、只传位置参数、只传关键字参数）且每种方式对应不同返回类型时，单纯依赖运行时逻辑（如 if args:）无法让静态类型检查器（如 mypy 或 IDE 的类型推导）精确识别各分支的返回类型。此时必须借助 @overload 装饰器显式声明多个独立的、互斥的调用签名，从而引导类型检查器进行精准匹配。
以下是一个完整、可验证的解决方案：
from typing import Union, overload, Tuple
@overload
def test() -> Tuple[int]: # 无参数：返回 tuple[int]
...
@overload
def test(*args: int) -> int: # 至少一个 int 位置参数：返回 int
...
@overload
def test(**kwargs: str) -> str: # 至少一个 str 关键字参数：返回 str
...
def test(*args: int, **kwargs: str) -> Union[int, str, Tuple[int]]:
if args:
return 5
if kwargs:
return "5"
return (5,)✅ 关键要点说明：
- 每个 @overload 声明必须是纯协议签名（无函数体，仅 ...），且按特异性从高到低排列（mypy 会按顺序匹配首个兼容签名）；
- 实际实现函数（最后一个未装饰的 def test(...)）不参与类型检查，仅提供运行时逻辑，其签名需兼容所有 overload；
- *args: int 和 **kwargs: str 在实现中保留，确保运行时行为一致，但 overload 中应避免混用 *args 和 **kwargs 同时出现的签名（否则易触发 overload-overlap 报错）；
- 如需抑制 mypy 对重载重叠的警告（例如 @overload 签名在逻辑上可能被同时满足），可添加 # type: ignore[overload-overlap] 注释（如 test() 和 test(*args) 在空 args 时存在理论重叠，但语义上互斥，可安全忽略）。
调用示例与类型推导效果：
k = test(1) # reveal_type(k) → "builtins.int" j = test(i="1") # reveal_type(j) → "builtins.str" i = test() # reveal_type(i) → "tuple[builtins.int]"
⚠️ 注意事项：
- 不支持 *args 与 **kwargs 同时非空的混合调用（本例未定义该情形）；若需支持，应额外增加对应 overload（如 @overload def test(*args: int, **kwargs: str) -> ...），并明确其返回类型；
- IDE（如 PyCharm、VS Code + Pylance）和 mypy 均能正确解析此类重载，但需确保启用严格模式（如 --strict）以获得最佳提示；
- Tuple[int] 推荐使用 tuple[int]（Python 3.9+），若需兼容旧版本，请导入 from typing import Tuple 并使用 Tuple[int]。
综上，合理设计 overload 签名是解决多态调用下类型精度问题的核心手段——它不改变运行时行为，却显著提升类型安全性与开发体验。
