7.函数重载 副本.md
来源：https://my.feishu.cn/file/O1h0bLDssoBGKRx6RVScFqbVnud
采集状态：已完成正文采集；已从查看代码模式逐行提取，行号 1 至 116 连续，并核对滚动到底。


在我们已经熟悉了 TypeScript 函数的类型定义、可选参数以及 `this` 的处理之后，我们将探索一个更能体现其类型设计精妙之处的特性——函数重载（Function Overloading）。

函数重载允许我们为同一个函数提供多个不同的“调用签名”（Call Signatures）。这意味着，同一个函数可以根据传入参数的类型、数量或组合，执行不同的逻辑并返回不同类型的值。这对于设计灵活且类型安全的 API 尤其有用。

### 为什么需要函数重载？

让我们从一个具体场景开始。假设我们需要编写一个函数 `parseDate`，它的功能是接收一个日期信息并返回一个 `Date` 对象。我们希望这个函数足够智能，能够处理两种不同的输入格式：

1.  一个时间戳（`number` 类型）。
2.  一个表示日期的字符串（`string` 类型，如 "2025-11-03"）。

如果不使用函数重载，我们可能会写出这样的代码：

```typescript
function parseDate(input: number | string): Date {
  if (typeof input === 'number') {
    return new Date(input);
  } else {
    return new Date(input);
  }
}
```

这段代码在功能上没有问题，但它的函数签名 `(input: number | string): Date` 并没有完全体现出其行为的全部细节。调用者只知道可以传入数字或字符串，但无法从签名上直接看出这两种输入对应的是哪种日期格式。当函数逻辑变得更复杂时，这种模糊性会降低代码的可读性和可维护性。

函数重载正是为了解决这类问题而生，它让我们可以更精确地描述函数的多种形态。

### 函数重载的结构

在 TypeScript 中，实现函数重载分为两个部分：

1.  **重载签名（Overload Signatures）**：我们首先定义一系列的函数声明（只有函数名、参数和返回类型，没有函数体）。这些声明就是函数的“重载签名”，它们向外界清晰地展示了所有合法的调用方式。

2.  **实现签名（Implementation Signature）**：在所有重载签名之后，我们提供一个包含实际函数体的最终实现。这个实现的函数签名必须足够通用，能够兼容上面所有的重载签名。

让我们用函数重载来重写 `parseDate` 函数：

```typescript
// 1. 重载签名
function parseDate(timestamp: number): Date;
function parseDate(dateString: string): Date;

// 2. 实现签名
function parseDate(input: number | string): Date {
  if (typeof input === 'number') {
    // 这里的 input 被 TypeScript 推断为 number
    return new Date(input);
  } else {
    // 这里的 input 被 TypeScript 推断为 string
    return new Date(input);
  }
}

// 调用
const dateFromTimestamp = parseDate(1762156800000); // 对应第一个签名
const dateFromString = parseDate("2025-11-03");    // 对应第二个签名

// const invalidCall = parseDate(true); // 编译时错误!
```

通过这种方式，我们获得了几个显著的好处：

*   **API 清晰化**：当开发者在编辑器中输入 `parseDate(` 时，IDE 会智能地提示出两个独立的、清晰的调用签名，而不是一个模糊的联合类型。
*   **类型安全增强**：TypeScript 会根据传入的参数，精确匹配到对应的重载签名。在函数实现内部，TypeScript 也能根据代码逻辑（如 `typeof` 判断）正确地推断出参数在特定分支下的具体类型。
*   **严格的调用检查**：任何不符合任一重载签名的调用都会在编译阶段被标记为错误。

### 关键规则与注意事项

在使用函数重载时，有几个重要的规则需要遵守：

1.  **实现签名对外不可见**：实现签名的作用是提供一个统一的函数体，它本身并不对外部调用者直接可见。当我们调用函数时，TypeScript 只会检查是否匹配某一个**重载签名**。

2.  **实现签名需兼容所有重载**：实现签名的参数类型和返回类型必须能够兼容所有的重载签名。通常，我们会使用联合类型（Union Types）或 `any` 来做到这一点。例如，在上面的例子中，实现签名的参数 `input` 是 `number | string`，它包含了两个重载签名的所有可能参数类型。

3.  **检查顺序**：TypeScript 在匹配重载时会从上到下逐一检查。因此，我们应该将最精确、最具体的签名放在前面，而将较通用的签名放在后面，以避免意外的匹配。

### 函数重载 vs. 联合类型

你可能会问，既然可以用联合类型，为什么还需要函数重载？

当函数的返回值类型**不**依赖于输入参数的类型时，使用联合类型通常是更简洁的选择。例如：

```typescript
// 返回值总是 string，使用联合类型更佳
function formatId(id: string | number): string {
  return `ID-${id}`;
}
```

但是，当函数的**返回值类型**与某个**输入参数的类型**强相关时，函数重载就显示出其威力了。设想一个函数，如果传入数字，它返回数字；如果传入字符串，它返回字符串。

```typescript
function process(input: number): number;
function process(input: string): string;
function process(input: number | string): number | string {
  if (typeof input === 'number') {
    return input * 2;
  } else {
    return input.toUpperCase();
  }
}

const numResult = process(10); // numResult 的类型是 number
const strResult = process("hello"); // strResult 的类型是 string
```

在这个例子中，TypeScript 能够精确地推断出 `numResult` 和 `strResult` 的类型，这是简单的联合类型签名 `(input: number | string): number | string` 所无法做到的。

### 总结

函数重载是 TypeScript 类型系统中的一个高级工具。它通过为单个函数提供多个调用签名，极大地增强了 API 的表现力和类型安全性。

虽然在许多简单场景下，使用联合类型或可选参数是更合适的选择，但在构建复杂的、需要根据输入精确决定输出类型的函数时，函数重载是实现清晰、健壮和开发者友好的 API 的不二法门。它将函数“契约”的定义提升到了一个新的高度，是每一位 TypeScript 开发者都应掌握的强大技巧。