2026 to do list
2025/12/28 16:03:25
本文档详细介绍了 Python 泛型的用法，并通过大量代码示例展示如何在 Python 中使用泛型进行类型安全编程。同时，我们也会对比 Java 的泛型机制，帮助你更好地理解两者的区别。
1. 为什么需要泛型？
Python 是一门动态语言，但在大型项目中，为了提高代码的可维护性和减少 Bug，我们通常会使用类型提示 (Type Hints)。泛型允许我们在定义函数、类或接口时，不指定具体的数据类型，而是在使用时再指定。
主要好处：
- 类型安全：静态类型检查器（如
mypy）可以在运行前发现类型错误。 - 代码复用：一套逻辑可以应用于多种数据类型。
- IDE 智能提示：更好的自动补全和代码导航。
2. 基础概念与语法
2.1 定义类型变量 (TypeVar)
在 Python 中（3.12 之前），泛型的核心是TypeVar。必须先定义一个类型变量对象，才能在后续代码中使用它。
fromtypingimportTypeVar,List# 定义一个类型变量 T# 习惯上变量名和字符串参数保持一致T=TypeVar('T')2.2 泛型函数
一个简单的例子：实现一个函数，返回列表中的第一个元素。
fromtypingimportTypeVar,List T=TypeVar('T')defget_first(items:List[T])->T:"""返回列表的第一个元素，类型与列表元素类型一致"""returnitems[0]# 使用示例n:int=get_first([1,2,3])# T 被推断为 ints:str=get_first(["a","b"])# T 被推断为 str# IDE 会报错的例子:# x: str = get_first([1, 2, 3]) # 错误: 期望返回 int，但标记为 str2.3 泛型类
使用Generic[T]基类来定义泛型类。
fromtypingimportTypeVar,Generic T=TypeVar('T')classStack(Generic[T]):def__init__(self)->None:self.items:List[T]=[]defpush(self,item:T)->None:self.items.append(item)defpop(self)->T:returnself.items.pop()# 具体化使用int_stack=Stack[int]()int_stack.push(1)# int_stack.push("a") # 类型检查错误: 期望 intstr_stack=Stack[str]()str_stack.push("hello")2.4 多个类型变量
类似于 Java 的Map<K, V>。
K=TypeVar('K')V=TypeVar('V')classKeyValuePair(Generic[K,V]):def__init__(self,key:K,value:V):self.key=key self.value=value pair=KeyValuePair[str,int]("age",25)2.5 上界约束 (Bound)
有时我们需要限制 T 必须是某个类的子类。
classAnimal:defspeak(self):passclassDog(Animal):...classCat(Animal):...# T 必须是 Animal 或其子类A=TypeVar('A',bound=Animal)defmake_noise(animal:A)->None:animal.speak()make_noise(Dog())# OK# make_noise("hello") # Error: str 不是 Animal 的子类3. Python vs Java 泛型对比
这是最关键的部分，理解两者的差异有助于你从 Java 思维转换到 Python 思维。
3.1 语法对比
| 特性 | Java | Python (3.5 - 3.11) | Python (3.12+) |
|---|---|---|---|
| 定义泛型类 | class Box<T> { ... } | class Box(Generic[T]): ... | class Box[T]: ... |
| 定义泛型方法 | public <T> T func(T x) | def func(x: T) -> T: | def func[T](x: T) -> T: |
| 类型变量声明 | 隐式声明 (直接写<T>) | 必须显式声明(T = TypeVar('T')) | 隐式声明 (3.12+ 新语法) |
| 实例化 | new Box<Integer>() | Box[int]() | Box[int]() |
| 通配符 | List<?> | List[Any] | List[Any] |
| 上界约束 | <T extends Number> | TypeVar('T', bound=Number) | class Box[T: Number]: |
3.2 核心机制差异
Java: 伪泛型与类型擦除 (Type Erasure)
- 机制：Java 编译器在编译时检查类型，但在生成的字节码中，所有的
T都会被替换成Object(或其他上界)。运行时 JVM 不知道List<String>和List<Integer>的区别。 - 后果：你不能在运行时做
if (obj instanceof T)这样的检查。
Python: 运行时对象与静态检查
- 机制：Python 是动态的。
Generic[T]和TypeVar('T')都是运行时的真实对象。 - 检查：Python 解释器本身完全忽略这些类型提示，不会在运行时报错（除非代码逻辑本身错了）。类型检查完全依赖外部工具（如
mypy,pyright, 或 IDE）。 - 后果：你可以运行
x: int = "hello"，Python 解释器照样执行不误。必须配合mypy使用才有意义。
3.3 代码直接对比
Java:
// Java 不需要提前定义 TpublicclassBox<T>{privateTcontent;publicvoidset(Tcontent){this.content=content;}publicTget(){returncontent;}}// 使用Box<String>box=newBox<>();box.set("hello");Python:
fromtypingimportTypeVar,Generic# Python 必须先定义 TT=TypeVar('T')classBox(Generic[T]):def__init__(self)->None:self.content:T=Nonedefset(self,content:T)->None:self.content=contentdefget(self)->T:returnself.content# 使用box=Box[str]()box.set("hello")3.4 上界约束对比 (Upper Bound)
Java 使用extends关键字来实现上界约束，而 Python 在TypeVar定义中使用bound参数。
Java:
// T 必须是 Animal 或其子类publicclassZoo<TextendsAnimal>{privateTanimal;publicvoidset(Tanimal){// 可以安全调用 Animal 的方法animal.speak();}}Python:
# T 必须是 Animal 或其子类T=TypeVar('T',bound='Animal')classZoo(Generic[T]):def__init__(self,animal:T):self.animal=animaldefset(self,animal:T)->None:# 可以安全调用 Animal 的方法self.animal.speak()4. 进阶用法示例 (结合你的项目)
在 RAG 系统或数据处理管道中，泛型非常有用。
4.1 泛型 Repository 模式
fromtypingimportTypeVar,Generic,List,Optionalfromdataclassesimportdataclass# 假设有两个实体模型@dataclassclassUser:id:intname:str@dataclassclassDocument:id:intcontent:str# 定义泛型 T，约束为必须有 id 属性 (这里用 Protocol 更高级，但简化演示用)T=TypeVar('T')classBaseRepository(Generic[T]):def__init__(self):self.db:dict[int,T]={}defsave(self,entity:T)->None:# 假设实体都有 id 属性self.db[entity.id]=entitydefget(self,id:int)->Optional[T]:returnself.db.get(id)deffind_all(self)->List[T]:returnlist(self.db.values())# 具体实现classUserRepository(BaseRepository[User]):deffind_by_name(self,name:str)->Optional[User]:foruserinself.db.values():ifuser.name==name:returnuserreturnNone# 使用user_repo=UserRepository()user_repo.save(User(1,"Alice"))user=user_repo.get(1)# 类型自动推断为 User4.2 泛型 Protocol (类似 Java Interface)
如果你想定义一个“只要有read()方法的对象”，不管它继承自谁。
fromtypingimportProtocol,TypeVar T=TypeVar('T')classReader(Protocol[T]):defread(self)->T:...defprocess_data(reader:Reader[str])->None:print(reader.read())classFileReader:defread(self)->str:return"file content"# FileReader 没有继承 Reader，但符合结构，可以通过检查process_data(FileReader())5. 总结
- 显式定义：Python (3.12前) 需要
T = TypeVar('T')。 - 继承 Generic：类需要继承
Generic[T]才能成为泛型类。 - 工具检查：泛型主要服务于静态检查工具和 IDE，运行时不会强制校验。
- 灵活性：Python 的泛型系统非常强大，配合
Protocol(结构化类型) 可以实现比 Java 更灵活的模式。