网络状态监听与离线消息补发队列实现

举报
yd_284811271 发表于 2026/11/14 09:09:23 2026/11/14
【摘要】 前言在笔记场景中,用户经常在无网环境下编辑、新增笔记。如果每次编辑直接发起网络请求,会大量抛出异常;更好的方案是:所有待同步操作先进入离线队列,监听网络恢复后自动批量补发,同时和上一篇的后台定时同步能力配合使用,保证弱网、断网场景下数据不丢失。本文基于 @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();
}

六、踩坑与优化点

  1. 网络回调重复触发
    频繁切换Wi‑Fi/移动网时,netAvailable 会多次回调,内部增加 isRunning 锁,防止并发跑多个消费循环。
  2. 大文件图片任务阻塞文本同步
    可以拆成两个独立队列:文本高优队列、图片低优队列,文本优先补发,图片在空闲时段上传,和前面富文本图片上传逻辑配合。
  3. Preferences存储上限
    离线任务过多不适合全部塞Preferences,任务量很大时,建议把离线队列存在RDB里,支持分页查询。
  4. 区分网络类型
    拿到 netCapabilities 判断当前是 Wi‑Fi / 蜂窝流量,增加策略:蜂窝网络下,只自动同步文本,图片上传改为用户手动触发,节省流量。
const caps = await connection.getDefaultNetCapabilities();
const isWifi = caps.netTypes.includes(NetType.NET_TYPE_WIFI);
  1. 任务幂等性
    后端接口必须支持幂等,使用 taskId 作为幂等标识,防止网络抖动导致同一条笔记重复上传。
  2. 用户感知
    页面增加状态提示:「离线保存,联网后自动同步」,提供一个“手动立即同步”按钮,主动触发队列消费。

七、和上一篇后台同步的联动关系

  • 前台:网络监听 + 即时入队,联网自动跑队列;
  • 退后台:后台数据传输任务兜底,定时触发一次队列消费;
  • 断网:所有变更落本地RDB+离线任务队列,不丢失;
  • 网络恢复:系统回调驱动自动补发。

结语

离线队列是笔记类应用数据可靠性的基础能力。基于系统网络回调实现事件驱动的补发机制,相比轮询方案更加省电、贴合鸿蒙系统设计规范;配合持久化存储、重试限流、优先级调度,就可以给用户稳定的离线编辑体验。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。