将React Query Hooks封装到TypeScript类中是否合规可行？

问题背景 #

你尝试将React Query Hooks封装到TypeScript类中，实现查询与 mutation 的分类管理，当前代码运行无报错，但担心是否违反React Hooks规则，或未来引发问题，同时想了解是否有更合适的函数式封装方案。

你的类封装实现示例：

const keys = {
  receipts: (filter?: ReceiptFilter) => ['receipts', filter],
  receipt: (id: string) => ['receipt', id]
};

class ReceiptQueries {
  public useReceipts = (filter?: ReceiptFilter) => {
    const dispatch = useDispatch();
    return useQuery({
      queryKey: keys.receipts(filter),
      queryFn: () => ReceiptApi.getReceipts(filter),
    });
  }

  public useReceipt = (id: string) => {
    return useQuery({
      queryKey: keys.receipt(id),
      queryFn: () => ReceiptApi.getReceipt(id),
    });
  }

  public useAddReceiptMutation = () => {
    const queryClient = useQueryClient();
    return useMutation({
      mutationFn: ({ receipt }) => ReceiptApi.addReceipt(receipt),
      onSuccess: () => {
        queryClient.invalidateQueries(keys.receipts());
      }
    });
  }

  public useUpdateReceiptMutation = () => {
    return useMutation({
      mutationFn: ({ receipt }) => ReceiptApi.updateReceipt(receipt),
    });
  }

  public useDeleteReceiptMutation = () => {
    return useMutation({
      mutationFn: ({ receiptId }) => ReceiptApi.deleteReceipt(receiptId),
    });
  }
}

export default new ReceiptQueries();

组件调用方式：

import ReceiptQueries from 'ReceiptQueries'

const App: React.FC = () => {
  const { data: allReceipts } = ReceiptQueries.useReceipts();

  return (
    <div>
      {allReceipts?.map(receipt => <div key={receipt.id}>{receipt.title}</div>)}
    </div>
  )
}

类封装方案的风险 #

虽然当前代码能正常运行，但它不符合React Hooks的核心规则，存在潜在问题：

• React要求Hooks只能在React函数组件或自定义Hooks的顶层调用，而类的方法本质是挂载在单例实例上的函数，并非标准的自定义Hooks（自定义Hooks必须是独立的、以use开头的函数）。
• 未来React可能强化Hooks的校验逻辑（比如StrictMode下的重复渲染检测、DevTools的规则校验），这种非标准用法可能触发警告或直接报错。
• 类实例是全局单例，若后续在类中添加状态逻辑，可能出现跨组件状态共享的意外问题。

推荐的函数式分类封装方案 #

如果你偏好分类管理的方式，完全可以用命名空间式的函数分组来实现，既满足分类需求，又严格遵守Hooks规则：

实现示例 #

// receiptQueries.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { useDispatch } from 'react-redux';
import ReceiptApi from './receiptApi';
import type { ReceiptFilter } from './types';

// 统一管理Query Keys
const keys = {
  receipts: (filter?: ReceiptFilter) => ['receipts', filter],
  receipt: (id: string) => ['receipt', id]
};

// 分类定义合法的自定义Hooks
export const useReceipts = (filter?: ReceiptFilter) => {
  const dispatch = useDispatch();
  return useQuery({
    queryKey: keys.receipts(filter),
    queryFn: () => ReceiptApi.getReceipts(filter),
  });
};

export const useReceipt = (id: string) => {
  return useQuery({
    queryKey: keys.receipt(id),
    queryFn: () => ReceiptApi.getReceipt(id),
  });
};

export const useAddReceiptMutation = () => {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: ({ receipt }) => ReceiptApi.addReceipt(receipt),
    onSuccess: () => {
      queryClient.invalidateQueries(keys.receipts());
    }
  });
};

export const useUpdateReceiptMutation = () => {
  return useMutation({
    mutationFn: ({ receipt }) => ReceiptApi.updateReceipt(receipt),
  });
};

export const useDeleteReceiptMutation = () => {
  return useMutation({
    mutationFn: ({ receiptId }) => ReceiptApi.deleteReceipt(receiptId),
  });
};

// 可选：导出统一的对象，保持和原类封装一致的调用方式
const ReceiptQueries = {
  useReceipts,
  useReceipt,
  useAddReceiptMutation,
  useUpdateReceiptMutation,
  useDeleteReceiptMutation
};

export default ReceiptQueries;

组件调用 #

和你原来的调用方式完全一致：

import ReceiptQueries from './receiptQueries'

const App: React.FC = () => {
  const { data: allReceipts } = ReceiptQueries.useReceipts();

  return (
    <div>
      {allReceipts?.map(receipt => <div key={receipt.id}>{receipt.title}</div>)}
    </div>
  )
}

总结 #

• 类封装方案存在合规性风险，不建议长期使用；
• 函数式分类封装既满足了你对分类管理的需求，又完全符合React Hooks规则，是更稳妥、可维护的方案。

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