点了马上变,别等服务器点头:乐观更新实战
点赞要等半秒才变红,用户会再点一次。本文按 TanStack Query 与 React 官方文档讲乐观更新:variables 与 onMutate 两种写法、useOptimistic 的 reducer 与删除恢复、失败三档处理、并发临时 id 与五个反模式,附上线检查表。

先把这篇的边界说清楚。站里已经有几篇讲“界面先动起来”的指南,但讲的都不是这篇的东西。《站内消息指南》讲的是消息怎么收发,其中顺带提了一句“点发送就先把消息显示出来”;这篇讲的就是那句话背后的完整做法:乐观更新。《离线同步指南》和《多设备冲突指南》讲的是数据最终怎么合到一起;这篇讲的是合起来之前,界面先给用户看什么。《加载、空态与错误态指南》讲的是等数据的时候界面长什么样;这篇讲的是反过来——不等数据,先把结果摆出来。乐观更新不是加载态的替代品,它是另一条路:用户点下去的那一刻,界面就按“已经成功了”来画,服务器的回答晚一点再到。
下面用到的“一起买”是一个虚构的练手项目:几个人共用一份购物清单,能加东西、能点赞、能勾掉已买的。本文所有以它为例的操作、代码和数字,都是为了讲清楚做法编出来的,不是真实记录。所有关于 TanStack Query 与 React 的规则、接口名和行为,都来自两家的官方文档,来源见每篇的 meta 信息与 evidence 记录。别的框架也有自己的乐观更新办法,思路相通,但接口名字不一样,照搬之前先对一下它自己的文档。
乐观更新到底是什么:一笔时间账
先算一笔时间账。用户点一下“点赞”,请求从手机出发、到服务器、再回来,在普通网络下要花 200 到 500 毫秒,弱网能到 2 秒。如果你等服务器回来说“好了”再把爱心变红,这 200 毫秒到 2 秒里,用户看到的是什么都没发生。点一下没反应,大多数人会再点一下——于是服务器收到两次点赞,爱心又变回去了,或者多出一条记录。乐观更新的做法反过来:点下去的同一毫秒,界面先把爱心变红,数字先加一;请求在后台慢慢走,成功了就悄悄确认,失败了再把爱心变回去、告诉用户没成功。
这不是在“骗”用户。它是在承认一个事实:绝大多数操作都会成功。点赞、收藏、关注、勾掉待办、改个名字,这些操作失败的概率很低,低到不值得让每一次点击都先等半秒。把“先画结果、后等确认”当成默认,把“失败回滚”当成例外来处理,界面就从“每一步都卡一下”变成了“每一步都跟手”。跟手感不是动画做出来的,是反馈时机做出来的:反馈发生在用户手指离开屏幕的那一刻,而不是服务器回包的那一刻。
但乐观更新也不是万能的。它只解决“反馈慢”的问题,不解决“操作本身慢”的问题。上传一张 20MB 的照片,乐观更新能做的最多是先把缩略图摆出来、显示“上传中”;照片真正传完还是要时间。发一条消息,乐观更新能先把消息贴进对话框;消息真正送达还是要等服务器。分清这两层,就不会对乐观更新有不切实际的期待:它管的是用户“看到”的那一层,不是“做完”的那一层。

