TypeScript继承类中方法重载失效问题排查

问题场景 #

我定义了二维向量类 Vec2 和继承自它的三维向量类 Vec3，代码如下：

Vec2.ts

export interface Vec2I {
    x: number;
    y: number;
}

export class Vec2 implements Vec2I {
    constructor(public x: number = 0, public y: number = 0) {}

    public set(x: Vec2I): void;
    public set(x: number, y: number): void;

    public set(x: Vec2I | number, y?: number) {
        if (typeof x === "number") {
            this.x = x;
            if (y !== undefined) {
                this.y = y;
            }
        } else {
            this.x = x.x;
            this.y = x.y;
        }
    }
}

Vec3.ts

import { Vec2, Vec2I } from "./Vec2";

export interface Vec3I extends Vec2I {
    z: number;
}

export class Vec3 extends Vec2 implements Vec3I {
    constructor(x: number = 0, y: number = 0, public z: number = 0) {
        super(x, y);
    }

    public set(x: Vec3I): void;
    public set(x: number, y: number, z: number): void;

    public set(x: Vec3I | number, y?: number, z?: number) {
        super.set(x, y);

        if (typeof x === "number") {
            if (z !== undefined) {
                this.z = z;
            }
        } else {
            this.z = x.z;
        }
    }
}

编译时出现如下类型错误：

Property 'set' in type 'Vec3' is not assignable to the same property in base type 'Vec2'.
  Type '{ (x: Vec3I): void; (x: number, y: number, z: number): void; }' is not assignable to type '{ (x: Vec2I): void; (x: number, y: number): void; }'.
    Types of parameters 'x' and 'x' are incompatible.
      Type 'number' is not assignable to type 'Vec3I'.

我原本以为 Vec3I 继承自 Vec2I，可以直接替换使用，但注释掉 Vec3 中的重载声明后，代码就能正常运行。

问题原因 #

TypeScript 对继承类的方法重载有严格的兼容性要求：子类的重载签名必须完全覆盖父类的所有重载签名，这是里氏替换原则（LSP）的体现——任何使用父类的地方，都能无缝替换成子类。

具体到这个场景：

1. 父类 Vec2 的 set 有两个重载：
   • set(x: Vec2I): void：接受任意二维向量接口实例
   • set(x: number, y: number): void：接受两个数字参数
2. 子类 Vec3 的 set 只定义了自己的两个重载：
   • set(x: Vec3I): void：仅接受三维向量接口实例（比父类的 Vec2I 范围更窄）
   • set(x: number, y: number, z: number): void：仅接受三个数字参数（不支持父类的两个数字参数的调用方式）

当把 Vec3 实例当作 Vec2 使用时（比如赋值给 Vec2 类型变量），调用 set(Vec2I) 或 set(1, 2) 时，子类的重载签名无法匹配这些调用，导致类型不兼容。

而注释掉重载声明后，TypeScript 会以方法的实现签名作为对外暴露的类型，你的实现代码其实能处理父类的所有调用场景（比如传入 Vec2I 时，会走 else 分支调用 super.set(x)），因此不会报错，但这种写法隐藏了真实的可用调用方式，不够规范。

解决方案 #

在子类的重载声明中保留父类的所有重载签名，再添加子类特有的重载签名，确保子类能兼容父类的所有调用方式：

修改后的 Vec3.ts 代码：

import { Vec2, Vec2I } from "./Vec2";

export interface Vec3I extends Vec2I {
    z: number;
}

export class Vec3 extends Vec2 implements Vec3I {
    constructor(x: number = 0, y: number = 0, public z: number = 0) {
        super(x, y);
    }

    // 保留父类的两个重载签名，确保兼容父类调用
    public set(x: Vec2I): void;
    // 添加子类特有的重载签名
    public set(x: Vec3I): void;
    public set(x: number, y: number): void;
    public set(x: number, y: number, z: number): void;

    public set(x: Vec2I | Vec3I | number, y?: number, z?: number) {
        // 处理父类的参数逻辑
        if (typeof x !== "number") {
            super.set(x);
            // 如果是Vec3I，额外处理z值
            if ('z' in x) {
                this.z = x.z;
            }
        } else {
            super.set(x, y);
            // 如果传入了z参数，更新z值
            if (z !== undefined) {
                this.z = z;
            }
        }
    }
}

这样修改后：

• 子类的重载签名完全覆盖了父类的所有调用场景，满足类型兼容性要求
• 同时新增了子类特有的重载方式（传入 Vec3I 或三个数字参数）
• 实现代码也做了对应调整，确保所有参数场景都能正确处理

内容的提问来源于stack exchange，提问作者Yurii Horchynskyi