websocket-heartbeat-js心跳檢測庫正式發布

前言：

兩年前寫了一篇websocket心跳的博客——初探和實現websocket心跳重連。  閱讀量一直比較大，加上最近考慮寫一個自己的npm包，因此就完成了一個websocket心跳的檢測庫。在這里先感謝幾個提供幫助的大佬朋友們，小弟受益匪淺。

 

介紹

websocket-heartbeat-js基於瀏覽器js原生websocket封裝，主要目的是保障客戶端websocket與服務端連接狀態。該程序有心跳檢測及自動重連機制，當網絡斷開或者后端服務問題造成客戶端websocket斷開，程序會自動嘗試重新連接直到再次連接成功。

原理

在使用原生websocket的時候，如果設備網絡斷開，不會觸發任何函數，前端程序無法得知當前連接已經斷開。這個時候如果調用websocket.send方法，瀏覽器就會發現消息發不出去，便會立刻或者一定短時間后（不同瀏覽器或者瀏覽器版本可能表現不同）觸發onclose函數。

后端websocket服務也可能出現異常，連接斷開后前端也並沒有收到通知，因此需要前端定時發送心跳消息ping，后端收到ping類型的消息，立馬返回pong消息，告知前端連接正常。如果一定時間沒收到pong消息，就說明連接不正常，前端便會執行重連。

為了解決以上兩個問題，以前端作為主動方，定時發送ping消息，用於檢測網絡和前后端連接問題。一旦發現異常，前端持續執行重連邏輯，直到重連成功。

約定

1.關閉websocket連接

如果需要斷開websocket，應該執行WebsocketHeartbeatJs.close()，WebsocketHeartbeatJs.ws是原生Websocket實例對象，WebsocketHeartbeatJs.ws.onclose，已經被綁定了重連方法，如果后端websocket服務直接關閉連接，前端WebsocketHeartbeatJs.ws.onclose會被執行，WebsocketHeartbeatJs會嘗試重連。如果后端想告訴前端需要斷開連接，需要發送特定消息給前端，前端收到特定消息，調用WebsocketHeartbeatJs.close()，WebsocketHeartbeatJs將不會重連。

websocketHeartbeatJs.onmessage = (e) => {
    if(e.data == 'close') websocketHeartbeatJs.close();
}

 

2.ping & pong

前端發送ping消息，后端收到后，需要立刻返回pong消息，pong消息可以是任何值，websocket-heartbeat-js並不處理pong消息，而只是在收到任何消息后，重置心跳，因為收到任何消息就說明連接是正常的。

 

用法

安裝

npm install websocket-heartbeat-js

引入使用

 

import WebsocketHeartbeatJs from 'websocket-heartbeat-js';
let websocketHeartbeatJs = new WebsocketHeartbeatJs({
    url: 'ws://xxxxxxx'
});
websocketHeartbeatJs.onopen = function () {
    console.log('connect success');
    websocketHeartbeatJs.send('hello server');
}
websocketHeartbeatJs.onmessage = function (e) {
    console.log(`onmessage: ${e.data}`);
}
websocketHeartbeatJs.onreconnect = function () {
    console.log('reconnecting...');
}

或者

 

<script src="./node_modules/websocket-heartbeat-js/dist/index.js"></script>
let websocketHeartbeatJs = new window.WebsocketHeartbeatJs({
    url: 'ws://xxxxxxx'
});

API

websocketHeartbeatJs.ws (WebSocket)

websocket-heartbeat-js僅僅是封裝了心跳相關的鈎子函數，websocketHeartbeatJs.ws是原生Websocket實例，如需要使用更多websocket特性，請直接操作websocketHeartbeatJs.ws。

websocketHeartbeatJs.ws 等於 WebSocket(websocketHeartbeatJs.opts.url);

 

websocketHeartbeatJs.opts (Object)

 

屬性	必填	類型	默認值	描述
url	true	string	none	websocket服務端接口地址
pingTimeout	false	number	15000	每隔15秒發送一次心跳，如果收到任何后端消息定時器將會重置
pongTimeout	false	number	10000	ping消息發送之后，10秒內沒收到后端消息便會認為連接斷開
reconnectTimeout	false	number	2000	嘗試重連的間隔時間
pingMsg	false	string	"heartbeat"	ping消息值

const options = {
    url: 'ws://xxxx',
    pingTimeout: 15000, 
    pongTimeout: 10000, 
    reconnectTimeout: 2000,
    pingMsg: "heartbeat"
}
let websocketHeartbeatJs = new WebsocketHeartbeatJs(options);

 

websocketHeartbeatJs.send(msg) (function)

 

發送消息給后端

websocketHeartbeatJs.send('hello server');

websocketHeartbeatJs.close() (function)

 

前端手動斷開websocket連接，此方法不會觸發重連。 websocketHeartbeatJs.close()

 

鈎子函數和事件函數

websocketHeartbeatJs.onclose (function)

websocketHeartbeatJs.onclose = () => {
    console.log('connect close');
}

 

websocketHeartbeatJs.onerror (function)

websocketHeartbeatJs.onerror = () => {
    console.log('connect onerror');
}

 

websocketHeartbeatJs.onopen (function)

websocketHeartbeatJs.onopen = () => {
    console.log('open success');
}

 

websocketHeartbeatJs.onmessage (function)

websocketHeartbeatJs.onmessage = (e) => {
    console.log('msg:', e.data);
}

 

websocketHeartbeatJs.onreconnect (function)

websocketHeartbeatJs.onreconnect = (e) => {
    console.log('reconnecting...');
}

demo

demo show

npmjs：https://www.npmjs.com/package/websocket-heartbeat-js

github：https://github.com/zimv/websocket-heartbeat-js