🔥 轻松管理 WebSocket 连接!easy-websocket-client
🔥 轻松管理 WebSocket 连接!easy-websocket-client
在前端开发中,WebSocket 是实现实时通信的核心技术,但原生 WebSocket 的连接管理(如断连重连、心跳维护、事件监听)往往需要编写大量重复代码。今天给大家分享一个自己开发的 WebSocket 连接管理库 —— easy-websocket-client,帮你一站式解决连接管理难题,专注业务逻辑开发!
🚀 核心优势
- 极简集成:一行代码创建连接,内置常用配置项,开箱即用。
- 智能重连:自动处理断连重连,支持最大重连次数和间隔配置。
- 心跳机制:可自定义心跳消息和间隔,保持连接活性。
- 灵活事件:支持连接打开、关闭、消息接收、错误等全生命周期回调。
- 单例模式:轻松实现全局唯一连接,避免重复创建和内存泄漏。
- TypeScript 支持:全程 TypeScript 开发,提供完善类型定义,智能提示更友好。
🛠 主要功能特性
1. 自动重连机制
- reconnectInterval:重连间隔
- maxReconnectAttempts:最大重连次数
- 断连后自动发起重连,达到最大次数后停止尝试
- 适用于网络不稳定场景,减少手动处理重连的繁琐代码
2. 可定制化心跳
- heartbeatMessage:自定义心跳消息内容(支持字符串或对象)
- heartbeatInterval:心跳发送间隔
- 自动检测服务端响应,心跳失败时触发重连
3. 全生命周期事件回调
onOpen
:连接成功时触发onClose
:连接关闭时触发(携带CloseEvent
参数)onMessage
:接收消息时触发(自动解析文本/二进制数据)onError
:连接报错时触发(捕获网络错误等异常)
4. 单例模式支持
- 装饰器方式:通过
@singleton
装饰器快速实现单例类 - 高阶函数方式:兼容不支持装饰器的环境,通过
singleton
函数包裹 - 刷新页面自动恢复连接,避免多页面重复创建
📦 快速上手
安装
# npm
npm install easy-websocket-client
# yarn
yarn add easy-websocket-client
# pnpm
pnpm add easy-websocket-client
基础使用示例
import WebSocketClient from 'easy-websocket-client';
// 创建连接实例
const client = new WebSocketClient('wss://example.com/socket', {
showLog: true, // 开启控制台日志
reconnectInterval: 2000, // 重连间隔 2 秒
heartbeatInterval: 10000, // 心跳间隔 10 秒
heartbeatMessage: 'ping', // 心跳消息
maxReconnectAttempts: 5, // 最大重连次数
onOpen: () => console.log('连接已打开'),
onClose: (e) => console.log('连接关闭', e),
onMessage: (message) => console.log('收到消息', message),
onError: (error) => console.error('连接错误', error),
});
// 发起连接
client.connect();
// 发送消息
client.send('Hello WebSocket!');
// 关闭连接
client.close();
单例模式实现(装饰器方式)
import { singleton } from 'easy-websocket-client';
interface Message {
type: string;
data: any;
}
@singleton
class MyWebSocketClient extends WebSocketClient<Message> {
constructor() {
// 动态生成连接地址(支持开发/生产环境区分)
const baseURL = import.meta.env.DEV
? `ws://${import.meta.env.VITE_WS_HOST}:${import.meta.env.VITE_PORT}/ws`
: import.meta.env.VITE_API_URL;
super(baseURL, {
heartbeatMessage: { type: 'HEARTBEAT', textMsg: 'ping' }, // 对象类型心跳消息
heartbeatInterval: 10000,
maxReconnectAttempts: 3,
connectResend: true, // 重连后自动重发未完成的消息
onMessage(data) {
console.log('业务消息处理:', data);
},
});
this.connect();
}
// 支持手动关闭并重置单例
public close = () => {
super.close();
MyWebSocketClient.reset(); // 重置单例实例
};
}
// 全局唯一实例
const clientInstance = new MyWebSocketClient();
📌 适用场景
- 实时聊天系统(如客服对话、直播间弹幕)
- 通知中心(如新消息提醒、系统公告推送)
- 实时数据监控(如仪表盘数据实时更新)
- 协同编辑工具(多人协作场景下的状态同步)
- 游戏实时交互(低延迟的游戏状态同步)
🧰 技术栈说明
- 基于原生 WebSocket 封装,支持浏览器和 Node.js(通过
ws
库) - 使用 TypeScript 开发,提供完整类型定义
- 支持 UMD 规范,可直接通过
<script>
标签引入 - 内置代码检查(ESLint)和单元测试(Jest),保证稳定性
📚 项目地址
如果觉得这个库对你有帮助,欢迎 Star ⭐ 支持!也欢迎提 Issue 或 PR 一起完善~
有任何使用问题或需求,欢迎在评论区交流,我会及时回复 😊
本作品采用《CC 协议》,转载必须注明作者和本文链接