Skip to content

离线优先:缓存、同步与冲突处理 ​

本篇要点:让应用在「有网但慢到用户放弃」时仍然可用,并把离线期间产生的写操作安全地补到服务端。 前置文章:《消息与推送:订阅消息、uni-push 与厂商通道》解决的是消息能不能送到;这一章解决用户在电梯里点开应用时看到的界面,以及他点下的那三次提交该怎么收场。

为什么需要它 ​

用户在电梯里点了三次提交,后台收到三条工单。不是他手抖:第一次转圈 45 秒,界面没有任何反馈,他以为没点上。

弱网最麻烦的地方在于它不会被识别成故障。uni.onNetworkStatusChange 只在网络类型变化时回调,地铁里连着 WiFi、往返时延(RTT)三秒、两个请求并发就卡死,对这套 API 来说仍然叫「网络正常」。所以别指望监听连通性来判断能不能用。

还有一层:wx.request 的默认超时是 60 秒,默认最大并发 10 个。六十秒意味着弱网下一个请求能把整页加载卡一分多钟;十个并发意味着列表页做起分页请求,翻到第二屏就开始排队,用户感觉是「越往下越慢」。这两个默认值都不适合直接上线。

离线优先(offline first)的做法是反过来的:先让界面有东西可看,再让网络去追。页面要数据的读取路径如图 10-1,注意最后两条失败分支是分开的。

图 10-1 离线优先的读取路径与三条失败分支

5xx 和超时回退旧数据,用户至少能看;4xx 必须删缓存,因为资源已删除或无权限,继续展示旧数据就是错的。这两类混在一起处理,就会出现「订单已取消,页面还显示待发货」这种让人投诉的现象。

核心概念 ​

缓存失效:只有三种可靠手段 ​

缓存(cache)把上次拿到的数据存起来,下次先读它。真正难的不是存,是让它在该失效时失效——版本号前缀、存活时间(TTL)、容量淘汰,只有这三种是可靠的。

版本号前缀是给 key 加一层 v3: 这样的常量,结构变更时把常量提一位,旧 key 自然读不到。类比是换一把门锁:不追着每把旧钥匙回收,直接让它们失效。反例是给对象加了一个必填字段却不动 key,老数据被新代码读出来变成 undefined,这类 bug 只在「用户升级后第一次打开」时出现,测试基本覆盖不到。

字节与字符:两个不同的长度 ​

小程序的写入上限按字节算,而 JS 的 str.length 按 UTF-16 码元算。一个中文字符占 3 个字节,length 只算 1,用 length 估体积会低估接近 3 倍。

小程序运行时没有 Blob,TextEncoder 也不保证存在,所以只能自己数。反例是「200 条商品列表,每条 1KB,应该 200KB 吧」——你以为写了 200KB,实际 580KB,线上报「存储空间不足」时,代码看起来完全正确。

离线队列:只接受「晚到也成立」的写操作 ​

离线队列(offline queue)把暂时发不出去的写请求存进本地,等网络恢复后按顺序重放。它的前提是服务端能幂等地接受这些请求,并且晚到十分钟业务仍然成立。

反例是把库存扣减、优惠券核销也做成队列。这两类操作依赖服务端的原子校验,排队等于把校验推迟到网络恢复之后,超卖是必然结果,只是时间问题。判断标准可以很土:这条数据晚十分钟到,业务能不能接受。不能接受的只能拦,不能排队。

乐观更新:先改界面,留一张回滚快照 ​

乐观更新(optimistic update)是先把本地状态改成「成功」的样子,等请求回来再确认或回滚。用户点「收藏」立刻变红,而不是转圈两秒。代价是要留一份快照:请求失败时把快照贴回去。

反例是只改界面不存快照。请求失败后界面显示已收藏、服务端没有记录,用户下次进来发现白点了,这比转圈更伤信任。

冲突:三种裁决方式,选一种写进协议 ​

冲突(conflict)指两个端在不知情的情况下改了同一条数据。三种常见裁决:最后写入者胜(last write wins,按时间戳)、字段级合并(各改各的字段,互不覆盖)、服务端裁决(服务端返回权威版本,客户端重放)。

反例是默认「最后写入者胜」却不校准时钟。手机时间被用户改过、跨时区、离线三天后补传,都会让「最后」这个词失去意义。

动手实践 ​

第一步:搭一层带版本号与 TTL 的缓存 ​

先读内存,再读 Storage,都没有才发请求。写回时同时带 expireAt。

js
// utils/cache.js —— 内存 + Storage 双层,key 带版本前缀
const V = 'v3'                        // 结构变更就加一
const mem = new Map()

export function readCache(key) {
  const k = `${V}:${key}`
  if (mem.has(k)) return mem.get(k)
  const hit = uni.getStorageSync(k)
  if (hit && Date.now() < hit.expireAt) {
    mem.set(k, hit.data)
    return hit.data
  }
  return null
}

export function writeCache(key, data, ttlMs = 30 * 60_000) {
  const k = `${V}:${key}`
  mem.set(k, data)
  try {
    uni.setStorageSync(k, { data, expireAt: Date.now() + ttlMs })
  } catch (e) {
    // 写入失败多为超限,淘汰后重试一次
    pruneTo(0.6)
    uni.setStorageSync(k, { data, expireAt: Date.now() + ttlMs })
  }
}

运行结果:首次进入列表页发起 1 次请求,第二次进入命中内存、0 次请求;杀掉进程重进命中 Storage、仍 0 次请求;把 V 改成 v4 后重新进入,Storage 里的旧 key 读不到,发起 1 次请求并把新结构写回。缓存超过 30 分钟后自动失效。

