---
id: query.freshness-policy
kind: contract
product: query
framework: react
locale: zh-CN
revision: 2
sourceCheckedOn: "2026-08-03"
versionRange: "^5"
verifiedAgainst: "@tanstack/react-query@5.101.4"
contentModel: 2
packages:
  - "@tanstack/react-query"
tasks:
  - "configure-stale-time"
  - "configure-gc-time"
  - "share-query-options"
sourceRefs:
  - "https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults"
  - "https://tanstack.com/query/latest/docs/framework/react/guides/query-options"
---

# 定义 Query 新鲜度契约

> 根据数据变化频率设置 staleTime，并独立决定 inactive 缓存的 gcTime。

## 执行契约

- **适用场景:** 团队需要为不同数据类型明确何时新鲜、何时后台更新、何时回收。
- **不要使用:** 不要为掩盖错误 Query Key 或重复 QueryClient 而随意提高 staleTime。
- **前置检查:** 记录数据变化频率、允许陈旧时间、主动失效事件和离线需求。
- **验证结果:** 用可控时间验证 fresh、stale 和 inactive 转换，并测试聚焦与重连后的行为。
- **失败模式:** 意外重新请求先检查默认 stale 状态和聚焦触发；数据不更新再检查是否误用了 static 策略。
- **安全边界:** 注销或权限变化时清理用户作用域缓存，避免在共享浏览器会话中显示前一用户数据。

## 两个时间轴

staleTime 控制何时允许基于陈旧状态重新获取；gcTime 只控制没有观察者的查询保留多久。不要用很长的 gcTime 代替新鲜度策略，也不要把默认后台重新获取误判为缓存失效。

## 共享契约

用 queryOptions 共置 queryKey、queryFn 和时间策略。Loader、useQuery、prefetchQuery 与 setQueryData 复用同一函数，保留类型关系并避免键漂移。

File: `src/features/issues/queries.ts`

```ts
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 成功后按资源键精确失效。

## Official sources

- https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults
- https://tanstack.com/query/latest/docs/framework/react/guides/query-options