网络状态监听与离线消息补发队列实现
【摘要】 前言在笔记场景中,用户经常在无网环境下编辑、新增笔记。如果每次编辑直接发起网络请求,会大量抛出异常;更好的方案是:所有待同步操作先进入离线队列,监听网络恢复后自动批量补发,同时和上一篇的后台定时同步能力配合使用,保证弱网、断网场景下数据不丢失。本文基于 @ohos.net.connection 实现网络监听,搭配内存+持久化离线任务队列。 一、方案选型@ohos.net.connectio...
前言
在笔记场景中,用户经常在无网环境下编辑、新增笔记。如果每次编辑直接发起网络请求,会大量抛出异常;更好的方案是:所有待同步操作先进入离线队列,监听网络恢复后自动批量补发,同时和上一篇的后台定时同步能力配合使用,保证弱网、断网场景下数据不丢失。本文基于 @ohos.net.connection 实现网络监听,搭配内存+持久化离线任务队列。
一、方案选型
@ohos.net.connection:系统原生网络管理模块,可以获取网络类型、注册网络状态变化回调,不需要额外三方库;- 队列持久化:离线任务不能只放内存,应用被杀死后会丢失,使用 Preferences 序列化存储任务队列;
- 执行策略:联网后按顺序补发,单任务失败单独重试,不阻塞整个队列;区分普通文本任务、图片上传任务(图片任务优先级更低)。
对比:单纯依靠轮询检测网络功耗高;系统网络回调是事件驱动,只有网络变化时触发,更省电。
二、权限配置
module.json5
"requestPermissions": [
{
"name": "ohos.permission.GET_NETWORK_INFO",
"reason": "监听网络状态,实现离线笔记自动补发",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
}
]
三、离线任务模型定义
// model/OfflineTask.ets
export enum TaskType {
UPLOAD_NOTE = 1,
UPLOAD_IMAGE = 2,
DELETE_NOTE = 3
}
export interface OfflineTask {
taskId: string;
type: TaskType;
payload: string; // 序列化后的笔记/图片信息
retryCount: number;
maxRetry: number;
createTime: number;
}
四、离线队列管理 + 网络监听封装
// utils/OfflineSyncQueue.ets
import { connection, NetType } from '@kit.NetworkKit';
import { preferences } from '@kit.DataStoreKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { http } from '@kit.NetworkKit';
import { util } from '@kit.UtilsKit';
const STORE_NAME = "offline_task_queue";
const TASK_KEY = "task_list";
export class OfflineSyncQueue {
private static ins: OfflineSyncQueue;
private prefs: preferences.Preferences | null = null;
private netSubscriber: number | null = null;
private isOnline: boolean = false;
private isRunning: boolean = false;
private taskList: OfflineTask[] = [];
static getInstance() {
if (!OfflineSyncQueue.ins) {
OfflineSyncQueue.ins = new OfflineSyncQueue();
}
return OfflineSyncQueue.ins;
}
async init() {
// 加载本地持久化队列
this.prefs = await preferences.getPreferences(getContext(), STORE_NAME);
const raw = await this.prefs.getSync(TASK_KEY, "[]") as string;
this.taskList = JSON.parse(raw);
// 获取初始网络状态
const netCap = await connection.getDefaultNetCapabilities();
this.isOnline = netCap.netTypes.length > 0;
// 注册网络监听
this.netSubscriber = connection.on('netAvailable', () => {
this.isOnline = true;
this.runQueue();
});
connection.on('netUnavailable', () => {
this.isOnline = false;
})
// 如果初始化时已经联网,直接消费队列
if (this.isOnline) {
this.runQueue();
}
}
// 添加任务到离线队列
async addTask(task: OfflineTask) {
this.taskList.push(task);
await this.saveQueue();
// 在线状态直接尝试执行
if (this.isOnline) {
this.runQueue();
}
}
// 持久化队列到Preferences
private async saveQueue() {
if (!this.prefs) return;
await this.prefs.putSync(TASK_KEY, JSON.stringify(this.taskList));
await this.prefs.flush();
}
// 消费任务队列
private async runQueue() {
if (this.isRunning || !this.isOnline || this.taskList.length === 0) return;
this.isRunning = true;
while (this.taskList.length > 0) {
const task = this.taskList[0];
const ok = await this.executeTask(task);
if (ok) {
// 成功,移除任务
this.taskList.shift();
} else {
task.retryCount += 1;
if (task.retryCount >= task.maxRetry) {
// 超过最大重试,移出队列,可写入失败日志,留给用户手动重试
this.taskList.shift();
console.warn(`任务${task.taskId}超过重试上限,放弃自动补发`);
}
// 失败,退出循环,等待下一次网络变化再尝试
break;
}
await this.saveQueue();
}
this.isRunning = false;
}
// 执行单个任务
private async executeTask(task: OfflineTask): Promise<boolean> {
try {
switch (task.type) {
case TaskType.UPLOAD_NOTE:
return await this.uploadNote(JSON.parse(task.payload));
case TaskType.UPLOAD_IMAGE:
return await this.uploadImage(JSON.parse(task.payload));
case TaskType.DELETE_NOTE:
return await this.deleteRemoteNote(JSON.parse(task.payload));
default:
return true;
}
} catch (err) {
console.error("任务执行异常", task.taskId, err);
return false;
}
}
private async uploadNote(note: any): Promise<boolean> {
// 模拟http上传笔记
// let res = await http.request(...)
return true;
}
private async uploadImage(imgInfo: any): Promise<boolean> {
// 图片上传,耗时更长,可单独限流
return true;
}
private async deleteRemoteNote(noteId: string): Promise<boolean> {
// 远端删除接口
return true;
}
// 销毁监听,释放资源,在Ability销毁时调用
destroy() {
if (this.netSubscriber !== null) {
connection.off('netAvailable', this.netSubscriber);
connection.off('netUnavailable');
}
}
}
五、业务侧使用示例
新增笔记时,不直接调用上传接口,统一入队:
// 编辑页保存笔记
async function saveNote(content: string) {
const noteData = {
id: util.generateRandomUUID(),
content,
updateTime: Date.now()
}
// 写入本地RDB
await NoteRdb.insertNote(noteData);
// 加入离线补发队列
const queue = OfflineSyncQueue.getInstance();
await queue.addTask({
taskId: util.generateRandomUUID(),
type: TaskType.UPLOAD_NOTE,
payload: JSON.stringify(noteData),
retryCount: 0,
maxRetry: 5,
createTime: Date.now()
})
}
在 EntryAbility 初始化和销毁:
import { OfflineSyncQueue } from '../utils/OfflineSyncQueue.ets';
onCreate() {
OfflineSyncQueue.getInstance().init();
}
onDestroy() {
OfflineSyncQueue.getInstance().destroy();
}
六、踩坑与优化点
- 网络回调重复触发
频繁切换Wi‑Fi/移动网时,netAvailable会多次回调,内部增加isRunning锁,防止并发跑多个消费循环。 - 大文件图片任务阻塞文本同步
可以拆成两个独立队列:文本高优队列、图片低优队列,文本优先补发,图片在空闲时段上传,和前面富文本图片上传逻辑配合。 - Preferences存储上限
离线任务过多不适合全部塞Preferences,任务量很大时,建议把离线队列存在RDB里,支持分页查询。 - 区分网络类型
拿到netCapabilities判断当前是 Wi‑Fi / 蜂窝流量,增加策略:蜂窝网络下,只自动同步文本,图片上传改为用户手动触发,节省流量。
const caps = await connection.getDefaultNetCapabilities();
const isWifi = caps.netTypes.includes(NetType.NET_TYPE_WIFI);
- 任务幂等性
后端接口必须支持幂等,使用taskId作为幂等标识,防止网络抖动导致同一条笔记重复上传。 - 用户感知
页面增加状态提示:「离线保存,联网后自动同步」,提供一个“手动立即同步”按钮,主动触发队列消费。
七、和上一篇后台同步的联动关系
- 前台:网络监听 + 即时入队,联网自动跑队列;
- 退后台:后台数据传输任务兜底,定时触发一次队列消费;
- 断网:所有变更落本地RDB+离线任务队列,不丢失;
- 网络恢复:系统回调驱动自动补发。
结语
离线队列是笔记类应用数据可靠性的基础能力。基于系统网络回调实现事件驱动的补发机制,相比轮询方案更加省电、贴合鸿蒙系统设计规范;配合持久化存储、重试限流、优先级调度,就可以给用户稳定的离线编辑体验。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论(0)