Frontend Optimistic Mutations 实用指南

当你需要一个便携的、与框架无关的规范来处理任何使用查询/缓存层的 React 或 React Native 应用的写入路径时，请使用此技能。它规范化了乐观更新生命周期（取消正在进行的查询 → 快照每个受影响的缓存 → 即时修补 → 出错时逐字回滚 → 在...上使其失效）

目标：一次写入感觉即时（UI在服务器确认之前就反映出来），是安全的

(失败会恢复到之前的确切状态，并且重试不会重复收费)，并且会保留缓存

连贯的（详细视图和每个列表页面一致）。三者同时兼顾——这就是工艺。

1. 何时应乐观（何时不应乐观）

High-confidence, low-conflict write (toggle status, like, mark-paid, reorder) Optimistic — patch immediately, roll back on error.

Create that returns a server-generated id/number/total Pending state, then setQueryData from the server response. A temporary optimistic row is optional; reconcile on success.

Destructive or hard-to-reverse write (delete with cascade, send money) Confirm first, then optimistic _or_ pending — never silent-optimistic.

Write whose result the user can't see yet (background job) Pending + toast, invalidate when done. No optimistic patch.

乐观是一种用户体验工具，适用于你有信心会成功的写作。如果失败很常见或代价高昂

2. 乐观生命周期（TanStack 查询）

典型的形状。每个节拍都有其作用；跳过一个会破坏准确性。

// modules/invoice/hooks/useInvoiceMutations.ts
interface MarkPaidContext {
  previousInvoice: Invoice | undefined; // detail snapshot
  previousLists: Array<[readonly unknown[], InvoiceListResponse]>; // every list page snapshot
}

export function useMarkInvoicePaid() {
  const queryClient = useQueryClient();
  const notifyError = useApiErrorToast();

  return useMutation<Invoice, ApiError, { id: InvoiceId }, MarkPaidContext>({
    mutationFn: ({ id }) => apiClient.post<Invoice>(INVOICE_API.markPaid(id)),

    // 1 + 2 + 3: cancel in-flight reads, snapshot, patch
    onMutate: async ({ id }) => {
      await queryClient.cancelQueries({ queryKey: invoiceKeys.all }); // (1) no late refetch clobber

      const detailKey = invoiceKeys.detail(id);
      const previousInvoice = queryClient.getQueryData<Invoice>(detailKey); // (2) snapshot detail
      if (previousInvoice) {
        queryClient.setQueryData<Invoice>(detailKey, {
          // (3) patch detail
          ...previousInvoice,
          status: InvoiceStatus.Paid,
        });
      }

      const previousLists: MarkPaidContext["previousLists"] = [];
      for (const [key, list] of queryClient.getQueriesData<InvoiceListResponse>(
        {
          queryKey: invoiceKeys.lists(),
        },
      )) {
        if (!list) continue;
        previousLists.push([key, list]); // (2) snapshot each page
        if (!list.invoices.some((i) => i.id === id)) continue;
        queryClient.setQueryData<InvoiceListResponse>(key, {
          // (3) patch matching row
          ...list,
          invoices: list.invoices.map((i) =>
            i.id === id ? { ...i, status: InvoiceStatus.Paid } : i,
          ),
        });
      }
      return { previousInvoice, previousLists };
    },

    // 4: roll back verbatim
    onError: (error, { id }, ctx) => {
      if (ctx?.previousInvoice)
        queryClient.setQueryData(invoiceKeys.detail(id), ctx.previousInvoice);
      for (const [key, list] of ctx?.previousLists ?? [])
        queryClient.setQueryData(key, list);
      notifyError(error);
    },

    // 5: invalidate so authoritative server state (paidAt, aggregates) refetches
    onSettled: (_d, _e, { id }) => {
      void queryClient.invalidateQueries({ queryKey: invoiceKeys.detail(id) });
      void queryClient.invalidateQueries({ queryKey: invoiceKeys.lists() });
    },
  });
}

3. 非乐观写入：使用服务器拥有的字段创建

一个返回 id/数字/总数的创建操作不能完全乐观。将其作为待处理的变更运行，并

export function useCreateInvoice() {
  const queryClient = useQueryClient();
  return useMutation<Invoice, ApiError, CreateInvoiceInput>({
    mutationFn: ({ document, idempotencyKey }) =>
      apiClient.post<Invoice>("/invoices", document, { idempotencyKey }),
    onSuccess: (invoice) => {
      queryClient.setQueryData(invoiceKeys.detail(invoice.id), invoice); // seed detail
      void queryClient.invalidateQueries({ queryKey: invoiceKeys.lists() }); // refresh lists
    },
    onError: (error) => notifyError(error),
  });
}

