本文介绍使用 TypeVar 约束泛型替代 @overload 实现 __init__ 类型安全的方法，使 Vector3 能自动推导并保持 x/y/z 的同质数值类型（int 或 float），同时精准提示 __key() 返回元组及 @property 访问器的类型。
本文介绍使用 `typevar` 约束泛型替代 `@overload` 实现 `__init__` 类型安全的方法，使 `vector3` 能自动推导并保持 `x/y/z` 的同质数值类型（`int` 或 `float`），同时精准提示 `__key()` 返回元组及 `@property` 访问器的类型。
在 Python 类型提示实践中，对构造函数（__init__）进行多重重载（@overload）以区分 int 和 float 参数组合，看似直观，实则存在根本性缺陷：@overload 仅影响类型检查器对调用点的推断，无法将参数类型约束传递至实例属性或后续方法返回值。这会导致 self._x、self.__key() 或 @property x 的类型退化为 int | float，丧失类型精度与静态分析价值。
更优解是采用泛型类（Generic Class）配合约束型类型变量（Constrained TypeVar）。它让类型系统能根据构造时传入的实际参数，一次性推导出整个实例的统一类型参数，从而实现端到端的类型一致性。
以下为推荐实现：
from typing import Generic, TypeVar
T = TypeVar('T', int, float) # 约束 T 只能是 int 或 float（二者互不兼容，但 int 可隐式提升为 float）
class Vector3(Generic[T]):
def __init__(self, x: T, y: T, z: T) -> None:
self._x: T = x
self._y: T = y
self._z: T = z
def __key(self) -> tuple[T, T, T]:
return (self._x, self._y, self._z)
@property
def x(self) -> T:
return self._x
@property
def y(self) -> T:
return self._y
@property
def z(self) -> T:
return self._z✅ 关键优势说明：
- T 在实例化时被唯一确定（如 Vector3(1, 2, 3) → Vector3[int]；Vector3(1.0, 2.0, 3.0) → Vector3[float]）；
- 所有属性（_x, _y, _z）和方法返回值（如 __key()、x）均精确继承 T，无联合类型污染；
- 支持跨类型混合传参的隐式提升规则：Vector3(1, 2.0, 3) 中 int 会被提升为 float，最终推导为 Vector3[float]（符合 Python 数值运算惯例）；
- 静态类型检查器（如 mypy）可捕获非法用法：Vector3("1", "2", "3") 将报错，因 str 不在 T 的约束范围内。
⚠️ 注意事项：
- 不要为 __init__ 添加 @overload —— 它与泛型机制冲突，且冗余；
- 显式标注 self._x: T 等字段类型（而非依赖类型推导），确保 mypy 在严格模式下也能正确识别；
- 若需严格禁止 int/float 混合（即 Vector3(1, 2.0, 3) 应报错），则需改用 Union[int, float] + 运行时校验，但会牺牲类型精度——泛型方案在类型安全与实用性间取得了最佳平衡。
通过此设计，Vector3 不仅获得清晰、自洽的类型契约，也为后续扩展（如 Vector3[complex]）预留了泛型接口，是构建强类型数值工具类的推荐范式。
