[鸿蒙从零到一] HarmonyOS WebSocket 实战：断线重连、心跳保活与连接状态机设计

delay = min(baseDelay * 2^attempt, maxDelay) * (0.5 + random() * 0.5)

IDLE ──connect()──▶ CONNECTING ──open──▶ CONNECTED
  ▲                     │ error/timeout      │ heartbeat timeout / close / error
  │                     ▼                    ▼
  └──close()──── RECONNECT_WAIT ◀────────────┘
                     │ delay到期
                     └──────▶ CONNECTING （attempt+1）
任意状态 ──close()──▶ CLOSED（终态，不再自动重连）

// RobustWebSocket.ets
import{webSocket}from'@kit.NetworkKit';
import{BusinessError}from'@kit.BasicServicesKit';

exportenumWsState{
IDLE='IDLE',
CONNECTING='CONNECTING',
CONNECTED='CONNECTED',
RECONNECT_WAIT='RECONNECT_WAIT',
CLOSED='CLOSED'
}

exportinterfaceWsConfig{
url:string;
heartbeatIntervalMs:number;// 心跳间隔，建议 30000
pongTimeoutMs:number;// pong 超时，建议 10000
baseReconnectDelayMs:number;// 退避基数，建议 1000
maxReconnectDelayMs:number;// 退避封顶，建议 30000
maxRetries:number;// -1 表示无限重连
}

exportclassRobustWebSocket{
privatews:webSocket.WebSocket|null=null;
privatestate:WsState=WsState.IDLE;
privategeneration:number=0;// 代际号，防幽灵连接
privateattempt:number=0;// 当前重连次数
privateheartbeatTimer:number=-1;
privatepongTimer:number=-1;
privatereconnectTimer:number=-1;
privatesendQueue:string[]=[];// 断线期间的消息队列
privateconfig:WsConfig;

onMessage?:(data:string)=>void;
onStateChange?:(s:WsState)=>void;

constructor(config:WsConfig){
this.config=config;
}

privatesetState(s:WsState):void{
if(this.state===s){return;}
console.info(`[WS] ${this.state} -> ${s}`);
this.state=s;
this.onStateChange?.(s);
}

connect():void{
if(this.state!==WsState.IDLE&&this.state!==WsState.RECONNECT_WAIT){
return;// 状态机拒绝非法迁移
}
this.doConnect();
}

privatedoConnect():void{
constgen=++this.generation;// 本次尝试的代际号
this.setState(WsState.CONNECTING);
this.ws=webSocket.createWebSocket();

this.ws.on('open',()=>{
if(gen!==this.generation||this.state===WsState.CLOSED){
this.ws?.close();// 迟到的旧代际回调，直接丢弃
return;
}
this.attempt=0;
this.setState(WsState.CONNECTED);
this.startHeartbeat(gen);
this.flushQueue();
});

this.ws.on('message',(err:BusinessError,data:string|ArrayBuffer)=>{
if(gen!==this.generation){return;}
consttext=typeofdata==='string'?data:'';
if(text==='{"type":"pong"}'){
this.clearPongTimer();// 收到 pong，链路确认存活
return;
}
this.onMessage?.(text);
});

this.ws.on('close',()=>this.handleDead(gen));
this.ws.on('error',()=>this.handleDead(gen));

this.ws.connect(this.config.url,(err:BusinessError)=>{
if(err&&gen===this.generation){this.handleDead(gen);}
});
}

privatehandleDead(gen:number):void{
if(gen!==this.generation){return;}// 旧代际事件，忽略
if(this.state===WsState.CLOSED){return;}// 用户已主动关闭
this.stopHeartbeat();
this.scheduleReconnect();
}

privatescheduleReconnect():void{
if(this.config.maxRetries>=0&&this.attempt>=this.config.maxRetries){
this.close();
return;
}
this.setState(WsState.RECONNECT_WAIT);
// 指数退避 + 0.5~1.0 随机抖动
constraw=Math.min(
this.config.baseReconnectDelayMs*Math.pow(2,this.attempt),
this.config.maxReconnectDelayMs
);
constdelay=raw*(0.5+Math.random()*0.5);
this.attempt++;
console.info(`[WS] reconnect #${this.attempt} in ${Math.round(delay)}ms`);
this.reconnectTimer=setTimeout(()=>this.doConnect(),delay);
}

// —— 心跳 ——
privatestartHeartbeat(gen:number):void{
this.heartbeatTimer=setInterval(()=>{
if(gen!==this.generation||this.state!==WsState.CONNECTED){return;}
this.ws?.send('{"type":"ping"}');
this.pongTimer=setTimeout(()=>{
console.warn('[WS] pong timeout, connection is half-open');
this.ws?.close();// 主动关掉死连接
this.handleDead(gen);// close 事件可能不来，直接驱动状态机
},this.config.pongTimeoutMs);
},this.config.heartbeatIntervalMs);
}

privateclearPongTimer():void{
if(this.pongTimer!==-1){clearTimeout(this.pongTimer);this.pongTimer=-1;}
}

privatestopHeartbeat():void{
if(this.heartbeatTimer!==-1){clearInterval(this.heartbeatTimer);this.heartbeatTimer=-1;}
this.clearPongTimer();
}

// —— 发送与队列 ——
send(data:string):void{
if(this.state===WsState.CONNECTED){
this.ws?.send(data);
}elseif(this.state!==WsState.CLOSED){
if(this.sendQueue.length>=100){this.sendQueue.shift();}// 有界队列防内存膨胀
this.sendQueue.push(data);
}
}

privateflushQueue():void{
while(this.sendQueue.length>0&&this.state===WsState.CONNECTED){
this.ws?.send(this.sendQueue.shift()!);
}
}

// —— 用户主动关闭：终态，不再重连 ——
close():void{
this.generation++;// 使所有在途回调失效
this.setState(WsState.CLOSED);
this.stopHeartbeat();
if(this.reconnectTimer!==-1){clearTimeout(this.reconnectTimer);this.reconnectTimer=-1;}
this.ws?.close();
this.ws=null;
this.sendQueue=[];
}
}

// Index.ets
import{RobustWebSocket,WsState}from'./RobustWebSocket';

@Entry
@Component
structIndex{
@StateconnState:string='IDLE';
@StatelastMsg:string='';
privateclient:RobustWebSocket=newRobustWebSocket({
url:'wss://echo.websocket.events',
heartbeatIntervalMs:30000,
pongTimeoutMs:10000,
baseReconnectDelayMs:1000,
maxReconnectDelayMs:30000,
maxRetries:-1
});

aboutToAppear():void{
this.client.onStateChange=(s:WsState)=>{this.connState=s;};
this.client.onMessage=(msg:string)=>{this.lastMsg=msg;};
this.client.connect();
}

aboutToDisappear():void{
this.client.close();// 页面销毁必须走终态，否则定时器泄漏
}

build(){
Column({space:12}){
Text(`连接状态：${this.connState}`).fontSize(18)
Text(`最近消息：${this.lastMsg}`).fontSize(14).fontColor('#666')
Button('发送测试消息')
.onClick(()=>this.client.send(JSON.stringify({type:'chat',body:'hello'})))
}
.width('100%').padding(16)
}
}

"requestPermissions":[
{"name":"ohos.permission.INTERNET"}
]