TypeScript 函数重载：重载签名详解

TypeScript 中的函数重载，是指为一个函数编写多个调用签名，后面再跟一个唯一的实现。每个签名都可以把不同的参数类型和不同的返回类型配对，调用方拿到的是最精确的那一个。

// Overload signatures: what callers see
function parse(input: string): number;
function parse(input: string[]): number[];
// Implementation: one body that handles every case
function parse(input: string | string[]): number | number[] {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

const one = parse("42");          // one: number
const many = parse(["1", "2.5"]); // many: number[]

console.log(one + 1);             // 43
console.log(many.map((n) => n * 2)); // [ 2, 5 ]

如果没有重载，parse 每次调用都会返回 number | number[]，在你自己收窄结果之前，one + 1 都会报错。

重载签名与实现

一个重载函数由两部分组成：

1. 重载签名：没有函数体的声明，每种支持的调用形式对应一个。调用方只能使用这些签名。
2. 实现签名：最后一个带函数体的声明。它的参数必须能接受所有重载接受的内容，它的返回类型必须涵盖所有重载的返回类型。它对外部是不可见的。

类型只存在于编译期，所以运行时只有一个 JavaScript 函数。实现必须检查自己的参数（typeof、Array.isArray、arguments.length...）来决定做什么。编译器会检查重载和实现是否一致：

function format(value: string): string;
function format(value: number): number {
  return value;
}
// error TS2394: This overload signature is not compatible with its implementation signature.

解决办法是放宽实现的类型：function format(value: string | number): string | number。

实现签名不能被调用

这是最让人意外的一条规则。一次调用必须单独匹配某一个重载签名；TypeScript 不会把它们组合起来。

// This does not compile: no single overload takes string | string[].
function parse(input: string): number;
function parse(input: string[]): number[];
function parse(input: string | string[]): number | number[] {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

function readInput(multi: boolean): string | string[] {
  return multi ? ["1", "2"] : "3";
}

console.log(parse(readInput(true)));

编译器输出：

index.ts(12,19): error TS2769: No overload matches this call.
  The last overload gave the following error.
    Argument of type 'string | string[]' is not assignable to parameter of type 'string[]'.
      Type 'string' is not assignable to type 'string[]'.

实现接受 string | string[]，但调用方看不到它。添加第三个接受联合类型、返回联合类型的重载，这次调用就能通过编译，并打印 [ 1, 2 ]：

function parse(input: string): number;
function parse(input: string[]): number[];
function parse(input: string | string[]): number | number[];
function parse(input: string | string[]): number | number[] {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

参数个数不同

重载也能描述参数个数不同的调用。下面的例子中，日期可以由时间戳构建，也可以由年、月、日构建，但不能只用两个数字：

function makeDate(timestamp: number): Date;
function makeDate(year: number, month: number, day: number): Date;
function makeDate(a: number, month?: number, day?: number): Date {
  if (month !== undefined && day !== undefined) {
    return new Date(Date.UTC(a, month - 1, day));
  }
  return new Date(a);
}

console.log(makeDate(0).toISOString());          // 1970-01-01T00:00:00.000Z
console.log(makeDate(2024, 3, 15).toISOString()); // 2024-03-15T00:00:00.000Z

// @ts-expect-error: No overload expects 2 arguments, but overloads do exist that expect either 1 or 3 arguments.
makeDate(2024, 3);

如果用一个带两个可选参数的签名，它会接受 makeDate(2024, 3)，并悄悄地构建出错误的日期。重载把这种情况变成了编译错误（TS2575）。

顺序很重要

TypeScript 从上到下依次尝试重载，选用第一个匹配的。把最具体的签名放在前面。列表靠前的宽泛重载会吞掉本该交给后面签名的调用：

function describe(value: unknown): string;   // matches everything
function describe(value: string): "text";    // never chosen
function describe(value: unknown): string {
  return typeof value === "string" ? "text" : "other";
}

const d = describe("hi"); // d: string, not "text"

把前两个签名交换位置，describe("hi") 的类型就是 "text"。

用重载还是联合类型参数？

当返回类型取决于参数类型时，重载多写的几行才值得。如果不是这样，一个带联合类型参数的签名更短、更易读，还能接受重载会拒绝的联合类型参数。

// Overloads that add nothing: the return type is always number
function lengthOfA(x: string): number;
function lengthOfA(x: unknown[]): number;
function lengthOfA(x: string | unknown[]): number {
  return x.length;
}

// Better: one signature
function lengthOf(x: string | unknown[]): number {
  return x.length;
}

function pick(useList: boolean): string | number[] {
  return useList ? [1, 2, 3] : "abc";
}

const input = pick(true);
console.log(lengthOf(input)); // 3 (lengthOfA(input) would be TS2769)
console.log(lengthOfA("abcd")); // 4

结合条件类型的泛型可以把某些重载组合写成一个签名，但只有两三种情况时，重载通常更易读。

方法与构造函数的重载

在类中，方法使用同样的写法：先写重载签名，再写带函数体的方法。构造函数也可以用同样的方式重载。

class Money {
  readonly cents: number;

  constructor(cents: number);
  constructor(amount: string);
  constructor(value: number | string) {
    this.cents = typeof value === "number" ? value : Math.round(parseFloat(value) * 100);
  }

  add(other: Money): Money;
  add(cents: number): Money;
  add(value: Money | number): Money {
    const extra = typeof value === "number" ? value : value.cents;
    return new Money(this.cents + extra);
  }
}

const price = new Money("19.99");
console.log(price.add(1).cents);               // 2000
console.log(price.add(new Money(1)).cents);    // 2000

接口和对象类型也可以声明重载，形式是多个调用签名，或者多个同名的方法签名。很多内置函数就是这样声明的：在编辑器里把鼠标悬停在数组的 reduce 上，会显示 “+2 overloads”。