cy-plugin-websocket

一个功能完整的 WebSocket 客户端封装库，支持心跳、自动重连、事件监听等特性。

✨ 特性

• 🔄 自动重连 - 支持指数退避重连策略
• 💓 心跳机制 - 可配置的心跳检测
• 📦 消息队列 - 连接断开时自动缓存消息
• 🎯 事件系统 - 基于 Emittery 的事件监听
• 🛡️ 类型安全 - 完整的 TypeScript 支持
• 🔧 高度可配置 - 丰富的配置选项

📦 安装

npm install cy-plugin-websocket

依赖要求

本项目依赖 emittery 作为事件系统，请确保已安装：

npm install emittery

🚀 快速开始

基础用法

注意： 使用事件监听时，请使用 enumSocketEvent 枚举而不是字符串，这样可以获得更好的类型安全性和 IDE 支持。

import SocketClient, {
  enumSocketEvent,
  enumSocketStatus,
  type ISocketOption
} from 'cy-plugin-websocket';

// 创建 WebSocket 连接
const socket = new SocketClient('wss://example.com/ws', {
  debug: true,
  autoReconnect: true
} satisfies ISocketOption);

// 建立连接
socket.connect();

// 监听事件
socket.on(enumSocketEvent.OPEN, () => {
  console.log('连接已建立');
});

socket.on(enumSocketEvent.MESSAGE, (data) => {
  console.log('收到消息:', data);
});

socket.on(enumSocketEvent.CLOSE, (code, reason) => {
  console.log('连接已关闭:', code, reason);
});

socket.on(enumSocketEvent.ERROR, (error) => {
  console.log('连接错误:', error);
});

// 发送消息
socket.send({ type: 'chat', message: 'Hello World' });

// 移除事件监听器
const messageHandler = (data) => {
  console.log('收到消息:', data);
};

socket.on(enumSocketEvent.MESSAGE, messageHandler);

// 稍后移除监听器
socket.off(enumSocketEvent.MESSAGE, messageHandler);

高级配置

import SocketClient, {
  enumSocketEvent,
  enumSocketStatus,
  type ISocketOption
} from 'cy-plugin-websocket';

const socket = new SocketClient('wss://example.com/ws', {
  // 开启调试模式
  debug: true,

  // 开启自动重连（默认 true）
  autoReconnect: true,

  // 断连时缓存消息，重连成功后重发
  connectResend: true,

  // 发送队列最大长度
  maxQueueSize: 100,

  // 连接超时（默认 10s）
  connectTimeout: 10000,

  // 心跳配置
  heartOption: {
    message: { type: 'ping' },
    interval: 30000, // 30秒心跳
    timeout: 60000 // 60秒未收到存活信号则断开重连
    // 仅 pong 重置超时（可选）
    // resetOnAnyMessage: false,
    // isPong: (data) => data?.type === 'pong'
  },

  // 重连配置
  reconnectOption: {
    maxCount: 10, // 最大重连次数（默认 10）
    interval: 2000, // 重连间隔
    maxInterval: 10000 // 最大重连间隔
  },

  // 自定义消息处理
  handleMessage: (data) => {
    console.log('处理消息:', data);
    return data;
  }
});

socket.connect();

// 使用 on 方法监听事件
socket.on(enumSocketEvent.OPEN, () => {
  console.log('连接已建立');
});

socket.on(enumSocketEvent.MESSAGE, (data) => {
  console.log('收到消息:', data);
});

// 使用 off 方法移除监听器
const errorHandler = (error) => {
  console.log('连接错误:', error);
};

socket.on(enumSocketEvent.ERROR, errorHandler);

// 稍后移除错误监听器
socket.off(enumSocketEvent.ERROR, errorHandler);

📚 API 文档

构造函数

new SocketClient(url: string, options?: ISocketOption)

参数

• url - WebSocket 服务器地址
• options - 配置选项（可选）

配置选项 (ISocketOption)

