几周前我在翻一个自己维护了大半年的数据处理库，目光停在几个用 `TypeVar` 和 `Generic` 堆起来的泛型基类上。那些代码为了给 `Pipeline` 类增加类型参数，前前后后写了好几行：定义协变类型变量、绑定上下界、然后在基类里小心翼翼地把类型变量传给 `Generic`。功能倒是正常，但每次有新人加入项目，都得先对着那几行类型变量声明解释半天。就在我盘算着要不要写一份团队内部的类型标注规范时，Python 3.13 正式发布了，PEP 695 带来的新式类型参数语法正好戳中这个痛点。
和之前需要用 `TypeVar` 显式声明、再喂给 `Generic` 的方式不同，Python 3.13 允许直接在类、函数或类型别名定义时用更自然的方式声明类型参数，同时还引入了一个全新的 `type` 语句用于声明类型别名。这个改动表面上看是语法糖，但在复杂泛型场景里确实能少写不少模板代码，而且让类型标注的阅读顺序更接近正常的代码逻辑。趁着热乎劲儿，我花了一个下午把那个数据处理管道库全面迁移到了新语法，过程比预想的顺利，但也有一些值得注意的细节。这篇文章就用这个实际的迁移案例，把新旧写法对照着讲一遍。
一、旧写法的痛点：TypeVar 的声明与使用为什么让人疲惫
在 Python 3.12 及之前的版本里，想让一个类支持泛型，标准做法是先用 `TypeVar` 声明一个或多个类型变量，然后在类定义中继承 `Generic[T]`。如果这个类型变量需要协变或逆变，还得指定 `covariant=True` 或 `contravariant=True`。一个简单的可迭代数据源抽象类通常会写成这样：
from typing import TypeVar, Generic, Iterator
T = TypeVar('T')
R = TypeVar('R')
class DataSource(Generic[T]):
def read(self) -> Iterator[T]:
raise NotImplementedError
class Processor(Generic[T, R]):
def process(self, item: T) -> R:
raise NotImplementedError这种写法有三个让人别扭的地方。第一，类型变量的名字要在字符串里再写一遍（比如 `TypeVar(‘T’)`），重复并且容易拼错。第二，如果涉及到协变，声明会更冗长：`T_co = TypeVar(‘T_co’, covariant=True)`，增加了认知负担。第三，当泛型继承链变长时，`Generic[T, R, …]` 的参数列表和类定义本身的业务逻辑混在一起，维护者需要在脑子里把类型参数从语义中剥离出来。
另外，类型别名（type alias）在 3.12 里通常直接用全局变量赋值的方式实现，比如 `Vector = list[float]`，但这种方式对于泛型别名（例如一个可带类型参数的函数签名别名）的支持并不理想，往往需要借助 `typing.TypeAlias` 标注并且写起来有些割裂。
这些不便在只有一个或两个类型变量的小型类上还不算太明显，但像数据处理管道这种需要串联多个泛型步骤的场景，类型变量的数量很容易膨胀到三四个，维护成本就上来了。
二、Python 3.13 的新语法：直接在类定义里声明类型参数
Python 3.13 允许在类名后面的方括号里直接声明类型参数，并且支持直接在声明处指定上界、协变等约束，不再需要先创建 `TypeVar` 对象。上面的例子用新语法重写，变成：
class DataSource[T]:
def read(self) -> Iterator[T]:
raise NotImplementedError
class Processor[T, R]:
def process(self, item: T) -> R:
raise NotImplementedError类型参数 `T` 和 `R` 直接在类名后的方括号里声明，它们的作用域是整个类体。不需要预先定义 `TypeVar`，也不需要继承 `Generic`。使用时依然是 `DataSource[int]` 或 `Processor[str, bytes]`。
如果需要协变或逆变，在类型参数前面加上 `*` 或 `**` 已经不是原来的含义，在 PEP 695 里，变体通过注解语法来设定：
class Source[out T]:
def read(self) -> T:
...
class Sink[in T]:
def write(self, item: T) -> None:
...`out` 表示协变，`in` 表示逆变，不加变体标记则默认不变。这个语法比 `TypeVar(‘T’, covariant=True)` 一眼就能读明白。
类型参数也可以指定上界，例如 `T: (int, float)` 表示 `T` 必须是 `int` 或 `float` 的子类型。声明方式直接在方括号内写 `T: SomeBase`。
class NumericProcessor[T: (int, float)]:
def process(self, value: T) -> T:
return value * 2这种写法让泛型定义回归到了一个相对自然的位置——类型参数紧跟在类名后面，进入类体就可用，阅读时的视线移动比之前来回跳转 `TypeVar` 和 `Generic` 要顺畅很多。
三、函数与类型别名的新语法：type 语句登场
除了类，函数也可以直接在名字后使用方括号声明类型参数：
def first[T](items: list[T]) -> T:
return items[0]调用时 `first([1, 2, 3])` 会自动推断 `T` 为 `int`，也可以显式指定 `first[int]([1, 2, 3])`。
类型别名则通过新增的 `type` 语句来定义，它取代了之前用变量赋值加 `TypeAlias` 标注的方式。语法很直观：
type Point = tuple[float, float]
type Matrix[T] = list[list[T]]`type` 语句定义的别名支持类型参数，并且可以在模块顶层直接使用，不需要从 `typing` 额外导入什么。对比旧写法 `Matrix = TypeAlias` 加函数式声明，新语法明显更符合直觉，也让代码审查时一眼就能区分普通变量赋值和类型别名。
四、完整迁移案例：一个数据处理管道从旧语法到新语法
我维护的那个数据处理管道库，核心抽象包括三个部分：一个数据源 `Source`，产出某种类型的数据；一个或多个变换步骤 `Step`，将输入类型转换为输出类型；以及一个管道 `Pipeline` 将它们串联。迁移之前，这些类大致是这样的（省略了部分实现）：
from typing import TypeVar, Generic, Iterator, Callable
T = TypeVar('T')
R = TypeVar('R')
class Source(Generic[T]):
def __iter__(self) -> Iterator[T]: ...
class Step(Generic[T, R]):
def apply(self, input: T) -> R: ...
class Pipeline(Generic[T, R]):
def __init__(self, source: Source[T], *steps: Step):
self.source = source
self.steps = steps
def run(self) -> Iterator[R]:
for item in self.source:
result: Any = item
for step in self.steps:
result = step.apply(result)
yield result代码逻辑本身不复杂，但类型参数的声明分散在三个类里，每个都需要独立的 `TypeVar`。而且 `Pipeline` 的类型参数 `T` 和 `R` 实际上分别代表“管道输入的原始数据类型”和“最终输出类型”，但中间步骤的类型变化并没有在泛型参数中体现——不过这属于更复杂的类型体操范畴，不是本次重构的重点。
迁移到 Python 3.13 新语法后，去掉所有 `TypeVar` 和 `Generic`，直接在类定义上声明类型参数：
from collections.abc import Iterator, Callable
class Source[T]:
def __iter__(self) -> Iterator[T]:
raise NotImplementedError
class Step[T, R]:
def apply(self, input: T) -> R:
raise NotImplementedError
class Pipeline[T, R]:
def __init__(self, source: Source[T], *steps: Step):
self.source = source
self.steps = steps
def run(self) -> Iterator[R]:
for item in self.source:
result: object = item
for step in self.steps:
result = step.apply(result)
yield result改完后再用 mypy 1.11 检查，所有类型推断正常。`Pipeline` 的构造函数传入 `Source[int]` 和一系列 `Step` 后，返回的 `run` 方法会自动计算出 `R` 的类型。从行数上看，删掉了四行 `TypeVar` 声明和三个 `Generic` 继承，换来的是每个类头部多了一段 `[T, R]`。更重要的是，不再需要跨文件追踪 `T`、`R` 是在哪个模块里定义的，类型参数变成了类定义的一部分，自包含性好了很多。
五、用 type 语句清理模块里的类型别名
原来库里还有几个用作中间表示的类型别名，比如从文件读取的原始行数据是 `list[str]`，转换后的记录是 `dict[str, object]`，旧写法是：
RawLines = list[str]
Record = dict[str, object]虽然也能工作，但在类型检查器看来它们只是普通变量，容易和模块里的全局变量混淆。迁移时改成了：
type RawLines = list[str]
type Record = dict[str, object]`type` 语句清晰地告诉静态检查器和阅读者：这是一个类型别名，而不是一个运行时要使用的值。并且 `type` 语句也支持像 `Record[T]` 这样的泛型别名定义，未来如果需要对记录结构做更细粒度的类型参数化，可以轻松扩展。
六、迁移过程中要注意的几个兼容性问题
尽管新语法看起来很美好，但有一些约束需要心里有数。
第一，运行时行为略有不同。旧的 `TypeVar` 在运行时是一个对象，可以在代码里通过 `T.__name__` 等方式去检查。新的类型参数语法在运行时也会生成相应的对象，但它们和旧的 `TypeVar` 并不是同一个类型，如果之前有代码依赖 `isinstance(x, TypeVar)` 做分支判断，那么这部分逻辑需要调整。
第二，类型检查器需要升级。mypy 1.11+ 和 pyright 1.1.380+ 都对 PEP 695 提供了完整支持。如果团队里还在用旧版本的检查器或 IDE 插件，那么新语法可能会报错。在迁移之前先统一升级工具链可以避免很多麻烦。
第三，旧的 `Generic` 基类依然可用，新旧可以混写在一个项目中，但建议一个模块内保持风格一致，否则读起来会有割裂感。
第四，`from __future__ import annotations` 与 type 语句的关系。如果你在模块中使用了这个 future 导入，类型别名不再需要加引号，新语法下的 type 语句同样不受影响，它会在所有注解被延后求值的模式下正常工作，这一点感觉很统一。
七、团队采纳后的真实反馈
我把重构后的分支推上去之后，组里两个之前对泛型标注有些畏惧的同事表示“看起来清爽了不少”。他们在新需求里也开始主动用方括号语法定义参数化的类，不用再专门查 `TypeVar` 的文档。对我来说，这属于那种“用上之后就很难回去”的改进——它没有改变类型系统本身的能力边界，但把原来那种晦涩的声明方式拉回到了直觉的位置。
现在如果想快速创建一个带泛型的工具类，随手就写：
class ResultWrapper[out T]:
def __init__(self, value: T):
self._value = value
def get(self) -> T:
return self._value不需要在文件头部额外维护类型变量列表，这块心智负担的降低在长期维护里会慢慢显现出价值。
八、总结
Python 3.13 的新式类型参数和 `type` 语句是对静态类型设施的一次重要打磨。它们没有引入全新的类型概念，但让表达泛型的语法与 Python 现有的类、函数定义风格更加统一。对于已经持续投入类型标注的团队，这次升级几乎零成本，却可以有效减少样板代码和类型变量的心智维护成本。如果你已经在用 Python 3.13，可以选一个泛型较密集的模块试一试迁移，感受一下那种方括号与类名合二为一的顺畅感。