第二步:写入前先算字节,超限就淘汰 ​

先量,再写。量不准,后面所有策略都是空的。

js
// utils/size.js —— 小程序没有 Blob 与可靠的 TextEncoder,只能自己数
export function utf8Bytes(s) {
  let n = 0
  for (let i = 0; i < s.length; i++) {
    const c = s.charCodeAt(i)
    n += c < 0x80 ? 1 : c < 0x800 ? 2 : c >= 0xd800 && c <= 0xdbff ? 4 : 3
  }
  return n
}

export function putSafely(key, value, limit = 200 * 1024) {
  const size = utf8Bytes(JSON.stringify(value))
  if (size > limit) return { ok: false, size }   // 分片或只存首页
  uni.setStorageSync(key, value)
  return { ok: true, size }
}

运行结果:200 条商品列表的 JSON,utf8Bytes 返回约 580000,超过 200KB 上限,putSafely 返回 { ok: false, size: 580000 },调用方改为只缓存首屏 40 条。同一份数据若用 str.length 判断,得到约 195000,会被误判为安全并写入失败。

第三步:队列重放,4xx 进死信 ​

队列要区分可重试与不可重试:5xx 与超时按退避重来,4xx 直接进死信(dead letter),不再无限重试。

js
// utils/queue.js —— 离线写队列:重试有上限,4xx 不重试
const QUEUE_KEY = 'v3:offline:queue'

export function enqueue(task) {
  const q = uni.getStorageSync(QUEUE_KEY) || []
  q.push({ ...task, id: `${Date.now()}-${Math.random().toString(16).slice(2)}`, tries: 0 })
  uni.setStorageSync(QUEUE_KEY, q)
}

export async function flush(send) {
  let q = uni.getStorageSync(QUEUE_KEY) || []
  const dead = []
  for (const task of q) {
    try {
      await send(task)                  // send 内部要带 task.id 做幂等键
    } catch (e) {
      if (e.statusCode >= 400 && e.statusCode < 500) { dead.push(task); continue }
      task.tries += 1
      if (task.tries >= 5) { dead.push(task) }
    }
  }
  q = q.filter(t => !dead.includes(t))
  uni.setStorageSync(QUEUE_KEY, q)
  if (dead.length) uni.setStorageSync('v3:offline:dead', dead)
}

运行结果:断网时点三次提交,队列里有 3 条、tries 均为 0;恢复网络后 flush 重放,服务端凭 task.id 幂等去重,只落 1 条工单;若某条请求返回 401(令牌过期),它直接进死信表,不再重试,界面上给用户一个「待同步失败,点击重试」的入口。

第四步:给冲突定裁决规则 ​

多端同步最容易含糊的地方是「同时改怎么办」。先把规则写成表,再写代码。

场景裁决方式依据字段用户可见行为
收货地址最后写入者胜updated_at(服务端时间)直接覆盖,不提示
购物车数量服务端裁决服务端返回的权威值刷新时以服务端为准
商品标题与描述字段级合并各自 field_updated_at保留双方改动,冲突字段提示
收藏列表并集合并id 集合两端条目都保留
订单状态服务端裁决,客户端只读status 枚举客户端不允许离线改

表里没有一种通用解。选定的规则必须写进接口文档,两端按同一份规则实现,否则同一个冲突在 H5 和 App 上会得到不同结果。

常见误解 ​

以为可以用 uni.clearStorage() 做退出登录。 官方文档写明,非 App 平台清空 Storage 会导致 uni.getSystemInfo 拿到的 deviceId 变化。这个 ID 常被当设备指纹、埋点主键、灰度分桶依据,一清全乱。退出登录应该按前缀删业务 key,并且业务 key 要避开 uni-、uni_、dcloud-、dcloud_ 这些系统保留前缀。

以为各端存储容量差不多。 实际差得远:H5 走 localStorage,约 5MB,且可能被浏览器清掉(隐私模式、存储压力、用户手动清理都算);App 走 plus.storage,官方说明无大小限制且是持久化的;微信小程序单 key 1MB、总计 10MB;支付宝小程序单条字符串上限 200×1024,总计 10MB。「存进去就一直在」这种假设,总会在某一台机器上被推翻。

以为离线队列能包住所有写操作。 它只能包住服务端可幂等接受、且晚到十分钟仍然成立的操作。库存扣减、优惠券核销、订单状态变更都不属于这一类,它们只能在线校验,失败就明确告诉用户失败。

小结 ​

  1. 《消息与推送:订阅消息、uni-push 与厂商通道》把消息送出去,这一章管用户点开之后看到什么:弱网的关键特征是「API 认为网络正常」,所以判断依据是请求耗时,不是连通性回调。
  2. 缓存失效只有版本号前缀、TTL、容量淘汰三种可靠手段,其余都是猜。
  3. 写入前用 UTF-8 字节数判断,中文场景下 str.length 会低估接近 3 倍。
  4. 离线队列要区分可重试与不可重试:5xx 退避重试,4xx 进死信,队列要有上限。
  5. 乐观更新必须留回滚快照;冲突裁决要先定规则再写代码,且规则要写进接口文档。

相关主题 ​

到这里,一个小程序 + H5 + App 的主干功能已经齐了:界面、网络、支付、推送、离线。剩下的是把它们交付出去——《进阶:适配鸿蒙 NEXT 与上架》讲鸿蒙 NEXT 的适配细节、签名与上架流程,以及审核最常见的驳回原因。