React / 系统课时
数据变更与缓存失效
数据变更与缓存失效
本课实现一个可运行的新增用户功能:Mutation 负责提交数据,成功后可以让相关查询失效并重新获取,也可以把响应结果直接写入缓存。你将学会根据服务端返回内容和页面一致性要求选择同步策略。
学习目标
- 使用
useMutation提交新增、修改或删除请求 - 在变更成功后通过
invalidateQueries重新获取数据 - 使用
setQueryData在不追加网络请求时更新缓存
认识变更后的同步责任
Mutation 只管理一次写操作的状态与生命周期,不会自动判断哪些查询缓存已经过期。成功回调需要明确选择:让相关查询失效,或使用服务端响应直接更新指定缓存。:contentReference[oaicite:3]{index=3}

失效策略更稳妥,因为最终列表由服务端重新计算;直接更新更快,因为已经拿到完整响应时不需要再请求一次。两者都应放在成功阶段,避免失败请求污染缓存。
编写完整变更示例
先确认项目已安装依赖。
npm install @tanstack/react-query --silent && npm ls @tanstack/react-query预期输出
mutation-demo@<VERSION> <PATH>
└── @tanstack/react-query@<VERSION>下面的入口文件提供两个按钮。第一个新增用户后使 ['users'] 查询失效,第二个把新增结果直接追加到同一个缓存。示例使用内存数组模拟服务端,因此可在普通 React 18 TypeScript 项目中直接观察请求次数。
import { StrictMode, useState } from 'react';
import { createRoot } from 'react-dom/client';
import {
QueryClient,
QueryClientProvider,
useMutation,
useQuery,
useQueryClient,
} from '@tanstack/react-query';
interface User {
id: number;
name: string;
}
type SyncStrategy = 'invalidate' | 'direct';
interface CreateVariables {
name: string;
strategy: SyncStrategy;
}
const queryClient = new QueryClient();
let serverUsers: User[] = [{ id: 1, name: 'Ada' }];
let listRequestCount = 0;
async function listUsers(): Promise<User[]> {
await new Promise((resolve) => setTimeout(resolve, 300));
listRequestCount += 1;
return [...serverUsers];
}
async function createUser(name: string): Promise<User> {
await new Promise((resolve) => setTimeout(resolve, 300));
const created = { id: Date.now(), name };
serverUsers = [...serverUsers, created];
return created;
}
function UserManager() {
const [name, setName] = useState('');
const queryClient = useQueryClient();
const usersQuery = useQuery({
queryKey: ['users'],
queryFn: listUsers,
});
const createMutation = useMutation({
mutationFn: ({ name }: CreateVariables) => createUser(name),
onSuccess: async (created, variables) => {
if (variables.strategy === 'invalidate') {
await queryClient.invalidateQueries({ queryKey: ['users'] });
return;
}
queryClient.setQueryData<User[]>(['users'], (current) =>
current ? [...current, created] : [created],
);
},
});
function submit(strategy: SyncStrategy) {
const trimmedName = name.trim();
if (!trimmedName || createMutation.isPending) {
return;
}
createMutation.mutate({ name: trimmedName, strategy });
setName('');
}
if (usersQuery.isPending) {
return <p>正在加载用户...</p>;
}
if (usersQuery.isError) {
return <p>加载失败:{usersQuery.error.message}</p>;
}
return (
<main>
<h1>用户管理</h1>
<form onSubmit={(event) => event.preventDefault()}>
<input
value={name}
onChange={(event) => setName(event.target.value)}
placeholder="输入用户名"
/>
<button
type="button"
disabled={createMutation.isPending}
onClick={() => submit('invalidate')}
>
新增并失效缓存
</button>
<button
type="button"
disabled={createMutation.isPending}
onClick={() => submit('direct')}
>
新增并直接更新
</button>
</form>
<p>列表请求次数:{listRequestCount}</p>
<p>{createMutation.isPending ? '正在提交...' : '可以继续提交'}</p>
<ul>
{usersQuery.data.map((user) => (
<li key={user.id}>{user.name}</li>
))}
</ul>
</main>
);
}
createRoot(document.getElementById('root')!).render(
<StrictMode>
<QueryClientProvider client={queryClient}>
<UserManager />
</QueryClientProvider>
</StrictMode>,
);预期结果
页面首次加载后显示 Ada,列表请求次数为 <N>。
输入 Lin 并点击“新增并失效缓存”,列表会重新获取并显示 Ada、Lin,请求次数增加。
输入 Kai 并点击“新增并直接更新”,列表立即增加 Kai,请求次数保持不变。
<N> 为运行时动态值,开发模式下的实际次数可能受环境影响。选择失效还是直接更新
| 策略 | 适用情况 | 主要代价 |
|---|---|---|
invalidateQueries |
服务端会补充字段、重新排序、影响统计或多个列表 | 多一次重新获取 |
setQueryData |
响应已包含界面所需的完整最新对象 | 必须准确更新每个相关缓存 |
| 组合使用 | 详情页可直接更新,但列表、分页或统计仍需服务端重算 | 同步规则较多 |
invalidateQueries({ queryKey: ['users'] }) 会按查询过滤器匹配相关查询,并把它们标记为过期;当前活动查询通常会重新获取。直接更新时,setQueryData 应返回新数组或新对象,不要原地修改旧缓存。:contentReference[oaicite:4]{index=4}
当 Mutation 响应已经返回完整用户对象时,直接写入缓存可以避免浪费一次网络请求。若响应只返回成功标记,或服务端还会执行排序、权限过滤与派生计算,应优先失效查询。:contentReference[oaicite:5]{index=5}
验证失败与一致性边界
提交失败时不要在 onError 中假装成功写入缓存;应保留旧数据并显示错误。若需要先更新界面再等待服务端确认,那属于乐观更新,还必须准备回滚快照。
缓存键必须与读取时完全对应。列表使用 ['users'],详情使用 ['users', id] 时,只更新列表不会自动修正详情。实际项目应列出一次变更影响的查询键,再决定逐个直写、统一失效或组合处理。