执行契约
- 适用场景
- 团队需要为不同数据类型明确何时新鲜、何时后台更新、何时回收。
- 不要使用
- 不要为掩盖错误 Query Key 或重复 QueryClient 而随意提高 staleTime。
- 前置检查
- 记录数据变化频率、允许陈旧时间、主动失效事件和离线需求。
- 验证结果
- 用可控时间验证 fresh、stale 和 inactive 转换，并测试聚焦与重连后的行为。
- 失败模式
- 意外重新请求先检查默认 stale 状态和聚焦触发；数据不更新再检查是否误用了 static 策略。
- 安全边界
- 注销或权限变化时清理用户作用域缓存，避免在共享浏览器会话中显示前一用户数据。
两个时间轴
staleTime 控制何时允许基于陈旧状态重新获取；gcTime 只控制没有观察者的查询保留多久。不要用很长的 gcTime 代替新鲜度策略，也不要把默认后台重新获取误判为缓存失效。
共享契约
用 queryOptions 共置 queryKey、queryFn 和时间策略。Loader、useQuery、prefetchQuery 与 setQueryData 复用同一函数，保留类型关系并避免键漂移。
import { queryOptions } from '@tanstack/react-query'
export const issuesOptions = queryOptions({
queryKey: ['issues', 'list'] as const,
queryFn: getIssues,
staleTime: 30_000,
gcTime: 5 * 60_000,
})选择规则
从服务端允许多旧、用户能否接受后台刷新、数据是否由当前客户端写入来确定 staleTime。只有明确不需要重新获取时才使用 Infinity；仍需在 Mutation 成功后按资源键精确失效。