如何为React Query useMutation Hook传递正确的TypeScript类型？

核心问题 #

useMutation无法自动处理联合类型的mutation函数，因为它要求单一明确的参数（TVariables）和返回值（TData）类型签名，联合类型会导致重载匹配失败。

解决方案1：拆分useMutation实例（推荐） #

根据provider的不同，分别创建对应类型的useMutation实例，彻底避免联合类型的歧义：

// 定义独立的mutation函数（提前拆分类型）
const fetchRedirectUrl = (param: string): Promise<RedirectUrl | null> => {
  // 你的请求逻辑
};

const fetchDomainList = (param: DomainList): Promise<ZeusResponseSingle<DomainList> | null> => {
  // 你的请求逻辑
};

// 分别初始化useMutation
const { mutate: mutateRedirect } = useMutation(fetchRedirectUrl);
const { mutate: mutateDomain } = useMutation(fetchDomainList);

// 使用时根据provider分支调用
if (provider === 'redirect-provider') {
  mutateRedirect('your-string-param');
} else {
  mutateDomain(yourDomainListParam);
}

这种方式类型最安全，代码逻辑清晰，完全符合TypeScript的类型检查规则。

解决方案2：手动指定useMutation泛型参数 #

如果必须使用单个useMutation实例，可手动指定泛型的参数和返回值联合类型，同时配合类型守卫确保调用时参数类型正确：

// 定义联合类型
type MutationVariables = string | DomainList;
type MutationData = (RedirectUrl | null) | (ZeusResponseSingle<DomainList> | null);

// 根据provider获取mutation函数
const appUrlMethod = provider === 'redirect-provider' 
  ? fetchRedirectUrl 
  : fetchDomainList;

// 手动指定useMutation的泛型参数（顺序：TData, TError, TVariables, TContext）
const { mutate } = useMutation<MutationData, unknown, MutationVariables>(appUrlMethod);

// 调用时必须用类型守卫约束参数类型
if (provider === 'redirect-provider') {
  mutate('your-string-param'); // TypeScript自动识别参数为string
} else {
  mutate(yourDomainListParam); // TypeScript自动识别参数为DomainList
}

解决方案3：类型断言（不推荐，仅应急使用） #

如果以上方法都不适用，可通过类型断言强制指定mutation函数的类型，但会失去部分类型检查安全性：

const appUrlMethod = provider === 'redirect-provider' 
  ? fetchRedirectUrl 
  : fetchDomainList;

// 根据provider断言为对应类型的函数
const typedMutationFn = provider === 'redirect-provider'
  ? (appUrlMethod as (param: string) => Promise<RedirectUrl | null>)
  : (appUrlMethod as (param: DomainList) => Promise<ZeusResponseSingle<DomainList> | null>);

const { mutate } = useMutation(typedMutationFn);

内容的提问来源于stack exchange，提问作者Dev9999