如何配置React Query在请求出错时保留数据？onError弃用替代方案

解决方案 #

1. 核心配置：错误时保留现有数据 #

React Query 默认不会清除已有缓存数据，除非主动调用 invalidateQueries 或 removeQueries。如果是切换查询键（比如日期变化）时新请求失败，想要保留之前的成功数据，核心依赖 keepPreviousData: true 配置：

• 该配置会让组件在新查询加载过程中或失败时，始终返回之前查询的成功数据（仅当之前有成功缓存时生效）。
• 若首次请求就失败，data 会是 undefined，需添加加载状态或默认值处理。

2. onError 的正确用法（未弃用，仅需修正写法） #

最新版 TanStack Query 中 onError 并未被弃用，只是需要作为 useQuery 的配置项放在 options 对象内部。如果需要在错误时做额外的手动数据恢复，可结合 useQueryClient 操作缓存。

修正后的完整代码 #

import { useState } from 'react';
import { useQuery, useQueryClient } from '@tanstack/react-query';
import { getDashboard } from '../dashboard/query';

function Dashboard() {
  const [todayDate, setTodayDate] = useState('');
  const queryClient = useQueryClient();

  const { data, isError, isFetching, error } = useQuery({
    queryKey: ['dashboard', { date: todayDate }],
    queryFn: getDashboard,
    keepPreviousData: true, // 切换查询键时保留旧数据，请求失败也不会清空
    retry: false,
    onError: () => {
      // 特殊场景下手动恢复数据（比如非查询键切换的请求失败）
      const lastValidData = queryClient.getQueryData(['dashboard', { date: '' }]);
      if (lastValidData) {
        queryClient.setQueryData(['dashboard', { date: todayDate }], lastValidData);
      }
    },
  });

  // 处理data为undefined的情况，避免强制断言报错
  if (!data) {
    return <div>加载中或暂无数据</div>;
  }

  return (
    <div>
      {isError && error && <div>{error.message}</div>}
      <div>{data.data.name}</div>
    </div>
  );
}

关键说明 #

• keepPreviousData: true：这是保留旧数据的核心配置，切换查询键时，新请求失败后data仍会保留之前的成功数据，直到新请求成功才更新。
• 避免强制断言：不要用data!强制跳过空值检查，先判断data是否存在，否则会在首次请求失败时抛出错误。
• 手动缓存操作：仅在特殊场景下需要手动恢复数据，比如非查询键切换导致的请求失败，可通过queryClient读写缓存。

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