离线优先:缓存、同步与冲突处理
本篇要点:让应用在「有网但慢到用户放弃」时仍然可用,并把离线期间产生的写操作安全地补到服务端。 前置文章:《消息与推送:订阅消息、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。
// 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 分钟后自动失效。
第二步:写入前先算字节,超限就淘汰
先量,再写。量不准,后面所有策略都是空的。
// 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),不再无限重试。
// 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。「存进去就一直在」这种假设,总会在某一台机器上被推翻。
以为离线队列能包住所有写操作。 它只能包住服务端可幂等接受、且晚到十分钟仍然成立的操作。库存扣减、优惠券核销、订单状态变更都不属于这一类,它们只能在线校验,失败就明确告诉用户失败。
小结
- 《消息与推送:订阅消息、uni-push 与厂商通道》把消息送出去,这一章管用户点开之后看到什么:弱网的关键特征是「API 认为网络正常」,所以判断依据是请求耗时,不是连通性回调。
- 缓存失效只有版本号前缀、TTL、容量淘汰三种可靠手段,其余都是猜。
- 写入前用 UTF-8 字节数判断,中文场景下
str.length会低估接近 3 倍。 - 离线队列要区分可重试与不可重试:5xx 退避重试,4xx 进死信,队列要有上限。
- 乐观更新必须留回滚快照;冲突裁决要先定规则再写代码,且规则要写进接口文档。
相关主题
到这里,一个小程序 + H5 + App 的主干功能已经齐了:界面、网络、支付、推送、离线。剩下的是把它们交付出去——《进阶:适配鸿蒙 NEXT 与上架》讲鸿蒙 NEXT 的适配细节、签名与上架流程,以及审核最常见的驳回原因。