鸿蒙操作系统使用 WebSocket 实现长连接实时通信实战(本文已在AtomGit仓库开源)
一、背景说明
腾讯 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等)或改由服务端推送通知。
六、扩展建议
- 消息分帧:为不同业务定义消息类型字段(心跳/业务/ACK),复用一条连接承载多类推送;
- 断线期间缓存:重连等待期把待发消息压入队列,
open后按序补发,保证命令不丢; - 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 全文。
更多推荐




所有评论(0)