查询重试

在 TanStack Query 中，当查询函数抛出错误时，系统会自动重试查询，直到达到最大连续重试次数（默认为 3 次），或者提供一个函数来确定是否允许重试。

配置查询重试

您可以在全局级别和单个查询级别进行配置。

• 禁用重试：设置 retry = false 会禁用重试。

• 设置最大重试次数：设置 retry = 6 会在失败请求重试 6 次后才会显示最终的错误。

• 无限重试：设置 retry = true 会无限重试失败的请求。

• 自定义重试逻辑：设置 retry = (failureCount, error) => ... 可以根据请求失败的原因自定义重试逻辑

在服务器端，默认的重试次数为 0，以确保服务器渲染尽可能快。

示例：指定重试次数。

import { useQuery } from "@tanstack/react-query";

const result = useQuery({
  queryKey: ["todos", 1],
  queryFn: fetchTodoListPage,
  retry: 10 // 会重试失败的请求 10 次，直到出现错误
});

Info：在每次重试时，错误内容将成为 failureReason 响应属性的一部分，直到最后一次重试。如果错误在所有重试尝试后依然存在，则错误会成为 error 属性。

重试延迟（Retry Delay）

默认情况下，在 TanStack Query 中，重试请求并不会立即发生。标准的做法是在每次重试时应用逐步递增的延迟。

默认的 retryDelay 设置是每次重试的延迟时间以双倍的方式增加（从 1000ms 开始），但最大不会超过 30 秒。

示例：全局配置重试延迟

import { QueryCache, QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000)
    }
  }
});

function App() {
  return <QueryClientProvider client={queryClient}>...</QueryClientProvider>;
}

覆盖重试延迟

虽然不推荐，您也可以在查询的 Provider 和单个查询选项中覆盖 retryDelay 函数或整数。如果设置为整数，则延迟将始终是相同的时间，而不管重试次数如何。

示例：指定固定的重试延迟

const result = useQuery({
  queryKey: ["todos"],
  queryFn: fetchTodoList,
  retryDelay: 1000 // 每次重试都会等待 1000ms
});