大型遗留项目中为仅实现父类单一重载变体的子类添加类型标注的解决方案（解决Mypy与里氏替换原则报错）

我太懂这种遗留项目的窘境了——想加类型标注规范代码，又不能动核心架构，还得跟Mypy的各种原则报错死磕。你遇到的问题本质是：父类的重载/Union类型要求方法能处理多种ID类型，但你的子类其实是针对单一ID类型做特化实现，直接重载父类方法会违反里氏替换原则（因为子类不能完全替换父类的所有场景），而用@overload又被要求实现所有变体，完全不符合你的需求。

下面给你两个解决方案，优先推荐第一个，完全合规且改动极小：

方案一：用泛型重构父类（最优解） #

这是最贴合你场景的方案，核心是把父类API改成泛型模板类，用泛型变量来约束ID的类型，这样子类就可以基于特定的ID类型做特化，完全符合里氏替换原则，Mypy也不会报错。

具体代码实现 #

from typing import TypeVar, List, Dict, Any, Generic

# 定义泛型变量，限制只能是int或str（匹配你现有场景）
IDType = TypeVar("IDType", int, str)

# 把API改成泛型类，继承Generic[IDType]
class API(Generic[IDType]):
    def get_by_ids(self, ids: List[IDType]) -> Dict[IDType, Any]:
        # 父类的核心共享逻辑（如果有的话），不需要改动
        pass

# 子类Foo继承API[int]，明确指定ID类型为int
class Foo(API[int]):
    def get_by_ids(self, ids: List[int]) -> Dict[int, Any]:
        # Foo的具体实现，只处理int类型ID
        pass

# 子类Bar继承API[str]，明确指定ID类型为str
class Bar(API[str]):
    def get_by_ids(self, ids: List[str]) -> Dict[str, Any]:
        # Bar的具体实现，只处理str类型ID
        pass

为什么这个方案有效？ #

1. 完全符合里氏替换原则：API[int]本身就是“处理int类型ID的API”，Foo是它的具体实现，当你把Foo当作API[int]的实例使用时，它的方法参数和返回值完全匹配，Mypy会认为这是合法的替换。
2. 改动极小：只需要给父类加泛型标注，子类继承时指定具体类型，完全不需要修改你的业务逻辑代码，完美适配遗留项目。
3. 类型检查精准：Mypy会严格检查子类的参数类型——比如你给Foo.get_by_ids传List[str]，它会立刻报错，完全符合你的需求。
4. 扩展性强：如果以后需要支持新的ID类型（比如tuple[int, int]），只需要扩展IDType的约束，或者创建新的子类API[Tuple[int, int]]即可。

方案二：临时压制Mypy报错（下策，谨慎使用） #

如果你暂时不想改父类的结构，也可以用# type: ignore来压制Mypy的报错，但这是妥协方案，会失去该方法的类型检查严谨性，只适合临时过渡：

class Foo(API):
    def get_by_ids(
        self, ids: List[int],
    ) -> Dict[int, Any]:  # type: ignore[override]
        pass

class Bar(API):
    def get_by_ids(
        self, ids: List[str],
    ) -> Dict[str, Any]:  # type: ignore[override]
        pass

⚠️ 注意：这个方案只是隐藏了报错，并没有从根本上解决LSP的问题——如果有代码把Foo当作API的实例来用，传了List[str]给get_by_ids，运行时还是会出问题，所以只推荐作为临时过渡方案，最终还是要转到泛型方案。

为什么之前的重载方案不行？ #

Mypy对父类的重载方法有严格要求：子类必须覆盖父类的所有重载变体，否则会认为子类不能完全替换父类的所有使用场景，违反里氏替换原则。这就是为什么你用@overload时，Mypy要求子类实现所有重载组合的原因——它默认认为子类必须支持父类的所有输入输出变体，这和你“子类只处理一种类型”的需求完全冲突，所以重载方案不适合你的场景。

内容来源于stack exchange