【理论】TypeScript 函数重载：从 Vue 3 defineEmits 说起的类型安全实践

一、背景介绍

Vue 3 的 <script setup> 语法：

const emit = defineEmits<{
  (e: 'click', payload: { timestamp: number }): void;
}>();

花括号里的 (e: 'click', payload: { timestamp: number }): void 并非完整的函数定义，而是一个调用签名（Call Signature）。它描述了函数的参数列表和返回类型，却不包含实现体。

这让我意识到，Vue 3 正是借助 TypeScript 的函数类型重载机制，为自定义事件提供了精确的类型约束。本文将从这一实际场景出发，系统梳理函数重载的核心概念、语法细节与最佳实践。

---

二、方案分析：重载的本质与语法体系

函数重载（Function Overloading）允许同一个函数拥有多个类型签名。编译器根据调用时的参数组合，匹配对应的重载签名，从而提供精确的类型推断和返回值推导。

2.1 普通函数的重载

重载的实现分为两步：声明多个重载签名 （对外暴露的类型接口），再提供一个实现签名（内部统一的函数体）。

// 步骤 1：重载签名（仅类型声明，无实现体）
function add(a: number, b: number): number;
function add(a: string, b: string): string;

// 步骤 2：实现签名（真正的函数体，参数类型需兼容所有重载）
function add(a: number | string, b: number | string): number | string {
  if (typeof a === 'number' && typeof b === 'number') {
    return a + b;
  }
  return `${a}${b}`;
}

// 调用时的类型安全检查
add(1, 2);      // ✅ 返回类型推断为 number
add('a', 'b');  // ✅ 返回类型推断为 string
add(1, 'b');    // ❌ 无匹配的重载签名，编译报错

关键设计原则：

• 重载签名面向调用方，决定外部可见的类型约束；
• 实现签名对外不可见，仅负责内部逻辑，其参数类型必须足够宽泛，以兼容所有重载分支。

2.2 类中的函数重载

类方法同样支持重载，且可通过可选参数实现更灵活的组合：

class Calculator {
  // 重载签名
  calculate(a: number, b: number): number;
  calculate(a: string, b: string): string;
  calculate(a: number, b: number, operation: 'add' | 'multiply'): number;

  // 实现签名：最后一个参数设为可选，兼容所有重载
  calculate(
    a: number | string,
    b: number | string,
    operation?: 'add' | 'multiply'
  ): number | string {
    if (typeof a === 'number' && typeof b === 'number') {
      if (operation === 'multiply') return a * b;
      return a + b;
    }
    return `${a}${b}`;
  }
}

const calc = new Calculator();
calc.calculate(1, 2);              // ✅ 返回 number
calc.calculate('hello', 'world'); // ✅ 返回 string
calc.calculate(5, 3, 'multiply'); // ✅ 返回 number

2.3 箭头函数的"重载"：接口中的调用签名

箭头函数本身不支持直接重载，但可通过接口或对象类型中的多个调用签名实现等效效果：

// 定义一个支持多种调用方式的函数类型
interface SearchFunc {
  (keyword: string): string[];
  (keyword: string, page: number): string[];
  (keyword: string, page: number, pageSize: number): string[];
}

const search: SearchFunc = (
  keyword: string,
  page?: number,
  pageSize?: number
): string[] => {
  // 实现逻辑
  return ['result1', 'result2'];
};

search('vue');        // ✅
search('vue', 1);     // ✅
search('vue', 1, 10); // ✅

这正是 defineEmits 所采用的模式：在泛型参数中传入一个包含多个调用签名的对象类型，从而让每个事件名都获得独立的类型约束。

---

三、核心辨析：联合类型 vs 重载

许多开发者会困惑：既然联合类型也能表达"多种可能"，为何还需要重载？

本质差异在于调用方的类型体验。

3.1 联合类型的局限

// 联合类型写法：返回值类型被"稀释"
function getLength(value: string | number): string | number {
  if (typeof value === 'string') return value.length;
  return value.toString().length;
}

