用TanStack Query实现React客户端缓存
把TanStack Query当作客户端server-state缓存:缓存API、请求去重、自动refetch、统一管理loading/error。
聚焦 TanStack Query 在 React 中的简单理解与实际应用,特别是客户端缓存。
TL;DR: @tanstack/react-query 不只是一个调用 API 的库。它可以充当客户端 server-state 缓存,缓存 API 数据、避免重复请求、按需自动 refetch,并非常方便地管理 loading/error 状态。
问题:重复的 API 请求#
在构建 React 应用时,我们经常会遇到一个很普遍的问题:
API 已经返回数据了,下次还需要再调一次 API 吗?
比如一个页面有这样一个 API:
GET /api/users/123text如果组件 A 调用了这个 API,之后组件 B 也需要用户 123 的信息,传统做法可能导致两个组件都调 API。
这就产生了多余的请求。
一种解法是自己造缓存:
const cache = new Map()ts但当应用变大,自己管理缓存很快就会变得复杂。
这时 TanStack Query 就派上用场了。
TanStack Query 是什么?#
TanStack Query(以前常被称为 React Query)是专门管理前端server state 的库。
React 用的包是:
npm install @tanstack/react-querybash关键在于:
TanStack Query 不单纯是一个
fetch()API 库。
它提供了一整套机制:
- 拉取数据
- 缓存数据
- 请求去重
- 数据 refetch
- 请求重试
- 管理 loading/error
- 缓存失效
- 乐观更新
- 分页
- 无限查询
- 后台 refetch
Server State 和 Client State 有什么区别?#
这是理解 TanStack Query 最重要的概念。
Client State#
属于 UI/应用自身的状态。
例如:
const [isOpen, setIsOpen] = useState(false)tsx或者:
const [theme, setTheme] = useState("dark")tsx这些数据属于前端自己。
Server State#
来自后端的数据。
例如:
{
"id": 123,
"name": "John",
"email": "john@example.com"
}json前端并不真正拥有这些数据。
后端才是数据源头。
TanStack Query 主要就是为解决这类状态而设计的。
[!NOTE] ELI5 一下:Client State 好比你家的电灯开关 —— 完全由你控制开和关。Server State 好比户外的天气 —— 你只能透过窗户(API)去”看”,并不拥有它,而且它随时可能变化。
不要把 TanStack Query 和 Redux 搞混#
一个简单的理解:
Redux/Zustand
↓
Client State
TanStack Query
↓
Server Statetext例如:
{
sidebarOpen: true,
theme: "dark"
}ts适合用 Zustand/Redux。
而:
{
users: [...],
posts: [...],
products: [...],
profile: {...}
}ts如果数据来自 API,TanStack Query 通常更合适。
当然两种状态可以在一个应用中共存。
缓存是如何工作的?#
例如:
const { data } = useQuery({
queryKey: ["user", userId],
queryFn: () => fetchUser(userId),
})tsxTanStack Query 用:
queryKeyts来确定缓存的是哪一份数据。
例如:
["user", 123]text和:
["user", 456]text是两个不同的缓存条目。
可以这样想象:
Query Cache
"user", 123
↓
{ id: 123, name: "John" }
"user", 456
↓
{ id: 456, name: "Alice" }
"posts", 123
↓
[ ... ]text[!TIP] 可以把
queryKey想象成超市储物柜的号码:每个 key 只打开一个格子,存一份数据。key 不同 → 格子不同,永远不会混。
基础示例#
首先创建 QueryClient。
import {
QueryClient,
QueryClientProvider,
} from "@tanstack/react-query"
const queryClient = new QueryClient()
export function App() {
return (
<QueryClientProvider client={queryClient}>
<MyApp />
</QueryClientProvider>
)
}tsx然后使用 query:
import { useQuery } from "@tanstack/react-query"
function UserProfile({ userId }: { userId: number }) {
const { data, isPending, error } = useQuery({
queryKey: ["user", userId],
queryFn: () => fetch(`/api/users/${userId}`).then(res => res.json()),
})
if (isPending) {
return <div>Loading...</div>
}
if (error) {
return <div>Error</div>
}
return <div>{data.name}</div>
}tsx值得注意的是:
queryKey: ["user", userId]ts正是缓存的 identity。
[!NOTE] 从 TanStack Query v5 开始,初始加载状态是
isPending(取代 v4 的isLoading),cacheTime改名为gcTime。本文示例使用 v5 API。
当第二个组件调用同一个 API#
假设组件 A 里有:
<UserProfile userId={123} />tsx之后组件 B 也用了:
<UserProfile userId={123} />tsxTanStack Query 知道:
["user", 123]text已经存在于 Query Cache 中。
因此组件 B 能立刻看到已有数据,而不是一片空白的 loading。
这是 TanStack Query 的一大优势。
[!NOTE] 默认
staleTime是0,即缓存数据被立刻视为过期。组件 B 依然能瞬间看到旧数据(无 loading),同时 TanStack Query 在后台 refetch 更新 —— 这种模式叫 stale-while-revalidate。
请求去重#
一个很常见的场景:
组件A ─┐
│
组件B ─┼──→ GET /api/user/123
│
组件C ─┘text如果三个组件几乎同时挂载,你肯定不想发出:
GET /api/user/123
GET /api/user/123
GET /api/user/123textTanStack Query 有基于 query key 共享/去重请求的机制。
概念上:
staleTime —— 数据多久之后算旧?#
这是一个非常重要的选项。
例如:
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60_000,
})tsx意思是数据被视为 60 秒内是新鲜的。
在这期间,如果别的组件使用:
["users"]tsTanStack Query 可以直接用当前缓存,而不是立刻 refetch。
例如:
00秒 API请求
↓
缓存
10秒 组件B
↓
用缓存
30秒 组件C
↓
用缓存
60秒 缓存变旧textstaleTime 不是缓存删除时间#
这是一个非常普遍的误解。
例如:
staleTime: 60_000ts并不是指:
60 秒后缓存被删除。
而是指:
60 秒后,数据被视为过期。
数据仍可能留在缓存里。
[!WARNING] 学 TanStack Query 时最常见的误解:
staleTime是”数据保鲜多久”,而不是”缓存存活多久”。staleTime过期后数据只是被标记为旧 —— 下次使用时会后台 refetch,但缓存并不会被删除。
gcTime#
TanStack Query 还有:
gcTimets以前常被称为:
cacheTimetext它关系到不再被使用的数据在被垃圾回收前保留多久。
例如:
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60_000,
gcTime: 5 * 60_000,
})tsx可以简单理解为:
staleTime
↓
数据多久之内算新鲜?
gcTime
↓
不活跃的缓存保留多久?text这是两个不同的概念。
[!NOTE] 默认值:
staleTime为0(立刻过期),gcTime为 5 分钟(最后一个组件卸载后,不活跃缓存保留 5 分钟)。新手遇到的大多数”奇怪”行为,都可以用这两个数字解释。
一个实际的配置#
例如商品 API:
const productsQuery = useQuery({
queryKey: ["products"],
queryFn: fetchProducts,
staleTime: 5 * 60 * 1000,
gcTime: 30 * 60 * 1000,
})tsx可以理解为:
5分钟
↓
数据视为新鲜
30分钟
↓
不活跃缓存可能被垃圾回收text这对很少变化的数据特别有用。
例如:
- 国家列表
- 分类
- 学校列表
- 配置
- 商品目录
- 主数据
[!TIP] 经验法则:数据越少变化,
staleTime越长。国家列表可以用staleTime: Infinity;实时价格表则用几秒或 refetch interval。
缓存不等于数据永远最新#
这一点非常重要。
假设:
后端
↓
User name = "John"text前端缓存:
User name = "John"text之后服务端变了:
后端
↓
User name = "Mike"text前端缓存里可能还是:
Johntext所以客户端缓存永远存在 trade-off:
性能
↕
新鲜度text想减少 API 请求:
staleTime ↑text想数据频繁更新:
staleTime ↓text数据 refetch#
TanStack Query 可以在多种情况下 refetch。
例如用户回到浏览器标签页时:
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
refetchOnWindowFocus: true,
})tsx概念:
这让应用感觉数据永远是最新的,而开发者不用自己写事件监听。
[!NOTE]
refetchOnWindowFocus默认就是true—— 容易让人吃惊的 “important defaults” 之一:切个标签页回来应用就自己调 API 了。如果在 DevTools 里看到”神秘”请求,很可能就是它。
缓存失效#
做 CRUD 时非常有用的功能。
例如:
GET /users
POST /userstext创建用户后:
await createUser(data)ts可以 invalidate:
queryClient.invalidateQueries({
queryKey: ["users"],
})tsTanStack Query 就知道查询:
["users"]text已经变旧,可以 refetch。
流程:
Mutation#
TanStack Query 也有 useMutation()。
const mutation = useMutation({
mutationFn: createUser,
})tsx使用:
mutation.mutate({
name: "John",
})tsx完整示例:
const queryClient = useQueryClient()
const mutation = useMutation({
mutationFn: createUser,
onSuccess: () => {
queryClient.invalidateQueries({
queryKey: ["users"],
})
},
})tsx这是很常见的模式:
乐观更新#
更高级的功能是乐观更新(Optimistic Update)。
例如用户点击:
❤️ 点赞text与其:
点击
↓
API请求
↓
服务端响应
↓
更新UItext可以这样做:
点击
↓
立刻更新UI
↓
API请求
↓
成功 → 保持
失败 → 回滚text用户会觉得应用更快。
例如:
这是手写缓存/状态管理会迅速变复杂的使用场景之一。
TanStack Query 会把缓存存到 LocalStorage 吗?#
默认:
不会。
Query cache 主要在内存里。
例如:
浏览器
└─JavaScript内存
└─TanStack Query Cachetext刷新页面:
F5
↓
JavaScript内存丢失
↓
Query缓存丢失text如果想持久化缓存,TanStack Query 可以结合持久化机制,例如:
localStorage
IndexedDBtext来打造持久缓存。
这适合想在刷新/离线后保留部分 server state 的应用。
TanStack Query 是 HTTP 缓存吗?#
不要把这两者混为一谈。
至少有两个不同的缓存层:
浏览器 / HTTP缓存
↓
HTTP响应缓存
TanStack Query
↓
应用层server-state缓存text例如:
TanStack Query 理解的是:
queryKey
staleTime
invalidation
mutation
query statets而 HTTP 缓存基于 HTTP 机制,例如:
Cache-Control
ETag
Last-Modified
Agetext两套系统可以协同工作。
和手写缓存对比#
不用 TanStack Query:
const cache = new Map()
async function getUser(id: number) {
if (cache.has(id)) {
return cache.get(id)
}
const data = await fetch(`/api/users/${id}`)
.then(res => res.json())
cache.set(id, data)
return data
}ts初看很简单。
但之后你必须解决:
❓ 缓存多久?
❓ 何时过期?
❓ 何时refetch?
❓ 重试?
❓ Loading?
❓ Error?
❓ 去重?
❓ Mutation?
❓ 失效?
❓ 分页?
❓ 无限滚动?
❓ 乐观更新?
❓ 垃圾回收?
❓ 并发请求?
❓ 离线?text这时最初简单的 Map() 已经变成了一套完整的缓存系统。
TanStack Query 解决了其中大部分问题。
TanStack Query vs Zustand#
典型的 React 架构可以同时用两者:
Zustand 示例:
{
sidebarOpen: true,
selectedTheme: "dark"
}tsTanStack Query:
{
users: [...],
posts: [...],
profile: {...}
}ts不必二选一。
TanStack Query vs SWR#
React/Next.js 中另一个流行的选择是 SWR。
两者的概念很相似:
React
├─TanStack Query
└─SWRtext都解决:
- 拉取
- 缓存
- 重新验证
- server state
TanStack Query 通常提供更完整的 query/mutation 体系和 server state 管理能力,而 SWR 的 API 相当精简。
所以如果应用中有大量:
CRUD
Mutation
分页
无限查询
乐观更新
缓存失效
复杂Server Statetext那么 TanStack Query 值得考虑。
什么时候该用 TanStack Query?#
TanStack Query 特别适合:
Dashboard
管理后台
电商
CRM
SaaS
社交网络
医疗应用
教育平台text特别是 API 很多的应用。
例如:
/users
/users/:id
/courses
/courses/:id
/students
/students/:id
/reports
/notificationstext与其每个组件自己管理:
fetch
loading
error
cache
refetchtext不如交给 TanStack Query 管理 server state。
什么时候不一定需要 TanStack Query?#
如果应用极其简单:
const [data, setData] = useState()
useEffect(() => {
fetch("/api/data")
.then(...)
}, [])tsx只有几个 API 请求,加一个库可能没什么收益。
同样,如果框架已经提供了很强的服务端数据获取/缓存机制,且应用主要用 server components,就要在引入客户端 query 库之前先考虑整体架构。
一个实际的架构#
对于大型 React SPA,可以这样组织:
src/
├─api/
│ ├─users.ts
│ ├─courses.ts
│ └─reports.ts
├─queries/
│ ├─users.ts
│ ├─courses.ts
│ └─reports.ts
├─components/
│ ├─UserList.tsx
│ └─CourseList.tsx
└─query-client.tstext例如:
// queries/users.ts
export const usersQuery = () => ({
queryKey: ["users"],
queryFn: fetchUsers,
})ts组件:
const { data, isPending } = useQuery(
usersQuery()
)tsx这样 API 逻辑不会和 UI 混在一起。
一个重要的模式:Query Key#
使用 TanStack Query 时,应该设计结构化的 query key。
例如:
["users"]ts["users", userId]ts["users", { page: 1, search: "john" }]ts可以想象成:
users
├─users/123
├─users/456
└─users?page=1&search=johntextquery key 设计得越一致:
invalidateQueries()ts和缓存管理就越容易。
[!TIP] query key 按从通用到具体的层级设计:
["users"]→["users", id]→["users", { page, search }]。这样invalidateQueries({ queryKey: ["users"] })就能失效整棵子树 —— 就像删除整个文件夹,而不是逐个删文件。
一个完整的例子#
function UserList() {
const queryClient = useQueryClient()
const usersQuery = useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60_000,
})
const createMutation = useMutation({
mutationFn: createUser,
onSuccess: () => {
queryClient.invalidateQueries({
queryKey: ["users"],
})
},
})
if (usersQuery.isPending) {
return <div>Loading...</div>
}
if (usersQuery.isError) {
return <div>Something went wrong</div>
}
return (
<>
{usersQuery.data.map(user => (
<div key={user.id}>
{user.name}
</div>
))}
<button
onClick={() =>
createMutation.mutate({
name: "John",
})
}
>
Add user
</button>
</>
)
}tsx此时的流程很清晰:
结论#
如果你的目标是 React 中 API 数据的客户端缓存,那么 @tanstack/react-query 非常值得考虑。
最需要记住的不是:
“TanStack Query 是 fetch API 库。”
而是:
TanStack Query 是 server state 管理与客户端缓存系统。
当应用 API 越来越多,开始出现这些问题时,它特别有用:
API请求重复
+
缓存
+
过期数据
+
Refetch
+
Mutation
+
缓存失效
+
乐观更新text与其用 useEffect + useState + Map 全部自己造,不如把 server-state 这部分交给 TanStack Query。
现代 React 架构可以简化为:
这也是避免把所有 API 数据无脑塞进 Redux/Zustand 的视角。