SuperAPI AI 工具集

optimistic-update-rollback-contracts

通用与其它

查看项目

更新于 10-16 06:44

技能介绍

用途:处理前端乐观更新(optimistic UI)的“应用—回滚—对账”生命周期问题,即变更在服务端确认前先显示,若对账出错会出现未回滚的假状态、重复行、临时 ID 残留、refetch 与变更竞争导致的闪烁等。

主要能力:1)应用前先取快照(getQueryData、先前列表、先前表单状态),失败时恢复该快照,而不是反向撤销增量;2)乐观写入前取消进行中的 refetch,如在 TanStack Query 的 onMutate 中 await cancelQueries({ queryKey }),避免 refetch 迟到覆盖乐观结果;3)将回滚接到每个失败出口,onError 恢复快照,SWR 默认 rollbackOnError: true 且支持按错误类型定制,需确认被豁免的错误类型(如 AbortError)是有意为之;4)结算时以服务端真实状态对账,在 onSettled 中 invalidate/refetch,让 id、时间戳、规范化或部分被拒的值替换猜测值,若变更应保持 pending 到 refetch 完成则返回该 invalidation promise;5)临时客户端 id 必须换成服务端 id,插入用 temp 前缀或 uuid,响应到达后替换该条目而非追加真实条目,Apollo 需带 __typename + id 使规范化缓存完成临时到真实合并,并用 update 函数把新对象放入列表查询;6)不要同时写结果又 invalidate 同一查询,每个查询只选一条对账路径(write-through 或 invalidate-and-refetch);7)同一资源的并发变更需排序,TanStack 可用 scope: { id } 让同作用域串行,或在调用点做防抖/排队;8)注意并发 refetch 窗口:第二个变更在第一个仍在途时启动,若第一个的 invalidation refetch 比第二个变更先结算,界面会回退,可用查询取消加细粒度失效、mutationKey 配合 isMutating 缓解;9)useOptimistic 的 reducer 必须基于当前状态参数重新计算,不能用捕获的旧列表,且在 action/transition 完成后自动回退,若其中未真正运行变更则会弹回。

使用方式:可用 ripgrep 探测代码库中的相关路径,例如 rg -n 'onMutate|cancelQueries|getQueryData|setQueryData|invalidateQueries|onSettled' src/ app/,以及针对 optimisticData、rollbackOnError、populateCache、useOptimistic、optimisticResponse 和临时 ID 创建(temp-、tmpId、crypto.randomUUID)、并发作用域(scope:\s*{、mutationKey、isMutating)的检索。

适用场景与限制:适用于乐观写入的创建、编辑、删除等用户可见对账契约被破坏时;已有快照+回滚+onSettled invalidate 的正确模式不应报缺陷;低失败风险的单界面动作使用 useOptimistic 且无缓存回滚属于有意简化;纯 queryKey 调优应归入数据获取缓存契约;非乐观变更(转圈等待确认)不在范围内。提交缺陷需给出文件/行号、onMutate/onError/onSettled 路径、症状与最小修复及验证测试;最小有用 PR 是一个失败测试驱动 apply→server-error→断言回滚到快照,创建场景还需断言临时 ID 替换后 refetch 只有一行。依赖库的具体版本与安装命令资料未提供。