在 React 项目里,最难维护的往往不是组件的 JSX,而是接口数据的生命周期。同一份订单数据可能同时出现在列表、统计卡片和详情弹窗中。保存操作完成后,究竟应该修改几个 useState?用户切换筛选条件时,旧请求返回的结果会不会覆盖新列表?
TanStack Query 提供了另一种组织方式:把服务端数据视为带有身份、有效期和重新获取规则的资源。组件声明“需要什么数据”,缓存层协调获取、复用和刷新。本文以订单工作台为例,解释 Query Key、staleTime、Mutation 和缓存失效之间的关系。
一、先划清客户端状态和服务端状态
搜索框里正在输入的字符、弹窗是否展开,是本地界面状态;订单列表、订单状态和服务端统计值,则由后端决定。把后者复制到多个组件的独立 useState 中,容易造成“列表已经更新,统计数字却没有变化”的问题。
工作台的页面结构可以从三个功能区开始:
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/5e9693c00a7455466989c3891a4f616bda7a17e4" class="order-workbench">
<header><h1>订单工作台</h1><p>查看与处理待办订单</p></header>
<section data-order-summary aria-label="订单统计"></section>
<section data-order-list aria-label="订单列表"></section>
</div>
TanStack Query 不取代所有状态管理工具。它解决的是远程数据的获取、缓存和更新协调;复杂的本地编辑草稿仍然可以交给 React 状态或其他本地状态库。
二、配置 QueryClient
通常在应用入口创建一个 QueryClient,并通过 Provider 交给子组件。单页浏览器应用应当复用同一个实例,而不是每次组件重渲染都创建新的缓存。
// src/main.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { createRoot } from 'react-dom/client';
import { App } from './App';
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 30_000,
retry: 1,
refetchOnWindowFocus: true
}
}
});
createRoot(document.getElementById('root')!).render(
<QueryClientProvider client={queryClient}>
<App />
</QueryClientProvider>
);
这里的 30_000 只是示例策略,不是所有系统都应该采用的值。查询结果在 staleTime 内被认为是新鲜数据;过期后可能在特定条件下触发后台重新获取。gcTime 则主要决定没有活跃订阅者的缓存条目可以保留多久,两者不能混为一谈。
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/76d5793462d525fb56e023197105395d79a16913" class="cache-status-panel" role="status">
<strong>数据状态</strong>
<span data-cache-state>等待读取</span>
<span data-last-refreshed>尚未刷新</span>
</div>
三、Query Key 必须包含所有查询变量
假设列表按订单状态筛选。若不同状态都使用 ['orders'] 作为缓存键,缓存层就无法区分“全部订单”和“待处理订单”。推荐定义集中管理的 Key 工厂。
export type Order = {
id: string; title: string; status: 'pending' | 'paid' };
export type OrderFilter = 'all' | 'pending' | 'paid';
export const orderKeys = {
all: ['orders'] as const,
lists: () => [...orderKeys.all, 'list'] as const,
list: (filter: OrderFilter) =>
[...orderKeys.lists(), {
filter }] as const,
detail: (id: string) =>
[...orderKeys.all, 'detail', id] as const
};
查询函数应该明确处理取消信号和非 2xx 状态。fetch 收到 HTTP 500 不会自动抛出异常,因此不能只写 return response.json()。
export async function fetchOrders(filter: OrderFilter, signal?: AbortSignal) {
const params = new URLSearchParams({
status: filter });
const response = await fetch(`/api/orders?${
params}`, {
signal });
if (!response.ok) throw new Error(`读取订单失败:${
response.status}`);
return response.json() as Promise<Order[]>;
}
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/7a6e4d6bc98678976a7384e75ad13e314abaf742" class="order-filters" role="group" aria-label="订单筛选">
<button type="button" data-status="all">全部</button>
<button type="button" data-status="pending">待处理</button>
<button type="button" data-status="paid">已支付</button>
</div>
四、使用 useQuery 声明数据依赖
组件只维护当前筛选状态,然后把筛选值放入 Query Key。筛选发生变化后,新 Key 对应新的缓存条目;此前已经获取的结果也可以在返回原条件时复用。
import { useState } from 'react';
import { useQuery } from '@tanstack/react-query';
import { fetchOrders, orderKeys, type OrderFilter } from './orders-api';
export function OrderList() {
const [filter, setFilter] = useState<OrderFilter>('all');
const query = useQuery({
queryKey: orderKeys.list(filter),
queryFn: ({ signal }) => fetchOrders(filter, signal)
});
if (query.isPending) return <p>正在获取订单…</p>;
if (query.isError) return <p role="alert">{query.error.message}</p>;
return (
<section>
<select value={filter} onChange={e => setFilter(e.target.value as OrderFilter)}>
<option value="all">全部</option>
<option value="pending">待处理</option>
<option value="paid">已支付</option>
</select>
{query.isFetching && <small>正在同步最新数据</small>}
<ul>{query.data.map(order => <li key={order.id}>{order.title}</li>)}</ul>
</section>
);
}
生产代码应当用受约束的枚举或运行时校验处理来自 URL 的筛选参数,而不是信任任意字符串。isPending 关注查询是否还没有可用数据,isFetching 则可以在展示旧缓存的同时表示后台同步。
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/b2f91bf84a6c0083c5614a2f9fd1a46b1da68100" class="order-loading" aria-live="polite">
<span data-loading-label>正在同步记录</span>
<progress data-load-progress></progress>
</div>
五、Mutation 成功后刷新哪一部分
假设用户把订单从“待处理”改成“已支付”。只更新当前列表中的一个标签可能不够:待处理列表、已支付列表、统计卡片都可能受影响。
import {
useMutation, useQueryClient } from '@tanstack/react-query';
function useMarkPaid() {
const client = useQueryClient();
return useMutation({
mutationFn: async (orderId: string) => {
const response = await fetch(`/api/orders/${
encodeURIComponent(orderId)}/pay`, {
method: 'POST'
});
if (!response.ok) throw new Error('状态更新失败');
},
onSuccess: async () => {
await client.invalidateQueries({
queryKey: orderKeys.lists() });
await client.invalidateQueries({
queryKey: ['order-summary'] });
}
});
}
invalidateQueries 会将匹配的查询标记为过期,并使符合条件的活跃查询重新获取数据。这种“完成写入后确认新的服务端事实”的方式,通常比手动同步多个组件更容易维护。
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/5059e8214fb56eaedcca4809b690ecb00510cd23" class="order-actions" aria-label="订单操作">
<button type="button" data-action="mark-paid">确认支付</button>
<button type="button" data-action="view-history">查看记录</button>
</div>
六、乐观更新不是默认选项
对于点赞、勾选等低风险操作,可以使用 onMutate 临时改写缓存,在失败时回滚。但对于支付、余额、审核结果等关键数据,界面不能把未确认的操作展示为最终完成。
如果需要乐观更新,必须至少处理取消正在进行的相关查询、保存旧缓存、写入临时值、失败时恢复快照,以及结算后再次失效查询。多个并发 Mutation 还需要额外处理回滚先后顺序。
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/72ce7c73ade14122b681ab79c426072c8d94794b" class="mutation-feedback" aria-live="polite">
<p data-operation-state>操作尚未开始</p>
<button type="button" data-retry hidden>重试</button>
</div>
对于不可逆写入请求,不应仅因客户端超时就直接重发。后端需要提供请求标识、幂等保障或查询确认状态的接口。
七、缓存失效与请求风暴之间的平衡
“每次返回页面就全部刷新”虽然容易理解,但会造成多余请求。可以根据资源变化频率调整 staleTime,按 Key 精准失效,并避免在多个组件挂载时重复触发不必要的写操作。
例如,订单详情和订单列表具有不同的 Key,修改某一条详情后可以只刷新对应详情;如果业务规则会影响汇总,还需要额外刷新统计查询。这应由数据依赖关系决定,而不是依赖某个组件所在位置。
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/75512347ef9e7c4c1fa21c1688a1814c7602c29a" class="query-debug-panel">
<h3>查询诊断</h3>
<output data-query-count>活跃查询:0</output>
<output data-request-errors>错误次数:0</output>
</div>
正式环境不应该把用户私有数据写入全局共享缓存,也不能把浏览器查询缓存视为永久存储。用户登出、切换租户或改变权限时,需要明确清理或隔离相关缓存。
八、上线前如何验证
至少覆盖四类情形:首次进入页面、从缓存返回、写入后刷新,以及弱网和后台重新获取。特别需要确认:快速切换筛选不会展示错误类型的订单;失败后旧数据仍可用时能否提示同步异常;离开页面后不必要的请求是否得到取消。
<div id="https://github.com/tiktokwuyu-ux/TIKTOK_baike/commit/38f02e20cbcb935b217bc3832cce1ce5a48d7108" class="query-test-results" role="status">
<p data-test="first-load">首次加载:待验证</p>
<p data-test="cache-hit">缓存复用:待验证</p>
<p data-test="mutation">写入失效:待验证</p>
</div>
九、总结
TanStack Query 的价值不在于替代 fetch,而在于为服务器状态建立明确的身份和生命周期。Query Key 表达数据依赖,staleTime 定义新鲜度,Mutation 描述写操作,失效机制让相关视图回到服务端事实。把这些边界设计清楚,比在每个 React 组件里重复编写一套加载、缓存和刷新逻辑更稳健。