TypeScript 函数重载：2025 年指南与示例

TypeScript 函数重载：为什么这不是“魔法”，而是智能代码的工具

如果你曾经用 JavaScript 编写过一个接受“字符串、数字甚至数组”的函数，你就会知道这个令人不快的时刻：函数内部是 if 语句的地狱，而外部对于调用该函数的人来说则完全不确定。TypeScript 优雅地解决了这个问题，但并不总是显而易见。函数重载 不是创建多个同名函数（就像在 Java 或 C++ 中那样）。而是为一个实现声明多个签名。

在 2025 年，当 TypeScript 已成为严肃前端和后端项目的事实标准时，熟练配置重载不仅仅是一个“技巧”，而是一项使你的代码可读、类型安全且对团队友好的技能。让我们深入了解它是如何工作的，新手常在哪里犯错，以及哪些模式值得采用。

函数重载到底是什么？

想象一下，你正在编写一个 formatDate 函数。它应该能够：

\n
• 接受一个 Date 对象并返回一个字符串。
\n
• 接受一个 ISO 格式的字符串并返回一个字符串。
\n
• 接受一个数字（时间戳）并返回一个字符串。
\n

如果只是简单地写成 function formatDate(input: Date | string | number): string，TypeScript 将无法提示你在特定调用中传递的具体类型。IDE 将显示通用类型，你将失去自动补全功能。重载解决了这个问题：

// 重载签名\nfunction formatDate(input: Date): string;\nfunction formatDate(input: string): string;\nfunction formatDate(input: number): string;\n\n// 实现签名\nfunction formatDate(input: Date | string | number): string {\n    if (input instanceof Date) {\n        return input.toISOString();\n    } else if (typeof input === 'string') {\n        return new Date(input).toISOString();\n    } else {\n        return new Date(input).toISOString();\n    }\n}

现在，当你调用 formatDate(new Date()) 时，TypeScript 知道返回的是 string，并会提示类型。没有魔法——只有严格的类型检查。

规则 #1：重载签名不能是实现

新手最常见的错误是试图在每个签名中编写函数体。不要这样做：

// ❌ 错误：重复实现\nfunction foo(x: number): number {\n    return x * 2;\n}\nfunction foo(x: string): string {\n    return x.toUpperCase();\n}

TypeScript 不支持多个同名实现。始终是一个实现，多个声明。

规则 #2：签名的顺序很重要

TypeScript 从上到下检查签名。第一个匹配的签名决定了返回类型。因此：

\n
• 将更具体的类型放在上面（例如，string 在 any 之前）。
\n
• 避免可能混淆编译器的重叠签名。
\n

// 良好：先处理具体情况\nfunction createButton(label: string, disabled?: boolean): HTMLButtonElement;\nfunction createButton(options: { label: string; disabled?: boolean }): HTMLButtonElement;\nfunction createButton(labelOrOptions: string | { label: string; disabled?: boolean }, disabled?: boolean): HTMLButtonElement {\n    // 实现\n}

规则 #3：如果签名超过 3 个，请使用联合类型

重载是一个强大的工具，但不要滥用它。如果你有 5 个以上的签名，代码将变得难以阅读。在 2025 年，一个好的实践是：

\n
• 最多 3 个签名——使用重载。
\n
• 超过 3 个——考虑使用 联合类型 或