先过四道关:这个操作能不能乐观
不是所有操作都能乐观。动手之前,先让操作过四道关,有一道过不去,就老老实实等服务器。
第一关,结果能不能提前算出来。点赞之后爱心是红的、数字加一,这个结果你不用问服务器也知道。改名字,改完显示什么你也知道。反过来,操作的结果要服务器算了才知道,就不能乐观:比如“领一张优惠券”,领到的是满 100 减 20 还是满 50 减 10,要服务器说了算;再比如搜索、推荐、算价钱,结果没法提前猜,猜了也是错的。
第二关,失败了能不能说清楚。操作失败时,你得能告诉用户“刚才那下没成”,而且用户得能接受这个说法。点赞失败,爱心变回去、冒一句“点赞失败,请重试”,用户能理解。关注失败也一样。但有些失败是说不清楚的:用户以为已经付款成功、界面也显示“已支付”,过一会儿又说“其实没扣上”,这种反转用户接受不了。
第三关,操作能不能重来。失败之后,用户点一下“重试”就能再来一次的操作,适合乐观。点赞、收藏、发消息、改备注,都是这类。不可逆的操作不适合:删账号、注销、清空数据、发验证码、扣钱,这些操作一旦在界面上“先显示成功”,失败时就没法干净地收场。
第四关,失败概率是不是足够低。如果某个操作在你的产品里十次有三次失败,乐观更新就是在反复打用户的脸:刚变红又变回去,刚加上又消失。先把成功率修上去,再谈乐观。第四关过不去,前面三关过了也没用。
记住一条硬线:凡是跟钱、跟不可逆的删除、跟法律效力有关的操作,一律不乐观。付钱、退款、删账号、解绑手机号、提交实名认证,这些操作哪怕慢一点、转圈久一点,也要等服务器点头。界面慢半秒,用户最多抱怨一句;界面先说成功、事后又反悔,用户会觉得被骗了。
第一条路:TanStack Query 的两种写法
如果你用 TanStack Query(也就是 React Query),官方文档给了两种乐观更新的写法。第一种最简单:直接用 useMutation 返回的 variables。发起点赞的 mutation 还在跑的时候,variables 里就已经装着这次点赞传过去的数据,你可以在列表渲染时把它拼进去,多渲染一个临时的、半透明的条目。等 mutation 跑完,临时条目自动消失——如果服务端返回成功、列表重新拉取,真实条目会以正常样式出现;如果失败了,临时条目也会消失,这时你可以用 mutation 的 isError 状态把那条失败的数据留下来、旁边挂一个“重试”按钮。
这种写法的最大好处是:你完全不用管回滚。临时条目不是真的写进了缓存,它只是“mutation 还在跑的时候多画一个”。mutation 一结束,不管成功失败,它都不见了。代价是它只在 mutation 和列表长在同一个组件里时最顺手。官方文档也写明了这一点:如果 mutation 和列表不在同一个组件里,可以用 useMutationState 这个 Hook,配合 mutationKey 在别的组件里读到所有进行中的 mutation;variables 会是一个数组,因为可能同时有好几个 mutation 在跑;想给每个乐观条目一个唯一键,可以用 mutation.state.submittedAt,连点两次也不会撞键。
第二种写法是直接改缓存,适合“屏幕上有好几个地方都要跟着变”的场景:点赞之后,列表里的数字、详情页的数字、个人主页的统计,都要同时加一。做法是给 useMutation 传 onMutate:在请求发出去之前,先把缓存里的数据改成乐观的样子。官方文档的建议是,让 onMutate 返回一个值——通常是一个回滚函数——这个返回值之后会原样传给 onError 和 onSettled。请求失败了,在 onError 里调用这个回滚函数,把缓存恢复成请求之前的样子;请求不管成功失败,在 onSettled 里重新拉取一次数据,让缓存和服务器对上。
// onMutate 先改缓存,返回回滚函数;失败时 onError 拿它恢复
useMutation({
mutationFn: toggleLike,
onMutate: async (postId) => {
await queryClient.cancelQueries({ queryKey: ["post", postId] });
const previous = queryClient.getQueryData(["post", postId]);
queryClient.setQueryData(["post", postId], (old) => ({
...old,
liked: !old.liked,
likes: old.likes + (old.liked ? -1 : 1),
}));
return { rollback: () => queryClient.setQueryData(["post", postId], previous) };
},
onError: (_err, _vars, context) => context?.rollback(),
onSettled: (_data, _err, postId) =>
queryClient.invalidateQueries({ queryKey: ["post", postId] }),
});
官方文档还写了一句很实在的提醒:大多数失败场景下,你其实不用手写回滚,只要触发一次重新拉取(refetch),缓存就会回到服务器给的真实状态。手写回滚只在一种情况下是必需的:失败本身就代表服务器出了问题、连重新拉取都拉不回来。这时候 refetch 拿不到真数据,只能靠你之前存下来的旧数据把界面恢复原样。所以回滚函数要写,但别把它当成唯一的救命绳——先 refetch,refetch 不行再回滚,这个顺序别反了。
两种写法怎么选,官方文档给了一个很直接的标准:如果只有一个地方要显示乐观结果,用 variables,代码少、不用管回滚、也最容易想明白;如果有好几个地方都要跟着变,直接改缓存,改一次、全屏都对上。选错了也不用怕:先从 variables 写起,等到真的出现“第二个地方也要变”的时候,再改成 onMutate,重构的量很小。
第二条路:React 原生的 useOptimistic
如果你用 React 19,官方还给了另一条路:useOptimistic 这个 Hook。它不碰任何缓存,只管“这个组件在 Action 跑着的时候显示什么”。签名很短:const [optimisticState, setOptimistic] = useOptimistic(value, reducer?)。第一个参数是真实值,第二个是可选的 reducer。没有 pending 的 Action 时,它返回的就是真实值;有 Action 在跑时,它返回 reducer 算出来的乐观值。
最简单的用法是点赞按钮。真实的 isLiked 存在父组件的 state 里,按钮里包一层 useOptimistic(isLiked),点击时在 startTransition 里面先 setOptimisticIsLiked(!optimisticIsLiked),再 await toggleLike(newValue),等服务器回来再把真实的 isLiked 更新掉。失败了怎么办?官方文档写得很清楚:如果 Action 抛错,Transition 还是会结束,React 按当前的真实值重新渲染;因为失败时父组件一般不会更新真实值,所以界面会自动回到点赞之前的状态。你只要 catch 住错误、给用户看一句提示就行,回滚是框架替你做的。
这里有两条铁规,违反了会直接报错。第一,setOptimistic 必须在 Transition 或者 Action 里面调,调在外面会报“An optimistic state update occurred outside a Transition or Action”,乐观值只会闪一下就缩回去。写在 startTransition(async () => {...}) 里面,或者写在表单的 Action prop 里(那种按约定以 Action 结尾的 prop,本身就跑在 Transition 里),都是对的。第二,不能在渲染的时候调 setter,调了会报“Cannot update optimistic state while rendering”;setter 只能出现在事件处理、effect 或者别的回调里。
列表场景要用 reducer。官方文档的待办列表示例是这样的:useOptimistic(todos, (currentTodos, newTodo) => [...currentTodos, { ...newTodo, pending: true }]),新增时先给新条目打一个 pending: true 的标记,渲染时在后面缀一句“添加中”。这里用 reducer 而不是直接传函数,原因很实际:如果别的用户在你这个 Action 跑着的时候也加了一条,todos 这个 prop 变了,React 会用新的 todos 重新跑一遍你的 reducer,你的乐观条目会加在最新的列表上面,而不是一份过期的拷贝上。直接传 updater 函数是看不到这种变化的——它只认得 Transition 开始那一刻的状态。
// 关注按钮:两个值一起变,用 reducer 一次算好,按钮文字和粉丝数永远对得上
const [optimisticState, updateOptimistic] = useOptimistic(
{ isFollowing: user.isFollowing, followerCount: user.followerCount },
(current, isFollowing) => ({
isFollowing,
followerCount: current.followerCount + (isFollowing ? 1 : -1),
})
);
function handleClick() {
const next = !optimisticState.isFollowing;
startTransition(async () => {
updateOptimistic(next);
await followAction(next);
});
}
一个 reducer 还能管多种动作。官方文档的购物车示例用一个带 type 字段的 action 对象同时处理三种动作:add 是加一件(已经在车里的就数量加一)、remove 是整行删掉、update_quantity 是改数量,每种都给条目打上 pending: true,总价直接拿乐观的购物车算。三种动作共用一个 reducer,好处是“购物车长什么样”只有一个地方说了算,不会在三个处理函数里写出三个版本。
删除是最需要小心的一种乐观更新。官方文档专门给了“带错误恢复的乐观删除”示例:点删除不是立刻把条目从列表里拿掉,而是先给它打上 deleting: true 的标记,渲染成半透明加删除线、按钮文案变成“删除中”并且禁用。删除成功了,父组件更新真实列表,条目自然消失;删除失败了,catch 住错误、把错误信息显示出来,条目因为真实值没变会自动重新出现。删东西先变灰、再消失,比“一点就没、失败又突然冒回来”要诚实得多,用户也更容易理解发生了什么。
失败了怎么办:三档处理,别只会一种
乐观更新的失败处理,分三档,按“用户能不能自己补救”来选。第一档是悄悄重刷:失败的原因大概率是一过性的网络抖动,用户甚至不需要知道发生过什么,重新拉取一次数据、界面回到真实状态就够了。点赞数、关注数、收藏状态,这类“看一眼就过去”的数据,用第一档。
第二档是回滚加一句提示:操作失败了,界面恢复原样,同时在操作发生的地方给一句人话——“点赞失败,请重试”,而不是弹一个全屏报错。提示要长在操作旁边,不要长在屏幕顶上;用户点的是哪一行,提示就出现在那一行旁边。这一档适合大多数需要用户知道“刚才那下没成”的场景。
第三档是留下来、给重发:失败的操作本身有用户输入在里面,丢了要用户重打一遍,代价最大。发消息是最典型的例子:消息先贴进对话框,发送失败时,消息不要消失,在它下面挂一个“发送失败,点击重发”的按钮,原文原样留着。这一档的判断标准很简单:如果重做一次要用户花超过十秒,就用第三档;如果点一下就能重来,第二档就够了。
还有一条容易漏的:重试的时候别让服务器重复执行。用户连点两次“重试”,服务器可能收到两次请求,点赞变成两次、订单变成两单。解决办法是给每一次操作带一个幂等键:同一个操作不管发几次,服务器只认第一次。站里的《Agent 友好 API 设计指南》已经把幂等键的写法讲透了,这里只记结论——乐观更新的重试按钮,必须配幂等键,否则重试本身就是一个新的 bug。
并发:连点、乱序与临时 id
乐观更新最容易翻车的地方,是用户手比网络快。点赞按钮连点三下:第一下还没回来,第二下、第三下已经发出去了。三个请求回来的顺序还不一定按发出去的顺序:先发的可能后到。界面如果只按“最后回来那个回答”来画,就可能把最终状态画错——用户点了三下是“赞、取消、赞”,最后一次回来的是第二次的回答,界面停在“没赞”上,跟用户的第三下对不上。
治这个问题的办法有三条。第一,给每一次操作一个临时 id:新增的条目先用客户端生成的 id(比如 crypto.randomUUID())占位,服务器返回真实 id 之后再换掉;渲染列表时用这个 id 当 key,千万别用数组下标当 key——下标会在增删之后移位,乐观条目和真实条目会对不上号。第二,互相抵消的操作要合并:连续的点赞、取消点赞,最后只发一次“最终状态”,而不是把三次请求都发出去。第三,同一个对象上的乐观更新要排队:前一个还没确认,后一个先别发,或者后一个发出去时带上“基于第几个版本”的信息,让服务器能判断顺序。
还有一种更隐蔽的并发:两个人同时改同一个东西。你把清单里“牛奶”的数量从 1 改成 2,另一个人同时把它改成 3。你的乐观更新显示 2,他的显示 3,服务器最后只会留一个。谁赢了,另一个人的界面就要悄悄变成赢了的那个数——但这时候要不要告诉用户?答案是:如果改的是数量这种小事,悄悄同步就行;如果改的是整段文字、整份配置这种大事,同步之前要先问用户一句,或者把冲突摆出来让他选。乐观更新管的是“我的操作先显示”,冲突解决是另一篇指南《多设备冲突》讲的事,别在这篇里混在一起。
五个反模式
反模式一:给钱做乐观。付款按钮一点就显示“支付成功”,扣款失败再改口。这不是体验优化,是在拿用户的信任开玩笑。钱、删账号、解绑、实名认证,一律等服务器点头。
反模式二:乐观删除不留痕。点删除条目立刻消失,失败了又突然冒回来,用户会以为见鬼了。删除先变灰、加删除线、按钮变“删除中”,失败了条目还在原地、旁边一句话说明原因。
反模式三:失败了悄悄吞掉。请求失败,界面悄悄变回去,一句话也不说。用户明明点了赞,爱心闪了一下又灭了,他不知道是网络问题、还是自己手滑没点上。失败一定要有可见的说法,哪怕只是一句“没成功,点一下重试”。
反模式四:把乐观状态当真状态存下来。乐观值只应该活在内存里、活在当前这次交互里。把它写进 localStorage、写进数据库,或者刷新页面之后还拿它当真,用户一刷新就看到“已经点过赞了”,再一刷新又没了。乐观状态的保质期就是这一次请求,请求结束它就该消失。
反模式五:什么都乐观。搜索结果、推荐列表、算出来的价格,这些结果是服务器算出来的,猜不到、也不该猜。乐观更新只用在“结果我能提前算出来”的操作上,判断标准就是前面那四道关。关没过就别硬上,转圈等一等,比猜错了再改口强。
检查表:上线之前过一遍
动手之前:这个操作的结果能不能提前算出来?失败了能不能一句话说清楚?是不是可逆、可重试的?跟钱和不可逆删除有没有关系?失败概率够不够低?五问有一问答不上来,先别乐观。
写代码的时候:只用一种写法管一个地方(variables 管单点、onMutate 管多点,别两处各写一半);临时条目带 pending 标记、看得出来它还没确认;回滚函数先写好再写乐观逻辑;重试按钮配幂等键;列表用稳定 id 当 key,不用下标。
上线之前:断网点一次,看失败提示长没长在操作旁边;连点五次点赞,看最终状态对不对;刷新一次页面,看乐观状态有没有穿帮;弱网模式下走一遍主流程,看有没有“闪一下又变回去”的地方。乐观更新做得好不好,不用看代码,看这四次测试:反馈是不是立刻有、失败是不是说得清、连点是不是不翻车、刷新是不是不穿帮。四个都过了,这个功能的体验就已经比“等服务器再变”高一个档次了。
评论 (0)
原始来源
相关文章
网页每天都在做决定:满一百就打折、库存是零就显示售罄。本文按 MDN 的《Making decisions in your code — conditionals》《if...else》《switch》三篇官方文档讲清楚:if 与 else if、比较运算符、真值与假值、逻辑运算符、|| 的经典写错法、嵌套 if 与悬空 else、switch 与穿透、三元运算符与卫语句。
主线程又要画页面又要算账,一算就卡。Worker 是另一条线程、另一个全局上下文,两边只靠消息传话。本文按 MDN 的《Using Web Workers》与《Worker》两篇官方文档讲清楚:new Worker、postMessage 与 onmessage、结构化克隆的复制语义、Worker 里能与不能、onerror 与 terminate()、SharedWorker、Transferable 零拷贝,另附虚构咖啡馆点单页一个月 100 次 Worker 翻车的分布。
setTimeout 管一次,setInterval 管反复,但 delay 只保证“最少等这么久”:0 也不立刻、后台标签页还会更晚、超过 2147483647 会溢出。本文按 MDN 的 setTimeout 与 setInterval 两篇官方文档讲清楚:异步返回、传参、delay 的数字规矩、嵌套 4 毫秒、clearTimeout 与 clearInterval、递归 setTimeout、this 丢失与字符串参数,另附虚构咖啡馆点单页一个月 100 次定时器翻车的分布。