| 参数 | 类型 | 默认值 | 描述 | | ----------------- | --------------------------------- | ------- | -------------------------------------------------------- | | debug | boolean | false | 是否开启调试模式 | | autoReconnect | boolean | true | 是否自动重连 | | connectResend | boolean | false | 断连时是否缓存消息，并在重连后重发 | | maxQueueSize | number | 100 | 发送队列最大长度，超出后丢弃最旧消息 | | connectTimeout | number | 10000 | 连接超时（毫秒），0 关闭；超时仍 CONNECTING 则断开重连 | | heartOption | ISocketHeartOption | - | 心跳配置 | | reconnectOption | ISocketReconnectOption | - | 重连配置 | | handleMessage | (data: MessageEvent) => unknown | - | 消息处理函数 |

心跳配置 (ISocketHeartOption)

| 参数 | 类型 | 默认值 | 描述 | | ------------------- | ------------------------ | ------------------ | ------------------------------------------------------------- | | message | any | { beat: 'beat' } | 心跳消息内容 | | interval | number | 3000 | 心跳间隔（毫秒） | | timeout | number | interval * 2 | 超时未收到存活信号则主动断开重连；设为 0 关闭检测 | | resetOnAnyMessage | boolean | true | true：任意下行消息重置超时；false：仅 isPong 命中才重置 | | isPong | (data: any) => boolean | - | 心跳响应判定，在 resetOnAnyMessage=false 时使用 |

重连配置 (ISocketReconnectOption)

| 参数 | 类型 | 默认值 | 描述 | | ------------- | -------- | ------- | -------------------- | | maxCount | number | 10 | 最大重连次数 | | interval | number | 5000 | 重连间隔（毫秒） | | maxInterval | number | 60000 | 最大重连间隔（毫秒） |

方法

connect()

建立 WebSocket 连接

socket.connect();

send(message: unknown)

发送消息

// 发送对象
socket.send({ type: 'chat', message: 'Hello' });

// 发送字符串
socket.send('Hello World');

close()

主动关闭连接

socket.close();

destroy()

销毁连接并清理资源

socket.destroy();

on(event, listener)

添加事件监听器

import { enumSocketEvent } from 'cy-plugin-websocket';

// 监听连接建立事件
socket.on(enumSocketEvent.OPEN, () => {
  console.log('连接已建立');
});

// 监听消息事件
const messageHandler = (data) => {
  console.log('收到消息:', data);
};
socket.on(enumSocketEvent.MESSAGE, messageHandler);

// 监听连接关闭事件
socket.on(enumSocketEvent.CLOSE, (code, reason) => {
  console.log('连接已关闭:', code, reason);
});

// 监听错误事件
socket.on(enumSocketEvent.ERROR, (error) => {
  console.log('连接错误:', error);
});

off(event, listener)

移除事件监听器

// 移除特定的消息监听器
socket.off(enumSocketEvent.MESSAGE, messageHandler);

// 移除所有错误监听器
socket.off(enumSocketEvent.ERROR);

once(event, listener)

添加一次性事件监听器

// 只监听一次连接建立事件
socket.once(enumSocketEvent.OPEN, () => {
  console.log('连接已建立，只执行一次');
});

// 只监听一次消息事件
socket.once(enumSocketEvent.MESSAGE, (data) => {
  console.log('收到第一条消息:', data);
});

offAll()

移除所有事件监听器

// 移除所有事件的所有监听器
socket.offAll();

// 通常在组件销毁时使用
socket.destroy();
socket.offAll();

事件

| 事件 | 参数 | 描述 | | --------- | ------------ | -------- | | open | Event | 连接建立 | | message | unknown | 收到消息 | | close | CloseEvent | 连接关闭 | | error | Event | 连接错误 |

属性

state

获取当前连接状态

const state = socket.state;
// enumSocketStatus.CONNECTING
// enumSocketStatus.OPEN
// enumSocketStatus.CLOSING
// enumSocketStatus.CLOSED