如何在React Query中以命令式方式处理错误？

这个问题我之前也踩过坑！核心原因就是组件每次重渲染时，只要isError状态保持为true，你的if (isError)代码块就会反复执行，自然会出现重复弹窗的问题。下面给你几个靠谱的解决方案，按需选择：

利用React的useEffect钩子，只在错误状态首次触发时执行命令式操作。通过把isError和error加入依赖数组，确保只有当错误状态真正发生变化（比如从加载/成功转为错误）时才触发：

function Todos() {
  const { isLoading, isError, data, error } = useQuery('todos', fetchTodoList);

  useEffect(() => {
    // 只在错误存在且是新错误时执行
    if (isError && error) {
      alert(`An error has occurred: ${error.message}`);
    }
  }, [isError, error]);

  if (isLoading) {
    return <span>Loading...</span>;
  }

  if (isError) {
    // 这里可以保留基础的错误UI，或者返回null，根据你的需求来
    return <span>Oops, something went wrong!</span>;
  }

  return (
    <ul>
      {data.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  );
}

这是最贴合React Query设计思路的方案！useQuery的配置项里自带onError回调，它只会在请求首次失败时触发一次，完全不会因为组件重渲染而重复执行：

function Todos() {
  const { isLoading, data } = useQuery('todos', fetchTodoList, {
    onError: (error) => {
      // 这里放你的命令式错误逻辑，比如弹窗、上报等
      alert(`An error has occurred: ${error.message}`);
    },
  });

  if (isLoading) {
    return <span>Loading...</span>;
  }

  // 如果请求失败，data会是undefined，这里可以渲染基础错误UI
  if (!data) {
    return <span>Oops, something went wrong!</span>;
  }

  return (
    <ul>
      {data.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  );
}

我个人最推荐这个方案，代码更简洁，也不需要额外处理状态监听的逻辑。

如果你的项目里多个组件都需要这种一次性的命令式错误处理，可以封装一个自定义Hook，把逻辑抽离出来：

import { useQuery, useRef, useEffect } from '@tanstack/react-query';

function useQueryWithImperativeError(queryKey, queryFn, onErrorCallback) {
  const queryResult = useQuery(queryKey, queryFn);
  const prevErrorRef = useRef(null);

  useEffect(() => {
    // 只有当新错误出现时才执行回调
    if (queryResult.isError && queryResult.error !== prevErrorRef.current) {
      onErrorCallback(queryResult.error);
      prevErrorRef.current = queryResult.error;
    }
  }, [queryResult.isError, queryResult.error, onErrorCallback]);

  return queryResult;
}

// 使用示例
function Todos() {
  const { isLoading, data } = useQueryWithImperativeError(
    'todos',
    fetchTodoList,
    (error) => {
      alert(`An error has occurred: ${error.message}`);
    }
  );

  if (isLoading) {
    return <span>Loading...</span>;
  }

  if (!data) {
    return <span>Oops, something went wrong!</span>;
  }

  return (
    <ul>
      {data.map(todo => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  );
}

这个Hook用useRef记录上一次的错误对象，确保同一个错误不会被重复处理，适合在多个组件中复用相同的错误处理逻辑。

快速选择指南 #

• 单个查询的命令式错误处理：优先用方案2，最省心。
• 需要在组件内结合其他状态处理错误：用方案1，灵活性更高。
• 多个组件需要重复逻辑：用方案3，减少代码冗余。

内容的提问来源于stack exchange，提问作者i.brod