React / 系统课时

数据变更与缓存失效

数据变更与缓存失效

本课实现一个可运行的新增用户功能:Mutation 负责提交数据,成功后可以让相关查询失效并重新获取,也可以把响应结果直接写入缓存。你将学会根据服务端返回内容和页面一致性要求选择同步策略。

学习目标

  • 使用 useMutation 提交新增、修改或删除请求
  • 在变更成功后通过 invalidateQueries 重新获取数据
  • 使用 setQueryData 在不追加网络请求时更新缓存

认识变更后的同步责任

Mutation 只管理一次写操作的状态与生命周期,不会自动判断哪些查询缓存已经过期。成功回调需要明确选择:让相关查询失效,或使用服务端响应直接更新指定缓存。:contentReference[oaicite:3]{index=3}

Mutation 与查询缓存同步流程

失效策略更稳妥,因为最终列表由服务端重新计算;直接更新更快,因为已经拿到完整响应时不需要再请求一次。两者都应放在成功阶段,避免失败请求污染缓存。

编写完整变更示例

先确认项目已安装依赖。

bash
npm install @tanstack/react-query --silent && npm ls @tanstack/react-query

预期输出

text
mutation-demo@<VERSION> <PATH>
└── @tanstack/react-query@<VERSION>

下面的入口文件提供两个按钮。第一个新增用户后使 ['users'] 查询失效,第二个把新增结果直接追加到同一个缓存。示例使用内存数组模拟服务端,因此可在普通 React 18 TypeScript 项目中直接观察请求次数。

tsx
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>,
);

预期结果

text
页面首次加载后显示 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] 时,只更新列表不会自动修正详情。实际项目应列出一次变更影响的查询键,再决定逐个直写、统一失效或组合处理。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

数据变更与缓存失效

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通