Python 类型参数语法如何改写通用容器与函数

如果一个项目里同时出现 TypeVar、Generic 和类型别名，Python 3.12 之后可以把类型参数直接写在类、函数或别名名称后面。迁移的核心不是“把尖括号换成方括号”，而是把类型参数放回它真正服务的对象旁边：通用类使用 class Box[T]，通用函数使用 def first[T](...)，通用别名使用 type Pair[T] = ...。

先把三种声明位置分清

旧写法通常先在模块级声明 T = TypeVar("T")，再把 T 传给不同的类和函数。这种方式仍然有效，但同一个名字可能被多个泛型对象复用，阅读代码时要回头查它的约束、边界和作用范围。新语法把声明位置前移到对象本身，迁移时可以按下面的关系对照。

这三种写法主要服务静态类型检查。运行时仍然是普通类、函数和类型对象；不要把类型参数语法误认为运行时的容器转换或数据校验。

用 class Box[T] 改写通用容器

容器迁移时，先找出“输入值是什么类型、保存后返回什么类型”这条关系，再把同一个 T 放到构造方法、属性和读取方法上。下面的例子不依赖额外库，重点是让 Box[int] 和 Box[str] 在调用点保留不同的元素类型。

class Box[T]:
    # T 只属于 Box 这个泛型类，表示容器保存的元素类型
    def __init__(self, value: T) -> None:
        self.value = value

    def get(self) -> T:
        # 返回值继续使用 T，类型检查器会把它替换成具体实参
        return self.value


number_box = Box(42)       # 推断为 Box[int]
message_box = Box("ready")  # 推断为 Box[str]
print(number_box.get() + 1)
print(message_box.get().upper())

这里不需要显式继承 Generic[T]。如果容器有上界，也可以写成 class Box[T: str]，表示 T 必须符合字符串上界。上界只影响类型检查规则，不会在构造时自动把整数转换成字符串。

用 def[T] 让函数传递元素类型

通用函数最适合从“输入和返回值必须保持什么关系”开始改。下面的 first 用 Iterable[T] 接受不同容器，并把元素类型传给返回值。空集合是运行时边界，所以示例显式抛出 ValueError，而不是让类型标注掩盖异常。

from collections.abc import Iterable

def first[T](items: Iterable[T]) -> T:
    # 迭代器可能为空，先处理运行时边界再返回元素
    for item in items:
        return item
    raise ValueError("items 不能为空")


name = first(["Ada", "Linus"])  # 推断为 str
count = first((1, 2, 3))         # 推断为 int
print(name.upper())
print(count + 1)

注意 T 只在函数声明及其注解中有效。它不是一个可以在函数体里读取的值，也不会因为写成大写字母就生成运行时变量。若函数需要处理不同参数列表，可以进一步使用 **P 参数规范，但不要为了“看起来泛型”而增加没有实际类型关系的参数。

类型别名和旧版本兼容要单独处理

当一组复杂类型会被多处复用时，可以用 type 声明泛型别名：

type Pair[T] = tuple[T, T]

def midpoint[T: int | float](pair: Pair[T]) -> T:
    # 上界限制可参与运算的类型，返回值仍与输入元素类型一致
    return (pair[0] + pair[1]) / 2  # 类型检查器可按项目规则提示结果类型

迁移到生产代码前，要先确认解释器版本和类型检查器版本。Python 3.11 及更早版本不能解析 class Box[T] 和 type Pair[T] 这样的语法，兼容写法仍应保留：

from typing import Generic, TypeVar

T = TypeVar("T")  # 旧版本把类型参数放在模块级，再传给 Generic

class Box(Generic[T]):
    def __init__(self, value: T) -> None:
        self.value = value

    def get(self) -> T:
        # 兼容写法的运行逻辑和新语法相同
        return self.value

迁移清单可以按三项检查：运行环境是否至少 Python 3.12；工具链是否接受 PEP 695 语法；公共库是否还要向 3.11 用户发布。如果最后一项答案是“要”，优先维持旧写法，或者用明确的版本分支和文档说明，不要只在源码里混用两套声明。

常见问题

类型参数会在运行时生成一个名为 T 的变量吗

不会。T 主要用于声明和静态分析，不能在函数体里当作值读取；需要运行时类型对象时，应显式传入类或使用普通参数。

新语法能替代所有 TypeVar 用法吗

不能。复杂的约束、参数规范、类型变量元数据或旧解释器兼容仍可能需要 TypeVar 等传统 API。迁移前先确认目标工具链支持范围。

为什么代码能运行但类型检查仍然报错

类型参数语法改变的是声明和检查模型，不会自动修复函数内部的可空值、空迭代器或不兼容返回值。先按运行时边界补异常处理，再根据检查器提示缩小类型。

把类型参数放到类、函数和别名名称旁边，通常能让通用关系更容易读懂；真正需要谨慎的是解释器版本、检查器支持和公共库兼容范围。先迁移一个小模块，再把同样的模式推广到整个项目。