TypeScript实现方法重载接口出现ts(2322)类型报错如何解决

该问题围绕TypeScript方法重载（method overloading）特性展开：可正常定义Api接口，但在实现该接口时触发类型报错。原有实现逻辑是通过判断arg的类型匹配对应重载签名，返回符合要求的类型值，但代码无法通过编译，且暂未在TypeScript官方文档中找到方法重载的相关实现说明。

复现代码 #

interface Api {
  test(arg: string): string;
  test(arg: number): string[];
}

const api: Api = {
  test(arg: string | number) {
    if (typeof arg === "string") {
      return "string";
    }
    return ["string", "string"];
  },
};

报错信息 #

Type '(arg: string | number) => string[] | "string"' is not assignable to type '{ (arg: string): string; (arg: number): string[]; }'.
  Type 'string[] | "string"' is not assignable to type 'string'.
    Type 'string[]' is not assignable to type 'string'.ts(2322)

TypeScript的重载实现有明确规则：

• 对外暴露的是编写的重载签名（也就是接口里定义的两个test方法类型）
• 内部的实现签名必须兼容所有重载签名的参数、返回值要求，但编译器在做接口赋值校验时，不会深入函数实现内部的类型收窄逻辑做关联校验，只会直接检查实现函数的整体类型是否匹配每个重载项。

当前编写的实现函数类型是(arg: string | number) => string | string[]，当校验是否匹配(arg: string) => string这个重载时，返回值string | string[]里的string[]无法赋值给string，就会直接抛出类型错误。

方案1：使用标准函数重载写法实现（推荐，类型最安全） #

不要直接在对象字面量里写联合参数的实现，先写全重载签名，再写兼容的实现签名，TS会认可这种写法的类型正确性：

interface Api {
  test(arg: string): string;
  test(arg: number): string[];
}

const api: Api = (() => {
  function test(arg: string): string;
  function test(arg: number): string[];
  function test(arg: string | number): string | string[] {
    if (typeof arg === "string") {
      return "string";
    }
    return ["string", "string"];
  }
  return { test };
})();

方案2：类型断言（适合逻辑简单的快速修复） #

如果确定内部逻辑不会出类型问题，可以直接用类型断言把实现函数指定为接口要求的test类型，跳过编译器的赋值校验：

interface Api {
  test(arg: string): string;
  test(arg: number): string[];
}

const api: Api = {
  test: ((arg: string | number) => {
    if (typeof arg === "string") {
      return "string";
    }
    return ["string", "string"];
  }) as Api['test']
};

注意：类型断言会绕过部分类型检查，不要在逻辑复杂的场景滥用，避免埋下类型隐患。

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