1. API定义

重载函数通过多个函数签名和一个实现签名定义：

// 重载签名（Overload Signatures）
function greet(name: string): string;
function greet(names: string[]): string[];

// 实现签名（Implementation Signature）
function greet(input: string | string[]): string | string[] {
  if (typeof input === "string") {
    return `Hello, ${input}!`;
  } else {
    return input.map(name => `Hi, ${name}!`);
  }
}

// 调用
const single = greet("Alice"); // string
const multi = greet(["Bob", "Charlie"]); // string[]

2. 核心作用

• 类型精确匹配：为不同参数组合提供精确返回值类型

• API文档化：显式声明函数支持的所有调用方式

• 类型安全：防止参数类型误用和返回值类型错误

3. 主要用处

1.参数多态：处理不同参数类型/数量的场景

// 日期格式化重载
function formatDate(timestamp: number): string;
function formatDate(date: Date): string;
function formatDate(dateObj: Date | number): string {
  // 实现...
}

2.参数依赖关系：根据参数类型确定返回值类型

// 返回值类型依赖参数类型
function parseInput(input: string): number;
function parseInput(input: number): string;
function parseInput(input: any): any {
  // 实现...
}

3.可选参数约束：精确控制可选参数组合

// 精确控制可选参数
function createElement(tag: "img", attrs: { src: string }): HTMLImageElement;
function createElement(tag: "a", attrs: { href: string }): HTMLAnchorElement;
function createElement(tag: any, attrs: any): HTMLElement {
  // 实现...
}

4. 使用要点

1. 签名顺序：从最具体 → 最宽泛排列

2. 实现签名：必须兼容所有重载签名

3. 类型收窄：在实现中使用类型守卫区分逻辑

function process(data: string): void;
function process(data: string[]): void;
function process(data: any): void {
  if (typeof data === "string") {
    // 字符串处理
  } else if (Array.isArray(data)) {
    // 数组处理
  }
}

避免陷阱：

• ❌ 实现签名不可直接调用

• ✅ 至少需要两个重载签名

• ✅ 返回值类型必须兼容所有签名

5. 最佳实践总结

6. 典型应用场景

1. DOM操作：处理不同元素类型

2. 数学计算：处理数值/矩阵等不同输入

3. API客户端：处理不同请求参数格式

4. 数据转换：输入输出类型映射

总结：

        TypeScript函数重载通过声明多个类型签名+单一实现的方式，在保持JavaScript灵活性的同时提供强类型约束。核心价值在于：

• 增强API自描述性

• 精确控制参数-返回值类型映射

• 提升复杂函数调用的类型安全性
  适用于需要处理多种参数模式但实现逻辑统一的场景，是构建类型安全复杂API的关键技术。