本技能聚焦 TanStack Query 的默认配置与数据新鲜度调优，帮助开发者正确设置缓存、重试与重新获取行为。
用途 用于在 React 应用中配置 QueryClient 的全局默认选项，以及针对单个查询设置新鲜度、缓存生命周期、重试策略、窗口聚焦/重连/定时重新获取和网络模式。
主要能力
- 全局默认配置：通过 new QueryClient({ defaultOptions: { queries: { ... } } }) 设置 staleTime、gcTime、retry、refetchOnWindowFocus 等。
- 按查询设置新鲜度：使用 queryOptions 为具体查询指定 staleTime，使新鲜度贴近数据源。
- 测试环境禁用重试：创建测试用 QueryClient，设置 retry: false，避免失败测试因默认重试延迟而挂起。
- 显式使用 networkMode：在 queryOptions 中设置 networkMode: 'online' 等，明确控制网络行为。
使用方式 示例代码展示了三种核心模式：
- 全局默认： import { QueryClient } from '@tanstack/react-query' export const queryClient = new QueryClient({ defaultOptions: { queries: { staleTime: 60_000, gcTime: 10 * 60_000, retry: 2, refetchOnWindowFocus: true, }, }, })
- 按查询设置新鲜度： import { queryOptions } from '@tanstack/react-query' export const settingsOptions = queryOptions({ queryKey: ['settings'], queryFn: async () => ({ theme: 'system' }), staleTime: 5 * 60_000, })
- 测试禁用重试： import { QueryClient } from '@tanstack/react-query' export function createTestQueryClient() { return new QueryClient({ defaultOptions: { queries: { retry: false } }, }) }
- 显式网络模式： import { queryOptions } from '@tanstack/react-query' export const metricsOptions = queryOptions({ queryKey: ['metrics'], queryFn: async () => ({ count: 1 }), networkMode: 'online', })
常见错误
- 混淆 gcTime 与 freshness：gcTime 控制未使用缓存的保留时间，staleTime 控制缓存数据是否被视为新鲜。错误示例在 useQuery 中设置 gcTime: 60_000，正确做法是设置 staleTime: 60_000。
- 静态 staleTime 阻止失效预期：staleTime: 'static' 会使查询即使被失效也不重新获取。应使用具体毫秒值，如 staleTime: 60_000。
- 测试因重试挂起：默认重试会增加延迟，导致失败测试在暴露错误前等待。应在测试 QueryClient 中设置 retry: false。
适用场景
- 需要统一管理多个查询的缓存与重试行为。
- 根据数据源特性调整新鲜度，例如设置较长的 staleTime 减少请求。
- 编写稳定的单元测试或集成测试，避免重试导致的超时。
- 需要明确控制在线/离线网络模式下的查询行为。
限制 资料未提供关于具体版本兼容性、性能影响、与其他库集成或收费信息的说明。