一、背景说明

腾讯 AI 助手 Marvis 等重量级应用本周接连完成鸿蒙原生适配,实时消息类场景(客服对话、行情推送、协同状态)在鸿蒙上的标准做法是建立 WebSocket 长连接。本文聚焦一个具体技术点:使用 @ohos.net.webSocket 模块实现应用与服务端的 WebSocket 长连接——建连、收发消息、心跳保活与断线自动重连,全部代码可直接编译运行(本文源码已在 AtomGit 仓库开源,见文末)。

二、技术原理

@ohos.net.webSocket 属于 Basic Services Kit 的网络能力,与 HTTP 短请求不同,WebSocket 在一条 TCP 连接上全双工通信,服务端可主动推送。核心 API:

  • createWebSocket():创建 webSocket.WebSocket 实例;
  • connect(url):建连,url 支持 ws:// 与 wss://(需声明 ohos.permission.INTERNET 权限);
  • on(‘open’|‘message’|‘close’|‘error’):生命周期与数据回调,'message' 的数据可能是字符串也可能是二进制 ArrayBuffer,需按实际协议区分;
  • send():发送数据(每次建议不超过 64KB,超限需分片);
  • close():主动关闭,携带 code 与 reason 交给服务端确认。

连接管理的关键是心跳保活与指数退避重连:移动网络下 NAT 超时、切 Wi-Fi/蜂窝都会静默断链,客户端用小数据包定时 ping 保持活跃,检测到 error/close 后按 2^n 秒退避重连,避免风暴式重试。数据流:

connect(url) → on('open') 启动心跳 → send 发送业务包 → on('message') 接收推送 → on('close'/'error') 停心跳 → 退避重连 → on('open') 恢复。

三、实现步骤

工程为 Stage 模型(API 12+),在 module.json5 中声明网络权限:

{
  "module": {
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" }
    ]
  }
}
1. 长连接管理类 WebSocketUtil.ets
import { webSocket } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

export type MessageHandler = (message: string) => void;

export class WebSocketUtil {
  private ws: webSocket.WebSocket | null = null;
  private url: string = '';
  private heartbeatId: number = -1;
  private reconnectDelay: number = 1000; // 初始重连间隔 1s
  private connected: boolean = false;
  private messageHandler: MessageHandler | null = null;

  // 建连:注册全套回调;断开后自动重连
  connect(url: string, onMessage: MessageHandler): void {
    this.url = url;
    this.messageHandler = onMessage;
    this.ws = webSocket.createWebSocket();

    this.ws.on('open', () => {
      this.connected = true;
      this.reconnectDelay = 1000; // 连接成功,重连间隔复位
      this.startHeartbeat();
    });

    this.ws.on('message', (err: BusinessError, message: string | ArrayBuffer) => {
      if (err) { return; }
      if (typeof message === 'string') {
        this.messageHandler?.(message);
      } else {
        // 二进制消息按自定义协议解析,此处演示转字符串
        this.messageHandler?.(new util.TextDecoder().decodeToString(new Uint8Array(message)));
      }
    });

    this.ws.on('close', (err: BusinessError, code: number, reason: string) => {
      this.connected = false;
      this.stopHeartbeat();
      this.reconnect(); // 服务端关闭后自动重连
    });

    this.ws.on('error', (err: BusinessError) => {
      this.connected = false;
      this.stopHeartbeat();
      this.reconnect(); // 网络异常后自动重连
    });

    this.ws.connect(url, (err: BusinessError) => {
      if (err) {
        console.error(`connect failed, code=${err.code}`);
        this.reconnect();
      }
    });
  }

  // 发送文本消息(WebSocket 单包建议不超过 64KB)
  send(message: string): void {
    if (!this.connected || !this.ws) {
      console.error('not connected, message queued instead');
      return;
    }
    this.ws.send(message, (err: BusinessError) => {
      if (err) { console.error(`send failed, code=${err.code}`); }
    });
  }

  // 心跳:每 20s 发送一次 ping 帧,防止 NAT 超时静默断链
  private startHeartbeat(): void {
    this.stopHeartbeat();
    this.heartbeatId = setInterval(() => {
      this.ws?.send('ping', (err: BusinessError) => {
        if (err) { this.reconnect(); }
      });
    }, 20000);
  }

  private stopHeartbeat(): void {
    if (this.heartbeatId !== -1) {
      clearInterval(this.heartbeatId);
      this.heartbeatId = -1;
    }
  }

  // 指数退避重连:1s → 2s → 4s → ... → 32s 封顶
  private reconnect(): void {
    this.stopHeartbeat();
    setTimeout(() => {
      console.info(`reconnecting, delay=${this.reconnectDelay}ms`);
      this.connect(this.url, this.messageHandler!);
    }, this.reconnectDelay);
    this.reconnectDelay = Math.min(this.reconnectDelay * 2, 32000);
  }

