一、前置思考1.1 弱网场景是移动应用体验的分水岭地铁、地下停车场、隧道、乡村、跨境旅行——网络时有时无是常态。应用在弱网下能不能用、数据对不对决定了用户去留场景1: 地铁上看新闻 → 没网 → 直接白屏 → 卸载 场景2: 旅行App离线查攻略 → 数据是昨天的 → 用户投诉 场景3: 物流PDA离线签收 → 数据存本地 → 上线后要合并 → 冲突! 场景4: 地下车库导航 → 无网 → 关键数据要可用1.2 离线优先Offline-First架构思想传统架构: 网络是主, 缓存是辅 (无网即死) 离线优先: 本地是主, 网络是辅 (无网可用, 有网同步) 核心原则: ① 数据先写本地 (立即响应) ② 网络异步同步 (后台排队) ③ 冲突有策略 (不丢不覆盖) ④ 上线自动合并 (无感)1.3 本文路线深入弱网预加载、离线数据优先级、同步队列、冲突合并策略落地离线优先架构。二、核心原理2.1 弱网预加载策略预加载 提前把可能用到的数据拉到本地 策略1: 连接时预加载 (WIFI 下全量预热) 策略2: 页面预加载 (进入列表页预取详情页数据) 策略3: 智能预加载 (基于用户习惯预测) 优先级: WIFI: 预加载大体积 (视频/地图包) 蜂窝: 只预加载核心数据 (列表/关键详情) 弱网: 停止大文件, 保留文本核心2.2 离线数据优先级数据分级: P0 关键数据 (必须离线可用): 账号、基础配置、离线地图 P1 常用数据 (强烈建议离线): 首页列表、已读消息 P2 扩展数据 (有网加载): 大图、视频、完整详情 存储分层: P0 → 加密数据库 (可靠) P1 → KV/磁盘缓存 (快速) P2 → 不缓存, 按需加载2.3 同步队列机制本地写入 → 进入同步队列 (带操作类型 版本) 网络恢复 → 队列顺序同步 → 成功出队 → 失败重试 同步队列设计: 持久化: 队列存本地 (重启不丢) 幂等: 同一条数据重复同步不重复生效 顺序: 同一实体按操作顺序同步 重试: 指数退避, 上限封顶2.4 冲突合并策略冲突场景: 设备A离线改了订单, 设备B在线改了同一订单 策略1: LWW (最后写入胜) — 简单但可能丢用户意图 策略2: 字段级合并 — 不同字段各取所长 策略3: 操作级合并 — 累加操作 (计数器) 策略4: 冲突提示 — 无法自动合并时让用户选择 推荐: 按数据类型混合使用三、源码/API 深度解析3.1 离线优先写入层import{distributedKVStore}fromkit.ArkData;// 同步队列条目interfaceSyncOp{id:string;// 全局唯一操作 id (幂等)entity:string;// 实体类型key:string;// 实体 keyop:put|delete;data:string;// 数据快照ts:number;// 本地时间戳retries:number;}classOfflineSyncQueue{privatekv:distributedKVStore.SingleKVStore|nullnull;privatequeue:SyncOp[][];privatereadonlyMAX_RETRY5;asyncinit(kv:distributedKVStore.SingleKVStore):Promisevoid{this.kvkv;this.queueawaitthis.loadQueue();// 从本地恢复}// 离线写入: 先落本地 入队asyncenqueue(op:SyncOp):Promisevoid{if(this.kv){awaitthis.kv.put(entity:op.key,op.data);}this.queue.push(op);this.persistQueue();}// 上线同步: 顺序出队asyncflush(syncFn:(op:SyncOp)Promiseboolean):Promisevoid{constpendingthis.queue.slice();for(constopofpending){constokawaitsyncFn(op);if(ok){this.queuethis.queue.filter(oo.id!op.id);}else{op.retries;if(op.retriesthis.MAX_RETRY){// 超限: 保留待人工处理console.error(同步失败超限: op.id);}}}this.persistQueue();}privatepersistQueue():void{// 队列持久化到本地存储}privateasyncloadQueue():PromiseSyncOp[]{return[];}}3.2 弱网检测与预加载import{connection}fromkit.NetworkKit;// 网络状态监听: 恢复时触发同步, WIFI 时触发预加载functionwatchNetwork(onWifi:()void,onCellular:()void,onOffline:()void):void{connection.on(netAvailable,(info:connection.NetHandle){constcapsconnection.getConnectionProperties(info);if(capscaps.linkNamewlan){onWifi();// WIFI: 预加载大文件}else{onCellular();// 蜂窝: 预加载核心}});connection.on(netLost,(){onOffline();});}3.3 冲突合并实现// 字段级合并: 不同字段各取修改时间新者interfaceDocVersion{fields:Mapstring,{value:string;ts:number};}functionmergeFieldLevel(local:DocVersion,remote:DocVersion):DocVersion{constmergednewMap(local.fields);remote.fields.forEach((v,key){constlvlocal.fields.get(key);if(!lv||v.tslv.ts){merged.set(key,v);// 远程该字段更新}});return{fields:merged};}// 操作级合并 (计数器): 差值累加functionmergeCounter(local:number,remote:number,localStart:number,remoteStart:number):number{// 各自的增量叠加, 而不是覆盖returnlocal(remote-remoteStart);}四、企业级实战落地4.1 离线优先架构全景┌──────────────────────────────────────────────┐ │ 业务层: 列表/详情/操作 (先读本地, 立即响应) │ ├──────────────────────────────────────────────┤ │ 数据层: │ │ 本地读取 (P0/P1 缓存) → 命中? → 返回 │ │ → 未命中 → 有网? → 拉远端 → 回填本地 │ │ → 无网 → 返回离线态降级提示 │ ├──────────────────────────────────────────────┤ │ 同步层: │ │ 写入 → 本地立即生效 入同步队列 │ │ 恢复网络 → 队列同步 → 冲突合并 → 收敛 │ ├──────────────────────────────────────────────┤ │ 存储层: P0 数据库 / P1 KV / P2 不缓存 │ └──────────────────────────────────────────────┘4.2 数据优先级落地数据类型优先级离线策略存储账号/TokenP0必须离线加密 KV首页列表P1预热 缓存KV 磁盘已读消息P1本地优先数据库详情/大图P2在线加载不缓存4.3 同步冲突解决矩阵数据类型合并策略说明用户设置LWW后改覆盖计数器(点赞/步数)操作合并增量叠加文档字段字段级合并各取最新订单状态状态机校验非法迁移拒绝待办事项冲突提示用户选择4.4 离线体验指标指标目标离线可读率P0/P1 数据 100% 可读离线操作成功率写入本地 100% 成功同步成功率恢复后 ≥ 99%冲突率字段级 5%同步延迟恢复网络后 10s五、问题排查与性能优化坑现象原因解决离线白屏无网无数据未预加载P0/P1 预热数据丢失重启后离线数据没了队列未持久化队列落本地重复同步同数据同步两次无幂等全局操作 id同步乱序后写先同步无顺序控制按实体排序覆盖丢失离线修改被覆盖LWW 后写覆盖字段级合并同步卡死一条坏数据阻塞队列无超限处理重试上限 隔离内存膨胀离线缓存无限增长无容量/过期分级 TTL LRU5.1 队列持久化与崩溃恢复同步队列必须落本地 (KV/文件) 崩溃恢复: 启动时加载队列 → 未同步的重新入队 幂等保障: 每条操作带全局 id, 服务端去重5.2 弱网降级策略弱网判定: RTT 阈值 / 丢包率 / 连续失败 降级动作: ① 停止大文件传输 ② 图片降为缩略图 ③ 请求合并 (批量接口) ④ 进入只读模式 (禁用写操作) 或 离线模式 (全部本地)5.3 同步时机选择触发时机: 网络恢复 (netAvailable) 应用回到前台 (onForeground) 定时兜底 (每 30 分钟) 用户手动刷新 避让策略: 弱网不重试 (减少失败请求) WIFI 才同步大文件 低电量延迟同步六、高阶总结与最佳实践离线优先是架构不是补丁本地为主、网络为辅无网可用、有网收敛。数据分级定离线策略P0 必离线、P1 常缓存、P2 在线加载。同步队列三要素持久化、幂等、有序重试有上限。冲突合并按类型设置 LWW、计数器叠加、文档字段合并、订单状态机。弱网智能降级检测网络质量分级预加载、避让同步。一句话记住离线优先四步走——数据先落本地、网络异步同步、冲突按类型合并、弱网智能降级让应用在没网时也能可用、可信、不丢。
一、前置思考1.1 弱网场景是移动应用体验的分水岭地铁、地下停车场、隧道、乡村、跨境旅行——网络时有时无是常态。应用在弱网下能不能用、数据对不对决定了用户去留场景1: 地铁上看新闻 → 没网 → 直接白屏 → 卸载 场景2: 旅行App离线查攻略 → 数据是昨天的 → 用户投诉 场景3: 物流PDA离线签收 → 数据存本地 → 上线后要合并 → 冲突! 场景4: 地下车库导航 → 无网 → 关键数据要可用1.2 离线优先Offline-First架构思想传统架构: 网络是主, 缓存是辅 (无网即死) 离线优先: 本地是主, 网络是辅 (无网可用, 有网同步) 核心原则: ① 数据先写本地 (立即响应) ② 网络异步同步 (后台排队) ③ 冲突有策略 (不丢不覆盖) ④ 上线自动合并 (无感)1.3 本文路线深入弱网预加载、离线数据优先级、同步队列、冲突合并策略落地离线优先架构。二、核心原理2.1 弱网预加载策略预加载 提前把可能用到的数据拉到本地 策略1: 连接时预加载 (WIFI 下全量预热) 策略2: 页面预加载 (进入列表页预取详情页数据) 策略3: 智能预加载 (基于用户习惯预测) 优先级: WIFI: 预加载大体积 (视频/地图包) 蜂窝: 只预加载核心数据 (列表/关键详情) 弱网: 停止大文件, 保留文本核心2.2 离线数据优先级数据分级: P0 关键数据 (必须离线可用): 账号、基础配置、离线地图 P1 常用数据 (强烈建议离线): 首页列表、已读消息 P2 扩展数据 (有网加载): 大图、视频、完整详情 存储分层: P0 → 加密数据库 (可靠) P1 → KV/磁盘缓存 (快速) P2 → 不缓存, 按需加载2.3 同步队列机制本地写入 → 进入同步队列 (带操作类型 版本) 网络恢复 → 队列顺序同步 → 成功出队 → 失败重试 同步队列设计: 持久化: 队列存本地 (重启不丢) 幂等: 同一条数据重复同步不重复生效 顺序: 同一实体按操作顺序同步 重试: 指数退避, 上限封顶2.4 冲突合并策略冲突场景: 设备A离线改了订单, 设备B在线改了同一订单 策略1: LWW (最后写入胜) — 简单但可能丢用户意图 策略2: 字段级合并 — 不同字段各取所长 策略3: 操作级合并 — 累加操作 (计数器) 策略4: 冲突提示 — 无法自动合并时让用户选择 推荐: 按数据类型混合使用三、源码/API 深度解析3.1 离线优先写入层import{distributedKVStore}fromkit.ArkData;// 同步队列条目interfaceSyncOp{id:string;// 全局唯一操作 id (幂等)entity:string;// 实体类型key:string;// 实体 keyop:put|delete;data:string;// 数据快照ts:number;// 本地时间戳retries:number;}classOfflineSyncQueue{privatekv:distributedKVStore.SingleKVStore|nullnull;privatequeue:SyncOp[][];privatereadonlyMAX_RETRY5;asyncinit(kv:distributedKVStore.SingleKVStore):Promisevoid{this.kvkv;this.queueawaitthis.loadQueue();// 从本地恢复}// 离线写入: 先落本地 入队asyncenqueue(op:SyncOp):Promisevoid{if(this.kv){awaitthis.kv.put(entity:op.key,op.data);}this.queue.push(op);this.persistQueue();}// 上线同步: 顺序出队asyncflush(syncFn:(op:SyncOp)Promiseboolean):Promisevoid{constpendingthis.queue.slice();for(constopofpending){constokawaitsyncFn(op);if(ok){this.queuethis.queue.filter(oo.id!op.id);}else{op.retries;if(op.retriesthis.MAX_RETRY){// 超限: 保留待人工处理console.error(同步失败超限: op.id);}}}this.persistQueue();}privatepersistQueue():void{// 队列持久化到本地存储}privateasyncloadQueue():PromiseSyncOp[]{return[];}}3.2 弱网检测与预加载import{connection}fromkit.NetworkKit;// 网络状态监听: 恢复时触发同步, WIFI 时触发预加载functionwatchNetwork(onWifi:()void,onCellular:()void,onOffline:()void):void{connection.on(netAvailable,(info:connection.NetHandle){constcapsconnection.getConnectionProperties(info);if(capscaps.linkNamewlan){onWifi();// WIFI: 预加载大文件}else{onCellular();// 蜂窝: 预加载核心}});connection.on(netLost,(){onOffline();});}3.3 冲突合并实现// 字段级合并: 不同字段各取修改时间新者interfaceDocVersion{fields:Mapstring,{value:string;ts:number};}functionmergeFieldLevel(local:DocVersion,remote:DocVersion):DocVersion{constmergednewMap(local.fields);remote.fields.forEach((v,key){constlvlocal.fields.get(key);if(!lv||v.tslv.ts){merged.set(key,v);// 远程该字段更新}});return{fields:merged};}// 操作级合并 (计数器): 差值累加functionmergeCounter(local:number,remote:number,localStart:number,remoteStart:number):number{// 各自的增量叠加, 而不是覆盖returnlocal(remote-remoteStart);}四、企业级实战落地4.1 离线优先架构全景┌──────────────────────────────────────────────┐ │ 业务层: 列表/详情/操作 (先读本地, 立即响应) │ ├──────────────────────────────────────────────┤ │ 数据层: │ │ 本地读取 (P0/P1 缓存) → 命中? → 返回 │ │ → 未命中 → 有网? → 拉远端 → 回填本地 │ │ → 无网 → 返回离线态降级提示 │ ├──────────────────────────────────────────────┤ │ 同步层: │ │ 写入 → 本地立即生效 入同步队列 │ │ 恢复网络 → 队列同步 → 冲突合并 → 收敛 │ ├──────────────────────────────────────────────┤ │ 存储层: P0 数据库 / P1 KV / P2 不缓存 │ └──────────────────────────────────────────────┘4.2 数据优先级落地数据类型优先级离线策略存储账号/TokenP0必须离线加密 KV首页列表P1预热 缓存KV 磁盘已读消息P1本地优先数据库详情/大图P2在线加载不缓存4.3 同步冲突解决矩阵数据类型合并策略说明用户设置LWW后改覆盖计数器(点赞/步数)操作合并增量叠加文档字段字段级合并各取最新订单状态状态机校验非法迁移拒绝待办事项冲突提示用户选择4.4 离线体验指标指标目标离线可读率P0/P1 数据 100% 可读离线操作成功率写入本地 100% 成功同步成功率恢复后 ≥ 99%冲突率字段级 5%同步延迟恢复网络后 10s五、问题排查与性能优化坑现象原因解决离线白屏无网无数据未预加载P0/P1 预热数据丢失重启后离线数据没了队列未持久化队列落本地重复同步同数据同步两次无幂等全局操作 id同步乱序后写先同步无顺序控制按实体排序覆盖丢失离线修改被覆盖LWW 后写覆盖字段级合并同步卡死一条坏数据阻塞队列无超限处理重试上限 隔离内存膨胀离线缓存无限增长无容量/过期分级 TTL LRU5.1 队列持久化与崩溃恢复同步队列必须落本地 (KV/文件) 崩溃恢复: 启动时加载队列 → 未同步的重新入队 幂等保障: 每条操作带全局 id, 服务端去重5.2 弱网降级策略弱网判定: RTT 阈值 / 丢包率 / 连续失败 降级动作: ① 停止大文件传输 ② 图片降为缩略图 ③ 请求合并 (批量接口) ④ 进入只读模式 (禁用写操作) 或 离线模式 (全部本地)5.3 同步时机选择触发时机: 网络恢复 (netAvailable) 应用回到前台 (onForeground) 定时兜底 (每 30 分钟) 用户手动刷新 避让策略: 弱网不重试 (减少失败请求) WIFI 才同步大文件 低电量延迟同步六、高阶总结与最佳实践离线优先是架构不是补丁本地为主、网络为辅无网可用、有网收敛。数据分级定离线策略P0 必离线、P1 常缓存、P2 在线加载。同步队列三要素持久化、幂等、有序重试有上限。冲突合并按类型设置 LWW、计数器叠加、文档字段合并、订单状态机。弱网智能降级检测网络质量分级预加载、避让同步。一句话记住离线优先四步走——数据先落本地、网络异步同步、冲突按类型合并、弱网智能降级让应用在没网时也能可用、可信、不丢。
