为组合式函数编写重载签名，核心是为其返回值或调用方式提供类型精确性；必须使用具名函数声明（如 function useapi()），配合多个重载签名与一个兼容所有情况的实现签名，并通过参数区分逻辑路径。
为组合式函数（如 useXXX 钩子）编写重载签名，核心不是“给函数本身加重载”，而是**为它的返回值或调用方式提供类型精确性**——尤其当它接受多种参数组合、返回不同结构时。TypeScript 的函数重载机制不适用于箭头函数或 `const useXxx = (...) => {...}` 形式，所以实际做法是：用普通函数声明 + 重载签名 + 实现签名，并把逻辑封装在返回对象中。
重载签名必须绑定到普通函数声明
Vue 组合式函数通常导出为命名函数（非箭头函数），这是支持重载的前提：
- 箭头函数、`const` 声明的函数、`export default` 函数均不支持重载
- 必须用
function useFetch()这种具名函数语法 - 重载签名写在实现签名之前，且不能有函数体
按参数数量和类型差异设计签名
常见场景：一个 useApi 钩子支持「仅 URL」、「URL + 配置」、「URL + 配置 + 选项」三种调用方式，返回类型随之变化：
Galileo TypeScript sdk
下载
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
- 传字符串 → 返回
{ data: Ref<any>, loading: Ref<boolean> }</boolean></any> - 传字符串 + 配置对象 → 返回
{ data: Ref<t>, error: Ref<error null> }</error></t> - 传字符串 + 配置 + 选项 → 返回
{ data: Ref<t>, execute: () => Promise<void> }</void></t>
对应重载签名如下：
function useApi(url: string): { data: Ref<any>; loading: Ref<boolean> };
function useApi<t>(url: string, options: UseApiOptions): { data: Ref<t>; error: Ref<error null> };
function useApi<t>(url: string, options: UseApiOptions, extra: { manual: true }): { data: Ref<t>; execute: () => Promise<void> };</void></t></t></error></t></t></boolean></any>
实现签名要兼容所有重载，且内部做类型守卫
实现签名参数需覆盖全部重载的联合类型，返回类型用 any 或宽泛联合类型（编译器不校验实现签名的返回类型，只校验调用是否匹配重载）：
- 参数类型合并为
string, UseApiOptions?, { manual?: boolean }? - 函数体内用
arguments.length或typeof extra === 'object'区分路径 - 返回值用类型断言或类型收窄确保内部逻辑安全
配合泛型与条件类型提升表达力
纯重载对泛型推导有限制（如无法在重载签名中直接写 <t></t>），可结合条件类型增强返回精度：
- 定义辅助类型：
type UseApiReturn<t m> = M extends true ? { data: Ref<t>; execute: () => Promise<void> } : { data: Ref<t>; error: Ref<error null> };</error></t></void></t></t> - 在实现中根据参数存在性返回对应类型，再用重载签名引导调用侧类型
- 避免把所有逻辑塞进实现签名——重载是给调用者看的契约，实现是内部适配层
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
