【TypeScript 】函数重载什么时候使用

TypeScript 的函数重载是一种强大的类型工具，但其必要性取决于具体场景。以下是判断是否使用函数重载的核心原则和适用场景分析：

---

一、函数重载的 必要性 与 优缺点

必要性	优点	缺点
需要明确表达不同类型参数与返回值的精确对应关系	1. 类型提示更清晰 2. 提高代码可读性 3. 强制类型约束更严格	1. 代码冗余（需维护多个签名） 2. 实现逻辑可能复杂化

---

二、判断何时使用函数重载的 4 个核心场景

1. 参数类型与返回值类型有严格对应关系

• 适用场景：不同参数类型必须返回特定类型结果，且无法通过联合类型简化。
• 示例：

  // 重载：参数为 string 时返回 string，参数为 number 时返回 number
  function parse(input: string): string;
  function parse(input: number): number;
  function parse(input: string | number): string | number {
    if (typeof input === "string") return input.toUpperCase();
    else return input * 2;
  }
  

2. 参数数量不同导致行为差异

• 适用场景：函数根据参数数量执行不同逻辑。
• 示例：

  // 重载：1 个参数返回 Date，3 个参数返回格式化字符串
  function createDate(timestamp: number): Date;
  function createDate(year: number, month: number, day: number): string;
  function createDate(a: number, b?: number, c?: number): Date | string {
    if (b !== undefined && c !== undefined) 
      return `${a}-${b}-${c}`;
    else 
      return new Date(a);
  }
  

3. 需要隐藏复杂实现细节

• 适用场景：对外暴露简洁的接口，但内部实现需要处理多种类型。
• 示例：

  // 重载：对外提供两种明确调用方式，内部统一处理
  function format(data: string[]): string;
  function format(data: Record<string, unknown>): string;
  function format(data: any): string {
    if (Array.isArray(data)) return data.join(", ");
    else return JSON.stringify(data);
  }
  

4. 提升 API 设计的类型友好性

• 适用场景：设计库或工具函数时，提供更直观的类型提示。
• 示例：

  // 重载：明确提示回调函数参数类型
  function on(event: "click", handler: (e: MouseEvent) => void): void;
  function on(event: "keypress", handler: (e: KeyboardEvent) => void): void;
  function on(event: string, handler: (e: unknown) => void): void {
    // 实现逻辑...
  }
  

---

三、避免使用函数重载 的 3 种情况

1. 参数类型与返回值关系简单

• 替代方案：直接使用 联合类型 或 泛型。
• 示例：

  // 不推荐重载（过度设计）
  function add(a: number, b: number): number;
  function add(a: string, b: string): string;
  function add(a: any, b: any) { return a + b; }
  
  // 更简洁的联合类型方案
  function add(a: number | string, b: number | string): number | string {
    return a + b;
  }
  

2. 参数之间无明确逻辑关联

• 替代方案：使用 条件类型（Conditional Types） 或 函数重载 + 类型守卫。
• 示例：

  // 不推荐（逻辑混乱）
  function process(value: string): string;
  function process(value: number): number[];
  function process(value: any) {
    if (typeof value === "string") return value.toUpperCase();
    else return [value, value * 2];
  }
  
  // 更合理的方案：拆分为两个函数
  function processString(value: string): string { /* ... */ }
  function processNumber(value: number): number[] { /* ... */ }
  

3. 需要动态类型推断

• 替代方案：使用 泛型 或 函数重载 + 类型断言。
• 示例：

  // 不推荐（无法覆盖所有类型）
  function getValue(key: "name"): string;
  function getValue(key: "age"): number;
  function getValue(key: string): string | number { /* ... */ }
  
  // 更灵活的泛型方案
  function getValue<T extends "name" | "age">(key: T): T extends "name" ? string : number {
    // 实现逻辑...
  }
  

---

四、函数重载 vs 其他方案的 决策树

1. 是否需要精确的输入输出类型映射？

   • 是 → 使用函数重载
   • 否 → 使用联合类型/泛型

2. 参数数量是否影响行为？

   • 是 → 使用函数重载
   • 否 → 使用默认参数或可选参数

3. 是否需要隐藏复杂内部类型转换？

   • 是 → 使用函数重载
   • 否 → 保持实现透明

---

五、最佳实践总结

• 优先使用简单方案：能用联合类型/泛型解决的问题，不要过度设计重载。
• 保持重载签名简洁：通常不超过 3 个重载签名，避免维护成本过高。
• 结合类型守卫（Type Guards）：在实现函数中使用 typeof/instanceof 细化类型。
• 文档化重载意图：通过注释说明每个重载签名的设计目的。

---

通过以上原则，你可以更清晰地判断何时使用 TypeScript 函数重载，从而在类型安全性和代码简洁性之间找到最佳平衡点。