查询重试
当 injectQuery 查询失败(查询函数抛出错误)时,若该查询请求尚未达到连续重试次数上限(默认为 3 次),或你提供了用于判断是否允许重试的函数,TanStack Query 将自动重试该查询。
你可以在全局层面和单个查询层面分别配置重试行为。
- 设置
retry = false将禁用重试。 - 设置
retry = 6将在显示查询函数最终抛出的错误前,重试失败的请求 6 次。 - 设置
retry = true将无限次重试失败的请求。 - 设置
retry = (failureCount, error) => ...可基于请求失败原因实现自定义逻辑。注意:failureCount在首次重试尝试时从0开始计数。
TypeScript
1import { injectQuery } from '@tanstack/angular-query-experimental'2 3// Make a specific query retry a certain number of times4const todoQuery = injectQuery(() => ({5 queryKey: ['todos', 1],6 queryFn: fetchTodoListPage,7 retry: 10, // Will retry failed requests 10 times before displaying an error8}))说明:
error属性的内容将在injectQuery的failureReason响应属性中持续存在,直至最后一次重试尝试。因此,在上述示例中,任何错误内容将在前 9 次重试尝试(总计 10 次尝试)期间作为failureReason属性的一部分;若所有重试尝试后错误依然存在,则最终错误内容将归入error属性。
重试延迟
默认情况下,TanStack Query 的重试不会在请求失败后立即执行。与标准实践一致,每次重试尝试都会逐步应用退避延迟(back-off delay)。
默认 retryDelay 设置为每次尝试时延迟时间翻倍(起始值为 1000ms),但不超过 30 秒:
TypeScript
1// Configure for all queries2import {3 QueryCache,4 QueryClient,5 provideTanStackQuery,6} from '@tanstack/angular-query-experimental'7 8const queryClient = new QueryClient({9 defaultOptions: {10 queries: {11 retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),12 },13 },14})15 16bootstrapApplication(AppComponent, {17 providers: [provideTanStackQuery(queryClient)],18})尽管不推荐,你仍可在插件(Plugin)和单个查询选项中显式覆盖 retryDelay(函数或整数值)。若将其设为整数而非函数,则每次重试延迟时间将保持恒定:
TypeScript
1const todosQuery = injectQuery(() => ({2 queryKey: ['todos'],3 queryFn: fetchTodoList,4 retryDelay: 1000, // Will always wait 1000ms to retry, regardless of how many retries5}))后台重试行为
当使用 refetchInterval 并启用 refetchIntervalInBackground: true 时,若浏览器标签页处于非活跃状态,重试将暂停。这是因为重试遵循与常规重新拉取(refetch)相同的焦点行为(focus behavior)。
如果你需要后台持续重试,请考虑禁用重试并实现自定义的重新拉取策略:
TypeScript
1const result = injectQuery({2 queryKey: ['todos'],3 queryFn: fetchTodos,4 refetchInterval: (query) => {5 // Refetch more frequently when in error state6 return query.state.status === 'error' ? 5000 : 300007 },8 refetchIntervalInBackground: true,9 retry: false, // Disable built-in retries10})该方法使你能够手动控制重试时机,同时确保后台的重新拉取保持活跃。