Mypy在泛型中对S1 | F1这类含未约束TypeVar的联合类型无法正确推断具体类型，导致误报Never；根本原因在于TypeVar缺乏区分依据，需通过bound、Protocol或Result模式明确语义边界。
mypy在泛型中对`s1 | f1`这类含未约束typevar的联合类型无法正确推断具体类型，导致误报`never`；根本原因在于typevar缺乏区分依据，需通过bound、protocol或result模式明确语义边界。
在使用mypy进行静态类型检查时，当你定义一个泛型类（如Node[I, S1, F1]）并期望其类型参数S1和F1分别对应成功与失败类型时，若仅声明Callable[[I], S1 | F1]，mypy会因类型变量无约束且可交换而陷入歧义：它无法确定Succ1 | Fail1应如何拆分到两个独立的TypeVar上——S1该是Succ1？Fail1？还是二者之一？这种不确定性导致类型推断失败，最终回退为Never（表示“不可能类型”），并报错Expected Callable[[str], Never]。
问题本质：Union不具备类型变量定向性
S1 | F1在语法上等价于F1 | S1，但泛型系统需要唯一、确定的赋值路径。当func1返回Succ1 | Fail1时，mypy无法自动将Succ1绑定给S1、Fail1绑定给F1——因为S1和F1均未声明任何约束（bound），它们在逻辑上完全对称，没有“成功”或“失败”的语义标识。
from typing import Generic, TypeVar, Callable, Protocol, Literal, reveal_type
# ✅ 正确做法：用 Protocol 定义语义边界
class SuccBase(Protocol):
success: Literal[True]
class FailBase(Protocol):
success: Literal[False]
S1 = TypeVar('S1', bound=SuccBase) # S1 必须满足 success=True
F1 = TypeVar('F1', bound=FailBase) # F1 必须满足 success=False
I = TypeVar('I')
class Node(Generic[I, S1, F1]):
def __init__(self, callback: Callable[[I], S1 | F1]):
self.callback: Callable[[I], S1 | F1] = callback
class Succ1(SuccBase):
success: Literal[True] = True
class Fail1(FailBase):
success: Literal[False] = False
def func1(_: str) -> Succ1 | Fail1:
return Succ1()
n1 = Node(func1) # ✅ mypy 现在能正确推断：Node[str, Succ1, Fail1]
reveal_type(n1) # → isolated_example2.Node[builtins.str, isolated_example2.Succ1, isolated_example2.Fail1]
? 关键点：bound=不仅限定了类型范围，更向类型检查器提供了区分逻辑——Succ1因满足SuccBase协议而只能归属S1，Fail1同理归属F1，消除了联合类型的歧义。
替代方案对比
| 方案 | 实现方式 | 优点 | 注意事项 |
|---|---|---|---|
| Protocol + bound | 如上例，用Literal字段标记语义 | 类型安全、零运行时代价、mypy/Pyright均支持 | 需显式继承协议（mypy要求严格） |
| ABC基类继承 | class Success: pass; class Failure: pass; S1 = TypeVar('S1', bound=Success) | 语义清晰，兼容旧版Python | 运行时有轻微开销，需定义基类 |
| Result封装类型 | 使用Result[Ok, Err]（如rustedpy/result） | 消除歧义、强制错误处理、API更健壮 | 需引入第三方或自定义类型，函数签名变更 |
最佳实践建议
- 避免裸联合类型泛型参数：S1 | F1作为泛型边界本身即设计信号——考虑是否应重构为Result[S1, F1]。
- 始终为TypeVar指定bound=：即使是最简bound=object也能防止Never回退，提升可读性。
- 显式类型注解优先：对关键实例变量（如n1: Node[str, Succ1, Fail1]）添加注解，绕过推断瓶颈。
- 善用reveal_type()定位问题：它是调试泛型推断最直接的工具。
最后，请记住：类型系统不是魔法，而是契约。当你让S1和F1承担不同职责时，就必须用代码明确定义它们的职责边界——否则，mypy只能选择沉默（Never）或报错，而这恰恰是在提醒你：设计需要更精确的语义表达。
