如何在React Query与Axios中实现带自定义选项的可复用Mutation Hook

要实现类型安全且灵活的useRegisterByEmail Hook，核心是利用React Query提供的UseMutationOptions泛型类型，结合你的业务类型定义约束自定义选项，同时避免覆盖核心的mutationFn和mutationKey。以下是具体实现步骤和代码示例：

步骤1：导入必要的类型 #

首先确保导入React Query和Axios的相关类型：

import { useMutation, UseMutationOptions } from '@tanstack/react-query';
import axios, { AxiosResponse, AxiosError } from 'axios';

步骤2：定义自定义选项的类型 #

通过Omit排除不希望用户覆盖的核心配置（mutationFn和mutationKey），同时基于你的注册请求的参数、返回值和错误类型，约束UseMutationOptions的泛型参数：

// 基于业务类型定义Mutation选项的类型
type UseRegisterByEmailOptions = Omit<
  UseMutationOptions<
    // mutationFn的返回值类型：Axios响应，包含自定义API响应结构
    AxiosResponse<ApiResponseInterface<RegisterByEmailResultInterface>>,
    // 错误类型：AxiosError，响应数据为自定义错误结构
    AxiosError<ErrorApiResponseInterface>,
    // mutationFn的参数类型：注册请求的Body结构
    RegisterByEmailBodyInterface
  >,
  // 排除不允许用户修改的核心字段
  'mutationFn' | 'mutationKey'
>;

步骤3：修改Hook以接受自定义选项 #

将Hook改为接受可选的options参数，合并默认配置与用户传入的选项：

export const useRegisterByEmail = (options?: Partial<UseRegisterByEmailOptions>) =>
  useMutation({
    mutationFn: registerByEmail,
    mutationKey: ['register'],
    // 合并用户选项，用户传入的配置会覆盖同名默认配置（排除字段除外）
    ...options,
  });

示例用法 #

现在你可以灵活传入自定义选项，比如成功/失败回调、重试策略等，同时享受完整的类型提示：

const { mutate, isLoading } = useRegisterByEmail({
  onSuccess: (response) => {
    // response类型自动推导为AxiosResponse<ApiResponseInterface<RegisterByEmailResultInterface>>
    console.log('注册成功:', response.data.result);
  },
  onError: (error) => {
    // error类型自动推导为AxiosError<ErrorApiResponseInterface>
    console.error('注册失败:', error.response?.data.message);
  },
  retry: 2, // 自定义重试次数
});

// 调用注册
mutate({ email: 'test@example.com', username: 'test', password: '123456' });

关键说明 #

• 使用Omit排除mutationFn和mutationKey，确保核心注册逻辑不会被用户意外覆盖，保证Hook的复用性和一致性。
• 泛型参数完全匹配业务类型，让所有回调函数的参数都有准确的类型提示，避免类型错误。
• 用Partial<>允许用户传入部分选项，无需填写所有配置，提升灵活性。

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