你是否遇到过这样的时刻：代码看起来完美无缺，但 Python 的类型检查器（mypy）却固执地报错？我的第一反应总是：“这肯定是检查器搞错了！”
最近，我在开发一款饮料管理应用时，就遇到了这种情况。mypy 抛出了这样一个令人困惑的错误：
1
|
error: Argument 1 to "party_drinks" has incompatible type "TinCan[Coke]"; expected "TinCan[Soda]"
|
起初我想：“可乐 本来 就是汽水啊！为什么在需要汽水罐的地方不能用可乐罐？”
事实证明，mypy 正在保护我，避免一个我没预料到的运行时灾难。
“雪碧倒进可乐罐”的灾难
为了理解 mypy 阻止了什么，想象这样一个现实场景：
你有一个明确标着“可乐”的罐子。你把它递给派对上的某人，对方很自然地往里面倒了雪碧（毕竟雪碧也是汽水，对吧？）。后来你自信地拿起罐子，期待熟悉的可乐味，结果——惊喜——你喝到的是柠檬味。你的预期被彻底打破！
这正是 Python 类型系统在代码中帮你避免的灾难。
对应到 Python 代码是这样的：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
|
from typing import TypeVar, Generic
class Soda:
"""所有汽水的基类"""
pass
class Coke(Soda):
"""可口可乐：期望有焦糖色和可乐味"""
pass
class Sprite(Soda):
"""雪碧：无色，柠檬味"""
pass
T = TypeVar("T")
class TinCan(Generic[T]):
"""可以装特定类型汽水的罐子"""
def __init__(self, contents: T):
self.contents = contents
def drink(self) -> T:
"""从罐子里喝汽水"""
return self.contents
def fill(self, new_soda: T) -> None:
"""用新的汽水替换内容物"""
self.contents = new_soda
def party_drinks(can: TinCan[Soda]):
"""接收任意汽水罐，并可能重新灌装"""
print(f"Drinking {type(can.drink()).__name__}")
can.fill(Sprite()) # 对于汽水罐来说，灌雪碧很合理！
# 问题出在这里：
coke_can = TinCan[Coke](Coke()) # 这是一个只装可乐的罐子
party_drinks(coke_can) # 🚨 mypy 阻止了这一步！
# 如果允许这样做，下一行在运行时就会出错：
# coke: Coke = coke_can.drink() # 期望得到可乐，结果却是雪碧！
|
mypy 阻止了这种用法，因为如果允许替换，你专用的可乐罐就会被雪碧“污染”，违背了类型契约。
为什么 TinCan[Coke] 不能当作 TinCan[Soda] 用？
你可能会想：“既然每个可乐都是汽水，难道不是每个 TinCan[Coke] 都是 TinCan[Soda] 吗？”
答案是不是，原因如下：
TinCan[Soda] 承诺它的 fill 方法能接受任何汽水TinCan[Coke] 只承诺能接受可乐- 如果我们把
TinCan[Coke] 当作 TinCan[Soda]，就违背了第2条承诺
这种泛型类型之间的关系叫做型变（variance），理解它对于类型安全至关重要。
容器的秘密生活：型变详解
关键在于容器的可替换性取决于它是只读、只写还是可读可写。Python 对这些模式有明确的分类：
🥤 协变容器：只读（从具体到一般是安全的）
想象一个密封罐——你只能喝，不能灌装：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
|
from typing import TypeVar, Generic
T_co = TypeVar("T_co", covariant=True)
class SealedCan(Generic[T_co]):
"""只读密封罐，不能重新灌装"""
def __init__(self, contents: T_co):
self._contents = contents
def drink(self) -> T_co:
return self._contents
# 注意：没有 fill() 方法！
def serve_any_soda(can: SealedCan[Soda]):
"""这个函数接收任何密封汽水罐"""
print(f"Serving {type(can.drink()).__name__}")
# 这样是安全的！
sealed_coke = SealedCan[Coke](Coke())
serve_any_soda(sealed_coke) # ✅ 完美运行
# 为什么？因为只能读取，可乐始终是汽水的子类
|
现实例子：
Sequence[T]、Iterable[T]、Iterator[T] 都是协变的- 函数的返回值类型是协变的
🪣 逆变容器：只写（从一般到具体是安全的）
再想象一个只能丢东西进去、不能取出来的垃圾桶：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
T_contra = TypeVar("T_contra", contravariant=True)
class DisposalCan(Generic[T_contra]):
"""只写垃圾桶"""
def dispose(self, item: T_contra) -> None:
print(f"Disposing {type(item).__name__}")
# 注意：无法取出内容！
def dispose_coke(can: DisposalCan[Coke]):
"""这个函数只处理可乐"""
can.dispose(Coke())
# 这样也是安全的！
general_disposal = DisposalCan[Soda]()
dispose_coke(general_disposal) # ✅ 完美运行
# 为什么？能接受任何汽水的垃圾桶当然能处理可乐
|
现实例子：
- 函数参数类型是逆变的
Callable[[T], None] 在参数 T 上是逆变的
⚖️ 不变容器：可读可写（不允许安全替换）
当容器既可读又可写（比如最初的 TinCan），它就是不变的：
1
2
3
|
# 这两种替换都不安全：
# ❌ TinCan[Coke] → TinCan[Soda]（会导致可乐罐被灌雪碧）
# ❌ TinCan[Soda] → TinCan[Coke]（可能取出不是可乐的内容）
|
现实例子：
list[T]、dict[K, V]、set[T] 都是不变的- 大多数可变容器都是不变的
型变速查表：何时用哪种型变
| 型变 |
适用场景 |
类型参数声明 |
示例 |
| 协变 |
只读操作 |
TypeVar("T", covariant=True) |
生产者、getter、迭代器 |
| 逆变 |
只写操作 |
TypeVar("T", contravariant=True) |
消费者、setter、处理器 |
| 不变 |
可读可写操作 |
TypeVar("T") |
可变容器 |
如何修复最初的问题
那么，如何修复我们的派对饮料场景？有三种方法：
方案一：用 Protocol 实现只读访问
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
from typing import Protocol, TypeVar
T_co = TypeVar("T_co", covariant=True)
class DrinkableContainer(Protocol[T_co]):
"""只能喝的容器协议"""
def drink(self) -> T_co: ...
def party_drinks_readonly(can: DrinkableContainer[Soda]):
print(f"Drinking {type(can.drink()).__name__}")
# 不能灌装——协议没有 fill 方法！
# 现在这样就安全了！
coke_can = TinCan[Coke](Coke())
party_drinks_readonly(coke_can) # ✅ 安全！
|
方案二：明确类型
1
2
3
4
|
def party_drinks_coke_only(can: TinCan[Coke]):
"""专门处理可乐罐的函数"""
print(f"Drinking {type(can.drink()).__name__}")
can.fill(Coke()) # 只灌可乐！
|
方案三：用 Union 类型增加灵活性
1
2
3
4
5
6
7
8
|
from typing import Union
def party_drinks_mixed(can: Union[TinCan[Coke], TinCan[Sprite]]):
"""显式处理不同类型汽水罐"""
if isinstance(can.drink(), Coke):
can.fill(Coke())
else:
can.fill(Sprite())
|
常见型变陷阱及规避方法
陷阱一：以为 list 可以安全替换
1
2
3
4
5
|
def process_sodas(sodas: list[Soda]):
sodas.append(Sprite()) # 这就是 list 不变的原因！
cokes: list[Coke] = [Coke(), Coke()]
# process_sodas(cokes) # ❌ mypy 阻止了这一步
|
修正： 用 Sequence 做只读访问：
1
2
3
4
5
6
7
8
|
from typing import Sequence
def process_sodas_readonly(sodas: Sequence[Soda]):
for soda in sodas:
print(type(soda).__name__)
cokes: list[Coke] = [Coke(), Coke()]
process_sodas_readonly(cokes) # ✅ 没问题！
|
陷阱二：型变声明与实际用法不符
1
2
3
4
5
6
|
# ❌ 错误：声明协变但有 setter
T_co = TypeVar("T_co", covariant=True)
class BrokenContainer(Generic[T_co]):
def set_item(self, item: T_co) -> None: # mypy 报错！
pass
|
修正： 型变声明要与实际用法一致。
我的顿悟时刻
“雪碧倒进可乐罐”的经历彻底改变了我对类型安全的看法。现在我不再和 mypy 的严格较劲，而是把它当作防止微妙运行时灾难的好朋友。
每当遇到型变相关的报错，我都会问自己：
-
这个容器支持哪些操作？
- 只读 → 用协变
- 只写 → 用逆变
- 可读可写 → 保持不变
-
我想做哪种替换？
- 具体 → 一般？需要协变
- 一般 → 具体？需要逆变
- 两种都想要？不变类型不支持
-
能否重构避免问题？
- 拆分读写接口
- 用 Protocol 增加灵活性
- 明确类型
Python 标准库中的型变
理解型变有助于正确使用 Python 内置类型：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
from typing import Callable, Iterator, Mapping
# 协变示例（可以用具体类型替代一般类型）
def process_iterator(it: Iterator[Soda]): ...
coke_iterator: Iterator[Coke] = iter([Coke()])
process_iterator(coke_iterator) # ✅ 协变
# 逆变示例（可以用一般类型替代具体类型）
def use_handler(handler: Callable[[Coke], None]): ...
general_handler: Callable[[Soda], None] = lambda s: print(type(s))
use_handler(general_handler) # ✅ 参数逆变
# 不变示例（必须完全匹配）
def modify_list(items: list[Soda]): ...
coke_list: list[Coke] = [Coke()]
# modify_list(coke_list) # ❌ 不变
|
总结
型变看似晦涩，其实是为了防止真实的 bug。“雪碧倒进可乐罐”并非理论问题，而是型变规则能帮你避免的实际运行时错误。
下次 mypy 抱怨型变时：
- 不要和它对抗——理解它在保护你
- 想想你的容器是只读、只写还是可读可写
- 选择合适的型变，或重构你的接口
记住：今天让你头疼的类型错误，就是明天你避免的运行时崩溃。
你遇到过 Python 型变相关的问题吗？你是怎么解决的？欢迎在评论区分享你的故事！
觉得有帮助？欢迎分享给你的团队，或收藏以备下次 mypy 对你“完美无瑕”的代码提出异议时查阅。
