React / 系统课时

完善交互与缓存同步

完善交互与缓存同步

本课在任务管理功能已经可用的基础上,补齐用户真正能感知的交互质量:加载时有反馈、无数据时有引导、危险操作先确认,并通过乐观更新让状态切换立即生效。最终还会建立清晰的缓存失效规则,避免列表、详情和分页数据彼此冲突。

学习目标

  • 为任务列表设计加载、空状态、错误和确认交互
  • 使用 TanStack Query 实现状态修改的乐观更新与失败回滚
  • 区分直接更新缓存与失效重查的适用场景

设计交互状态

任务页面至少包含四类可见状态:首次加载、后台刷新、空结果和请求失败。首次加载可以显示骨架或提示;后台刷新不应清空现有列表;空状态需要区分“系统没有任务”和“当前筛选没有结果”。

删除、归档等不可轻易撤销的操作应先确认,普通状态切换则适合乐观更新。这样既避免无意义弹窗,也让高频操作保持流畅。

任务缓存同步时序

实现乐观更新

下面的主示例依赖 @tanstack/react-query。它假设应用入口已经通过 QueryClientProvider 注入查询客户端,并且后端提供 GET /api/tasks 与 PATCH /api/tasks/:id。

tsx
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";

type TaskStatus = "TODO" | "DOING" | "DONE";

type Task = {
  id: number;
  title: string;
  status: TaskStatus;
};

type TaskPageResult = {
  items: Task[];
  total: number;
};

type UpdateVariables = {
  id: number;
  status: TaskStatus;
};

const taskKeys = {
  lists: () => ["tasks", "list"] as const,
  list: (page: number) => ["tasks", "list", { page }] as const,
  detail: (id: number) => ["tasks", "detail", id] as const,
};

async function getJson<T>(url: string, init?: RequestInit): Promise<T> {
  const response = await fetch(url, {
    headers: { "Content-Type": "application/json" },
    ...init,
  });
  if (!response.ok) throw new Error(`请求失败:${response.status}`);
  return response.json() as Promise<T>;
}

export default function TaskListWithCache() {
  const queryClient = useQueryClient();
  const page = 1;
  const queryKey = taskKeys.list(page);

  const taskQuery = useQuery({
    queryKey,
    queryFn: () => getJson<TaskPageResult>(`/api/tasks?page=${page}`),
    staleTime: 30_000,
  });

  const updateStatus = useMutation({
    mutationFn: ({ id, status }: UpdateVariables) =>
      getJson<Task>(`/api/tasks/${id}`, {
        method: "PATCH",
        body: JSON.stringify({ status }),
      }),

    onMutate: async (variables) => {
      // 先停止旧请求,避免响应覆盖即将写入的乐观结果
      await queryClient.cancelQueries({ queryKey });

      const previous = queryClient.getQueryData<TaskPageResult>(queryKey);

      queryClient.setQueryData<TaskPageResult>(queryKey, (current) => {
        if (!current) return current;
        return {
          ...current,
          items: current.items.map((task) =>
            task.id === variables.id
              ? { ...task, status: variables.status }
              : task,
          ),
        };
      });

      return { previous };
    },

    onError: (_error, _variables, context) => {
      // 请求失败时恢复更新前的完整缓存快照
      if (context?.previous) {
        queryClient.setQueryData(queryKey, context.previous);
      }
    },

    onSettled: async (_data, _error, variables) => {
      await Promise.all([
        queryClient.invalidateQueries({ queryKey: taskKeys.lists() }),
        queryClient.invalidateQueries({
          queryKey: taskKeys.detail(variables.id),
        }),
      ]);
    },
  });

  if (taskQuery.isPending) return <p>正在加载任务...</p>;
  if (taskQuery.isError) return <p role="alert">任务加载失败,请重试。</p>;

  if (taskQuery.data.items.length === 0) {
    return <p>当前条件下没有任务,请创建任务或调整筛选条件。</p>;
  }

  return (
    <section>
      {taskQuery.isFetching && <p>正在同步最新数据...</p>}

      <ul>
        {taskQuery.data.items.map((task) => (
          <li key={task.id}>
            <span>{task.title}</span>
            <select
              value={task.status}
              disabled={updateStatus.isPending}
              onChange={(event) =>
                updateStatus.mutate({
                  id: task.id,
                  status: event.target.value as TaskStatus,
                })
              }
            >
              <option value="TODO">待处理</option>
              <option value="DOING">进行中</option>
              <option value="DONE">已完成</option>
            </select>
          </li>
        ))}
      </ul>

      {updateStatus.isError && (
        <p role="alert">状态更新失败,页面已恢复原值。</p>
      )}
    </section>
  );
}

预期结果:

text
首次进入页面时显示“正在加载任务...”。
列表存在时,后台刷新只显示“正在同步最新数据...”,不会清空旧内容。
切换状态后页面立即显示新状态;请求失败时恢复旧状态并提示错误。
请求成功或失败结束后,任务列表和对应详情缓存都会重新校验。

接口地址、任务 ID 和网络耗时属于动态值,实际运行时可能不同。示例中的 staleTime 为 30 秒,表示这段时间内数据通常被视为新鲜,但手动失效仍会触发重新获取。

制定缓存失效策略

直接写缓存适合结果可预测且字段少的操作,例如只修改任务状态。失效重查适合服务端可能补充更新时间、操作人、权限结果或派生字段的场景。两者通常组合使用:先乐观写入提升速度,再失效重查保证最终一致。

查询键必须稳定且分层。["tasks"] 表示任务域,列表键包含筛选和分页条件,详情键包含任务 ID。更新一条任务后,可以精确失效该详情;若任务状态会影响多个筛选列表,则失效整个任务域更安全。

补充确认弹窗

删除任务前可以使用浏览器原生确认框完成最小实现。确认通过后再调用删除 mutation,成功时移除详情缓存并失效列表缓存。

tsx
async function confirmDelete(taskId: number): Promise<boolean> {
  const accepted = window.confirm("删除后无法恢复,是否继续?");
  if (!accepted) return false;

  const response = await fetch(`/api/tasks/${taskId}`, { method: "DELETE" });
  if (!response.ok) throw new Error(`删除失败:${response.status}`);
  return true;
}

预期结果:

text
点击删除后先出现确认提示。
选择取消时不发送请求。
选择确认且接口返回成功时,函数结果为 true。
接口失败时抛出错误,由调用方显示失败提示。

生产项目可以替换为设计系统中的确认弹窗,但仍要保留相同语义:危险说明、取消入口、确认中的禁用状态,以及失败后的错误反馈。

验证异常与并发

在浏览器开发者工具中把网络切换为慢速模式,确认后台刷新时旧列表仍可见。再让更新接口返回 500,检查状态是否先变化、随后回滚,并出现错误提示。

连续快速修改同一任务可能产生并发覆盖。简单项目可以在 mutation 进行时禁用选择框;更复杂的项目应为每个任务维护独立提交状态,或让后端使用版本号进行并发控制。

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

目录与阅读设置

阅读设置

17

记录一个想法

完善交互与缓存同步

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

登录哪都通