本文介绍在使用带不变量泛型的 protocol 时，因 `union` 返回类型引发 `process_sample` 参数类型不匹配的问题，并提供基于 `@overload` 的精准类型推导方案，无需重构架构即可让 mypy 正确推断同一 exporter 实例中 `get_sample()` 与 `process_sample()` 的类型一致性。
在 Python 类型系统中，当协议（Protocol）使用不变量（invariant）泛型类型参数（如 MyExporter[T] 中的 T），其子类型关系严格受限：MyExporter[SampleA] 和 MyExporter[SampleB] 互不兼容，二者并集 Union[MyExporter[SampleA], MyExporter[SampleB]] 无法被静态类型检查器（如 mypy）用于安全地调用泛型方法——尤其当方法参数依赖于同一 T 时。
例如，以下代码会触发 mypy 报错：
exporter = get_exporter("a") # 类型为 Union[MyExporter[SampleA], MyExporter[SampleB]]
sample = exporter.get_sample() # 推断为 SampleA | SampleB（即 Union[SampleA, SampleB]）
exporter.process_sample(sample) # ❌ 错误：期望 SampleA 或 SampleB，但得到 Union根本原因在于：mypy 将 exporter 视为“两种可能类型的并集”，而 get_sample() 和 process_sample() 的类型签名分别被独立解析，缺乏跨方法的上下文关联性（即“同一个 exporter 实例”这一运行时事实无法被类型系统捕获）。
✅ 推荐方案：使用 @overload 实现精确重载签名
通过 @overload 显式声明不同字面量输入对应的精确返回类型，可引导类型检查器为每次调用绑定唯一、确定的泛型实例：
调用 Cutout.Pro 视觉处理 API 进行背景移除、人像抠图和照片增强，支持文件上传与图片 URL 输入。
from typing import Protocol, overload, TypeVar, cast, Union
from typing_extensions import Literal
class BaseSample: ...
class SampleA(BaseSample): ...
class SampleB(BaseSample): ...
T = TypeVar("T", bound=BaseSample)
class MyExporter(Protocol[T]):
def get_sample(self) -> T: ...
def process_sample(self, sample: T) -> str: ...
# 模拟具体实现（仅用于类型验证）
my_exporter_a = cast(MyExporter[SampleA], object())
my_exporter_b = cast(MyExporter[SampleB], object())
@overload
def get_exporter(name: Literal["a"]) -> MyExporter[SampleA]: ...
@overload
def get_exporter(name: Literal["b"]) -> MyExporter[SampleB]: ...
def get_exporter(name: str) -> Union[MyExporter[SampleA], MyExporter[SampleB]]:
if name == "a":
return my_exporter_a
return my_exporter_b
# ✅ 类型检查通过
exporter_a = get_exporter("a") # 类型：MyExporter[SampleA]
sample_a = exporter_a.get_sample() # 类型：SampleA
output_a = exporter_a.process_sample(sample_a) # ✅ OK
exporter_b = get_exporter("b") # 类型：MyExporter[SampleB]
sample_b = exporter_b.get_sample() # 类型：SampleB
output_b = exporter_b.process_sample(sample_b) # ✅ OK? 提示：Literal["a"] 确保编译期字面量推导；@overload 装饰器本身不执行逻辑，仅提供类型契约；实际函数体需覆盖所有重载分支（此处用 str 作为宽泛类型兜底）。
? 替代思路（适用场景有限）
统一泛型上界：若业务允许将 exporter 泛型设为 MyExporter[Union[SampleA, SampleB]]，则 get_sample() 返回 SampleA | SampleB，process_sample 也能接受该联合类型。但此方式牺牲了类型精度（无法区分 A/B 特有字段），且要求 process_sample 实际能处理两种样本，通常不推荐。
-
运行时类型守卫：对 sample 使用 isinstance 或 TypeGuard 进行窄化，再分路径调用：
sample = exporter.get_sample() if isinstance(sample, SampleA): exporter.process_sample(sample) # mypy 推断 exporter 为 MyExporter[SampleA]⚠️ 注意：这要求 exporter 本身也需被窄化（如 assert isinstance(exporter, MyExporter[SampleA])），否则类型守卫仅作用于 sample，exporter 仍为 Union，无法保证方法调用安全。
✅ 总结
| 方案 | 类型精度 | 实现成本 | 推荐度 |
|---|---|---|---|
| @overload + Literal | ⭐⭐⭐⭐⭐（完全保留泛型特异性） | 低（仅增几行类型声明） | ✅ 强烈推荐 |
| 统一 Union[T] 泛型 | ⭐⭐（丢失子类型信息） | 极低 | ⚠️ 仅限简单聚合场景 |
| isinstance/TypeGuard | ⭐⭐⭐⭐（需配合 exporter 窄化） | 中（需额外判断逻辑） | ⚠️ 适合动态分支复杂场景 |
最终，@overload 是最符合 Python 类型哲学的解法：它不改变运行时行为，仅向类型检查器注入更丰富的契约信息，在零架构改动前提下，彻底解决泛型协议联合返回导致的类型不一致问题。