  // 主动关闭并停止一切重连
  close(): void {
    this.stopHeartbeat();
    this.connected = false;
    this.ws?.close('正常退出', 1000);
    this.ws = null;
  }
}
2. UI 调用示例 Index.ets
import { WebSocketUtil } from '../model/WebSocketUtil';

@Entry
@Component
struct Index {
  @State received: string = '';
  @State inputText: string = '';
  private wsUtil: WebSocketUtil = new WebSocketUtil();

  build() {
    Column({ space: 12 }) {
      Text('WebSocket 长连接').fontSize(16).fontWeight(FontWeight.Bold)

      Button('建立连接').onClick(() => {
        // 连接测试服务的公开回显地址,真实场景替换为自己的 wss 服务
        this.wsUtil.connect('wss://echo.websocket.events', (message: string) => {
          this.received = `${this.received}\n收到:${message}`;
        });
      })

      TextInput({ placeholder: '输入要发送的内容' })
        .width('90%')
        .onChange((value: string) => { this.inputText = value; })

      Button('发送').onClick(() => {
        this.wsUtil.send(this.inputText);
      })

      Button('断开连接').onClick(() => {
        this.wsUtil.close();
        this.received = '';
      })

      Text(this.received || '接收记录')
        .fontSize(13)
        .width('90%')
        .height(160)
        .backgroundColor('#F2F3F5')
        .padding(10)
        .borderRadius(8)
        .alignSelf(ItemAlign.Center)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}
四、应用场景示例

订阅行情/状态推送时,把收到的一条消息按业务协议拆分后驱动 UI:

// 服务端推送 JSON:{"type":"price","symbol":"HOS","value":12.8}
this.wsUtil.connect('wss://push.example.com/realtime', (message: string) => {
  try {
    const data: Record<string, string> = JSON.parse(message) as Record<string, string>;
    if (data.type === 'price') {
      AppStorage.setOrCreate('lastPrice', data.value); // 全局状态联动刷新
    }
  } catch (e) {
    console.error('invalid push message');
  }
});
五、技术要点
1. 心跳与重连的边界

心跳间隔应小于服务端/NAT 的空闲超时(常用 20~30s);重连必须用指数退避并封顶(如 32s),否则服务端短暂抖动会引发客户端风暴式重试。本文实现已内置:连接成功即复位退避值,错误后翻倍。

2. 回调生命周期陷阱

on('message') 等回调注册在旧实例上,重连 createWebSocket() 后是新实例,必须重新注册全套回调——本文通过把注册逻辑放进 connect() 解决;页面销毁时调用 close(),避免泄漏。

3. 错误处理
this.ws.on('error', (err: BusinessError) => {
  if (err.code === 2302999) {
    console.error('连接失败,检查网络与证书(wss 需有效 TLS)');
  } else {
    console.error(`ws error code=${err.code}`);
  }
});
4. 使用限制
  • 需声明 ohos.permission.INTERNET;生产环境应使用 wss:// 加密通道;
  • 单条消息建议不超过 64KB,大报文需在应用层分片;
  • 应用退后台后长连接可能被系统管控,需要持续收消息的场景应配合长时任务(audioPlayback 等)或改由服务端推送通知。
六、扩展建议
  1. 消息分帧:为不同业务定义消息类型字段(心跳/业务/ACK),复用一条连接承载多类推送;
  2. 断线期间缓存:重连等待期把待发消息压入队列,open 后按序补发,保证命令不丢;
  3. TLS 加固:wss 服务端配置单向证书即可满足多数场景,对证书校验有特殊要求时可使用自建证书校验回调:
// 连接 wss 地址,其余流程与 ws 一致
this.ws.connect('wss://push.example.com/realtime', (err: BusinessError) => { /* ... */ });
结语

本文用 @ohos.net.webSocket 完成了鸿蒙应用长连接从建连、心跳保活、指数退避重连到消息收发的完整实现,核心代码约 150 行,均已开源到文末 AtomGit 仓库。理解连接生命周期与重连边界后,客服对话、行情推送等实时场景都能在鸿蒙上稳定承载。

代码仓库

本文完整工程已在 AtomGit 开源:https://atomgit.com/NJPJI_Yang/hm-article-20261122-websocket-atomgit

仓库包含可直接用 DevEco Studio 打开编译的完整鸿蒙 Stage 工程(AppScope 应用配置、entry 模块、module.json5 权限、hvigor 构建脚本齐全),以及与 CSDN 发布内容一致的 article.md 全文。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