# 为什么 Python 阻止我把雪碧倒进可乐罐


你是否遇到过这样的时刻：代码看起来完美无缺，但 Python 的类型检查器（mypy）却固执地报错？我的第一反应总是：“这肯定是检查器搞错了！”

最近，我在开发一款饮料管理应用时，就遇到了这种情况。mypy 抛出了这样一个令人困惑的错误：

```console
error: Argument 1 to "party_drinks" has incompatible type "TinCan[Coke]"; expected "TinCan[Soda]"
```

起初我想：“可乐 *本来* 就是汽水啊！为什么在需要汽水罐的地方不能用可乐罐？”

事实证明，mypy 正在保护我，避免一个我没预料到的运行时灾难。

## “雪碧倒进可乐罐”的灾难

为了理解 mypy 阻止了什么，想象这样一个现实场景：

你有一个明确标着“可乐”的罐子。你把它递给派对上的某人，对方很自然地往里面倒了雪碧（毕竟雪碧也是汽水，对吧？）。后来你自信地拿起罐子，期待熟悉的可乐味，结果——*惊喜*——你喝到的是柠檬味。你的预期被彻底打破！

这正是 Python 类型系统在代码中帮你避免的灾难。

对应到 Python 代码是这样的：

```python
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]` 吗？”

答案是**不是**，原因如下：

1. `TinCan[Soda]` 承诺它的 `fill` 方法能接受*任何*汽水
2. `TinCan[Coke]` 只承诺能接受可乐
3. 如果我们把 `TinCan[Coke]` 当作 `TinCan[Soda]`，就违背了第2条承诺

这种泛型类型之间的关系叫做**型变（variance）**，理解它对于类型安全至关重要。

## 容器的秘密生活：型变详解

关键在于容器的可替换性取决于它是**只读**、**只写**还是**可读可写**。Python 对这些模式有明确的分类：

### 🥤 协变容器：只读（从具体到一般是安全的）

想象一个密封罐——你只能喝，不能灌装：

```python
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]` 都是协变的
- 函数的返回值类型是协变的

### 🪣 逆变容器：只写（从一般到具体是安全的）

再想象一个只能丢东西进去、不能取出来的垃圾桶：

```python
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`），它就是**不变的**：

```python
# 这两种替换都不安全：
# ❌ 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 实现只读访问

```python
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)  # ✅ 安全！
```

### 方案二：明确类型

```python
def party_drinks_coke_only(can: TinCan[Coke]):
    """专门处理可乐罐的函数"""
    print(f"Drinking {type(can.drink()).__name__}")
    can.fill(Coke())  # 只灌可乐！
```

### 方案三：用 Union 类型增加灵活性

```python
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 可以安全替换

```python
def process_sodas(sodas: list[Soda]):
    sodas.append(Sprite())  # 这就是 list 不变的原因！

cokes: list[Coke] = [Coke(), Coke()]
# process_sodas(cokes)  # ❌ mypy 阻止了这一步
```

**修正：** 用 `Sequence` 做只读访问：

```python
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)  # ✅ 没问题！
```

### 陷阱二：型变声明与实际用法不符

```python
# ❌ 错误：声明协变但有 setter
T_co = TypeVar("T_co", covariant=True)

class BrokenContainer(Generic[T_co]):
    def set_item(self, item: T_co) -> None:  # mypy 报错！
        pass
```

**修正：** 型变声明要与实际用法一致。

## 我的顿悟时刻

“雪碧倒进可乐罐”的经历彻底改变了我对类型安全的看法。现在我不再和 mypy 的严格较劲，而是把它当作防止微妙运行时灾难的好朋友。

每当遇到型变相关的报错，我都会问自己：

1. **这个容器支持哪些操作？**
   - 只读 → 用协变
   - 只写 → 用逆变
   - 可读可写 → 保持不变

2. **我想做哪种替换？**
   - 具体 → 一般？需要协变
   - 一般 → 具体？需要逆变
   - 两种都想要？不变类型不支持

3. **能否重构避免问题？**
   - 拆分读写接口
   - 用 Protocol 增加灵活性
   - 明确类型

## Python 标准库中的型变

理解型变有助于正确使用 Python 内置类型：

```python
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 对你“完美无瑕”的代码提出异议时查阅。*