const result = getLength('hello');
// result 的类型为 string | number，而非精确的 number
// 需要手动类型断言才能进一步操作

3.2 重载的精确推断

// 重载写法：返回值与输入参数精确对应
function getLength(value: string): number;
function getLength(value: number): string;
function getLength(value: string | number): number | string {
  if (typeof value === 'string') return value.length;
  return value.toString().length;
}

const numResult = getLength('hello'); // 类型精确推断为 number
const strResult = getLength(123);       // 类型精确推断为 string

结论 ：当不同参数组合对应不同的返回值类型时，重载能消除调用方的类型不确定性，避免冗余的类型守卫或断言。

---

四、实操步骤：三个典型应用场景

场景一：根据参数类型返回不同结果

function getUser(id: number): User;
function getUser(email: string): User | null;
function getUser(param: number | string): User | null {
  if (typeof param === 'number') {
    return database.findById(param); // 按 ID 查询，必定返回 User
  }
  return database.findByEmail(param); // 按邮箱查询，可能返回 null
}

const user1 = getUser(1);              // 类型: User（无需判空）
const user2 = getUser('a@b.com');      // 类型: User | null（需判空处理）

场景二：Vue 3 的 defineEmits（本文缘起）

const emit = defineEmits<{
  (e: 'update:modelValue', value: string): void;
  (e: 'submit', data: { name: string; age: number }): void;
  (e: 'cancel'): void;
}>();

// 使用时获得完整的类型提示与校验
emit('update:modelValue', 'new value');
emit('submit', { name: 'Alice', age: 25 });
emit('cancel');

场景三：DOM API 风格的字符串字面量分发

function createElement(tag: 'div'): HTMLDivElement;
function createElement(tag: 'span'): HTMLSpanElement;
function createElement(tag: 'input'): HTMLInputElement;
function createElement(tag: string): HTMLElement {
  return document.createElement(tag);
}

const div = createElement('div');     // 类型: HTMLDivElement
const span = createElement('span');   // 类型: HTMLSpanElement
const input = createElement('input'); // 类型: HTMLInputElement

---

五、验证效果：避坑指南与最佳实践

5.1 实现签名必须兼容所有重载

// ❌ 错误示例：实现签名未包含 string 类型
function fn(x: string): void;
function fn(x: number): void;
function fn(x: number): void {} // 编译报错：缺少 string 的处理

5.2 每个重载签名必须有实现支撑

// ❌ 错误示例：仅有重载声明，缺少实现体
function fn(x: string): void; // 报错：函数实现缺失

5.3 避免重载签名之间的类型兼容

// ❌ 反模式：any 包含 string，导致第一个签名永远无法匹配
function fn(x: string): void;
function fn(x: any): void;
// 实际调用时永远匹配第二个签名，第一个签名形同虚设

5.4 关于 @ts-expect-error 的说明

虽然可以用 @ts-expect-error 临时绕过实现签名的严格类型检查，但这会掩盖潜在的类型不一致风险。除非在迁移遗留代码等特殊场景，否则不推荐在生产代码中使用。

---

六、总结

TypeScript 的函数重载并非语法糖，而是一种在编译期建立参数与返回值精确映射 的类型工具。从 Vue 3 的 defineEmits 到复杂的 API 封装，重载让调用方获得了"开箱即用"的类型安全，而无需在运行时承担任何额外开销。

掌握重载的关键在于理解其三层结构：对外暴露的重载签名负责契约，对内的实现签名负责兼容，而调用方享受精确推断。当这一机制运用得当，TypeScript 的类型系统便从"约束"转化为"赋能"，让代码在健壮性与开发体验之间取得平衡。

---

参考文献

1. TypeScript Handbook: Functions - Overloads
2. Vue 3 官方文档：TypeScript with Composition API - Typing Component Emits
3. 《Programming TypeScript》--- Boris Cherny, Chapter 4: Functions