@jinfeitec/websocket-service

一个WebSocket服务库，支持单例模式、发布订阅模式、自动重连、心跳机制等高级功能。

特性

• 单例模式: 使用ES6 Class + 闭包实现单例，确保整个应用只有一个WebSocket连接实例
• 发布订阅模式: 维护订阅列表，通过消息类型关联对应的回调函数，实现多组件订阅同一类型消息
• 自动重连: 使用指数退避算法实现智能重连
• 心跳机制: 定时发送心跳包维持连接
• 消息队列: 连接未就绪时自动缓存消息
• 连接状态通知: 提供onConnected/onDisconnected事件通知
• 消息压缩: 对大消息使用JSON.stringify + gzip压缩
• 类型化消息: 支持基于类型的消息收发
• TypeScript支持: 提供完整的类型定义

安装

npm install @jinfeitec/websocket-service

基本用法

import WebSocketService from '@jinfeitec/websocket-service';

// 获取单例实例
const ws = WebSocketService.getInstance();

// 连接到WebSocket服务器
ws.connect('wss://your-websocket-server.com')
  .then(() => {
    console.log('连接成功');
  })
  .catch(error => {
    console.error('连接失败:', error);
  });

// 发送消息
ws.send('Hello, WebSocket!');

// 发送类型化消息
ws.sendTypedMessage('chat', {
  content: '你好！',
  sender: 'user1'
});

// 订阅特定类型的消息
const unsubscribe = ws.subscribe('chat', (payload, message) => {
  console.log('收到聊天消息:', payload);
  console.log('完整消息对象:', message);
});

// 注册连接事件
ws.onConnected(() => {
  console.log('WebSocket已连接');
});

ws.onDisconnected((event) => {
  console.log('WebSocket已断开连接:', event);
});

// 取消订阅
unsubscribe();

// 断开连接
ws.disconnect();

在Vue 3中使用

请查看 examples/vue-example.js 获取完整示例。

配置选项

const ws = WebSocketService.getInstance({
  // 重连配置
  reconnect: {
    enabled: true,        // 是否启用自动重连
    maxAttempts: 10,      // 最大重连尝试次数
    baseDelay: 1000,      // 基础延迟时间（毫秒）
    maxDelay: 30000       // 最大延迟时间（毫秒）
  },
  // 心跳配置
  heartbeat: {
    enabled: true,        // 是否启用心跳
    interval: 10000,      // 心跳间隔（毫秒）
    message: 'ping',      // 心跳消息内容
    loseLimit: 5,         // 允许丢失心跳的最大次数
    responseTimeout: 3000 // 心跳响应超时时间（毫秒）
  },
  // 消息压缩配置
  compression: {
    enabled: true,        // 是否启用消息压缩
    threshold: 1024       // 压缩阈值（字节）
  },
  // 日志配置
  logging: {
    enabled: true,        // 是否启用日志
    level: 'info'         // 日志级别: 'debug', 'info', 'warn', 'error'
  }
});

API文档

核心方法

• WebSocketService.getInstance(config): 获取WebSocketService单例实例
• connect(url): 连接到WebSocket服务器
• disconnect(): 断开WebSocket连接
• send(message): 发送消息
• sendTypedMessage(type, payload): 发送带类型的消息
• subscribe(type, callback): 订阅消息
• unsubscribe(type, callback): 取消订阅消息
• onConnected(callback): 注册连接成功回调
• onDisconnected(callback): 注册断开连接回调
• onError(callback): 注册错误回调
• getState(): 获取当前连接状态
• getUrl(): 获取当前连接URL
• getQueueLength(): 获取消息队列长度
• clearQueue(): 清空消息队列
• destroy(): 销毁实例

许可证

MIT