React / 系统课时
接入共享状态与缓存
接入共享状态与缓存
这一节把“跨页面共享的客户端状态”和“来自服务端、需要缓存的数据”分开管理。你会用 Context 保存当前团队选择,用 TanStack Query 缓存团队成员,并在修改后精确失效对应缓存,避免每个页面各自请求、各自维护副本。
学习目标
- 区分适合 Context 的共享客户端状态和适合查询缓存的服务端状态。
- 使用
QueryClientProvider建立统一的数据缓存边界。 - 在数据修改成功后失效相关查询,并触发重新获取。
先划清两类状态
当前选中的团队、主题模式、侧栏开关这类值没有服务端生命周期,适合用 Context 或轻量状态库共享。团队成员列表则来自接口,除了数据本身,还伴随加载、错误、过期、重新获取等状态,应该交给查询缓存管理,而不是复制进 Context。
这两类状态会协作,但职责不同:Context 决定“当前查看哪个团队”,查询键决定“缓存哪一份团队成员”,修改成功后再只让受影响的查询过期。

安装并建立缓存边界
在已有 React 项目中安装 TanStack Query:
npm install @tanstack/react-query预期结果
命令成功结束且没有安装错误;包数量、审计摘要和耗时会随项目与 npm 版本变化。下面示例可直接替换 src/App.jsx。为了无需后端也能运行,示例用内存对象模拟 API;成员页和概览页共享同一个团队选择与查询缓存,切页时 QueryClientProvider 不会卸载。
import { createContext, useContext, useState } from "react";
import {
QueryClient,
QueryClientProvider,
useMutation,
useQuery,
useQueryClient,
} from "@tanstack/react-query";
const queryClient = new QueryClient();
const TeamContext = createContext(null);
let nextMemberId = 1;
let database = {
frontend: ["Ada", "Grace"],
backend: ["Linus", "Ken"],
};
function fetchMembers(teamId) {
return new Promise((resolve) => {
setTimeout(() => resolve([...database[teamId]]), 300);
});
}
function addMember({ teamId }) {
return new Promise((resolve) => {
setTimeout(() => {
const name = `New-${teamId}-${nextMemberId++}`;
database[teamId] = [...database[teamId], name];
resolve(name);
}, 300);
});
}
function useMembers() {
const { teamId } = useContext(TeamContext);
return useQuery({
queryKey: ["members", teamId],
queryFn: () => fetchMembers(teamId),
staleTime: 30_000,
});
}
function TeamSelector() {
const { teamId, setTeamId } = useContext(TeamContext);
return (
<select value={teamId} onChange={(e) => setTeamId(e.target.value)}>
<option value="frontend">frontend</option>
<option value="backend">backend</option>
</select>
);
}
function MembersPage() {
const { teamId } = useContext(TeamContext);
const client = useQueryClient();
const membersQuery = useMembers();
const addMutation = useMutation({
mutationFn: addMember,
onSuccess: () => {
// 修改成功后只让当前团队缓存失效,活动查询会重新获取。
client.invalidateQueries({ queryKey: ["members", teamId] });
},
});
if (membersQuery.isPending) return <p>加载中...</p>;
return (
<section>
<ul>
{membersQuery.data.map((name) => <li key={name}>{name}</li>)}
</ul>
<button
disabled={addMutation.isPending}
onClick={() => addMutation.mutate({ teamId })}
>
{addMutation.isPending ? "添加中..." : "添加成员"}
</button>
</section>
);
}
function OverviewPage() {
const membersQuery = useMembers();
if (membersQuery.isPending) return <p>加载中...</p>;
return <p>当前团队共有 {membersQuery.data.length} 名成员。</p>;
}
function Workspace() {
const [page, setPage] = useState("members");
return (
<main>
<h1>团队工作区</h1>
<TeamSelector />
<button onClick={() => setPage("members")}>成员页</button>
<button onClick={() => setPage("overview")}>概览页</button>
{page === "members" ? <MembersPage /> : <OverviewPage />}
</main>
);
}
export default function App() {
const [teamId, setTeamId] = useState("frontend");
return (
<QueryClientProvider client={queryClient}>
<TeamContext.Provider value={{ teamId, setTeamId }}>
<Workspace />
</TeamContext.Provider>
</QueryClientProvider>
);
}预期结果
首次进入 frontend 成员页时先显示“加载中...”,随后显示 Ada、Grace。
切到概览页后仍保持 frontend,并显示“当前团队共有 2 名成员”;在 staleTime 内可直接复用同一查询缓存。
切到 backend 后显示 Linus、Ken,frontend 与 backend 分别保留自己的缓存。
点击“添加成员”后当前团队查询被失效并重新获取,列表出现 New-<TEAM_ID>-<ID>;切到概览页后成员数同步增加。<TEAM_ID> 表示当前团队标识,<ID> 表示示例运行时递增的成员编号。
理解失效而不是手动同步
invalidateQueries 不会直接替你构造新列表,而是把匹配查询标记为过期;对于当前正在使用的查询,TanStack Query 会重新获取最新数据。这保留了“服务端才是事实来源”的边界,尤其适合服务端可能补充字段、重新排序或执行校验的修改操作。
如果接口直接返回完整的新对象,也可以使用 setQueryData 更新缓存以减少一次请求;但只有能确定本地结果与服务端最终状态一致时才这样做。不要同时在 Context、组件 useState 和 Query Cache 中保存同一份成员列表,否则很快会出现多份数据不同步。
验收缓存行为
先在两个团队之间切换,确认查询键按团队隔离;再在成员页与概览页之间切换,确认 teamId 不丢失且缓存可复用;最后新增成员,确认只刷新当前团队的数据。如果共享选择和服务端数据各自只有一个事实来源,跨页面状态与缓存更新就形成了稳定边界。