4. 缓存一致性（锁步详细列表）

一个实体出现在许多缓存中：它的详细信息，以及每个经过过滤/分页的列表页面。一个

乐观补丁必须触碰所有这些，否则表面会不一致。使用分层密钥工厂

（摘自 frontend-architecture §4.3）这样你就可以精准地定位。

export const invoiceKeys = {
  all: ["invoices"] as const,
  lists: () => [...invoiceKeys.all, "list"] as const,
  list: (p: IListParams) => [...invoiceKeys.lists(), p] as const,
  detail: (id: InvoiceId) => [...invoiceKeys.all, "detail", id] as const,
} as const;

对你触及的每一页进行快照（按其确切查询键键控），以便回滚时恢复每一页

逐字地，而不仅仅是当前屏幕上显示的那一个。

5. 幂等性（对涉及资金操作的写入进行安全重试）

重试的 POST 不得执行两次操作。在表单初始化时（或第一次）生成密钥 一次

用户意图），在重试中传递它，并让客户端将其作为头发送。服务器重放

在其窗口内对重复键的原始响应。

// at form initialisation — stable for the lifetime of this attempt
const idempotencyKey = useMemo(() => crypto.randomUUID(), []);

// mutation forwards it; the typed client puts it on the header
apiClient.post<Invoice>("/invoices", document, { idempotencyKey });

useMutation({
  retry: (count, error: ApiError) => error.isNetworkError && count < 2, // network-only, bounded
});

五拍的生命周期是相同的；区别在于钩子。

TanStack Query onMutate (cancel + snapshot + patch) → onError (rollback) → onSettled (invalidate). The reference shape above.

RTK Query onQueryStarted: updateQueryData returns a patchResult; await queryFulfilled and call patchResult.undo() in catch. invalidatesTags on settle.

SWR mutate(key, optimisticData, { rollbackOnError: true, populateCache, revalidate: true }) — optimistic data + automatic rollback + revalidate.

对于 React Native，所有三个库都可以不改变地工作；缓存是事实上的来源

也适用于原生。保持 mutation hooks 无 DOM，这样它们可以在 web 和原生之间共享。

8. 规范检查清单（在审查中执行）

添加乐观突变： 决定乐观是安全的（第1节）。写出五个节拍

(§2)。识别实体所在的每个缓存，并修补/快照所有这些缓存 (§4)。

使写入操作可安全重试： 在表单初始化时生成幂等性键，并在线程中传递它

变异，确认客户端发送它 (§5)，并设置仅网络的有界重试 (§6)。

调试闪烁 / 写入后状态错误： 检查 onMutate 是否取消了查询（延迟

重新获取覆盖）并且 onSettled 使（过时的服务器计算字段）失效。检查 _所有_

列表页面被修补了，而不仅仅是可见的那个。

审查写入路径：按照§8运行清单。缺少最有价值的捕获项

cancelQueries（竞争覆盖）、部分缓存补丁（详情/列表不一致）以及幂等性

在 mutationFn 内生成的键（不再保护重试）。

此技能遵循 Anthropic 的 SKILL.md 格式，并且可以在各个代理之间移植。

来源说明：本文内容整理自开源项目 agentic-awesome-skills（中文翻译版），遵循 CC BY 4.0（知识共享署名 4.0 国际）许可协议，此处作为中文资料整理分享，版权归原作者所有。

A portable, framework-agnostic discipline for the write path of any React or React Native app using a query/cache layer. Codifies the optimistic-update lifecycle (cancel in-flight queries → snapshot every affected cache → patch instantly → roll back verbatim on error → invalidate on...

前端

编程语言

开发工具

前端乐观更新实用指南，提供可移植、框架无关的写入路径规范。核心涵盖五步生命周期：取消查询、快照缓存、即时修补、逐字回滚、失效刷新。适用于TanStack Query、RTK Query等主流库，确保UI即时响应且失败安全恢复。包含幂等性策略、缓存一致性及乐观与待处理状态的选择标准，附完整代码示例与审查清单。

React Native

服务器

GitHub

Agent

ReAct 

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

Frontend Optimistic Mutations 实用指南

Frontend Optimistic Mutations 实用指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