Enhanced Websocket Client

一个功能强大的 Websocket 客户端库，提供自动重连、心跳检测和断线恢复等高级特性。

安装

使用 npm 安装:

npm install enhanced-websocket

基本用法

import { EnhancedWebsocket } from "enhanced-websocket"

const ws = new EnhancedWebsocket({
  url: "wss://example.com/socket",
  debug: true,
})

ws.setEventHandlers({
  onOpen: () => console.log("Connected!"),
  onMessage: (event) => console.log("Received:", event.data),
  onClose: () => console.log("Disconnected"),
  onError: (error) => console.error("Error:", error),
})

// 发送消息
ws.send("Hello, server!")

配置选项

创建 EnhancedWebsocket 实例时可以传入以下配置选项： | 选项 | 类型 | 默认值 | 描述 | |----------------------|--------------------|-------------|----------------------------------------| | url | string | - | WebSocket 服务器地址（必填） | | pingTimeout | number | 5000 | 发送心跳包的间隔（毫秒） | | pongTimeout | number | 4000 | 等待心跳响应的超时时间（毫秒） | | reconnectTimeout | number | 4000 | 重连尝试的间隔时间（毫秒） | | pingMessage | string | "heartbeat" | 心跳包的内容 | | maxReconnectAttempts | number | 3 | 最大重连尝试次数 | | debug | boolean | false | 是否启用调试日志 | | initialMessage | string | object | "" | 连接建立后立即发送的消息 | | messageHandler | function | - | 消息处理函数 |

API

方法

• send(message: string | object): boolean
  发送消息到服务器。

• close(permanent: boolean = false): void
  关闭连接。如果 permanent 为 true，则不会自动重连。

• setEventHandlers(handlers: WebSocketEventHandlers): void
  设置事件处理器。

• getState(): number
  获取当前连接状态。

• isConnected(): boolean
  检查是否已连接。

• getActiveConnections(): number
  获取活跃连接数。

• destroy(): void
  销毁连接（永久关闭）。

事件处理器（通过 setEventHandlers 设置）

• onOpen
  连接建立时触发

• onClose
  连接关闭时触发

• onError
  发生错误时触发

• onMessage
  收到消息时触发

• onReconnect
  尝试重连时触发

高级用法

自定义心跳消息

const ws = new EnhancedWebsocket({
  url: "wss://example.com/socket",
  pingMessage: JSON.stringify({ type: "ping" }),
  pingTimeout: 10000, // 10 秒发送一次心跳
  pongTimeout: 5000, // 5 秒内未收到响应则认为断线
})

自动重连

默认情况下，连接断开时会自动尝试重连。你可以自定义重连行为：

const ws = new EnhancedWebsocket({
  url: "wss://example.com/socket",
  maxReconnectAttempts: 5,
  reconnectTimeout: 3000, // 每 3 秒尝试一次重连
})

调试模式

启用调试模式以查看详细日志：

const ws = new EnhancedWebsocket({
  url: "wss://example.com/socket",
  debug: true,
})

注意事项

• 确保在不再需要连接时调用 destroy() 方法以释放资源。
• 对于需要保持长连接的应用，建议适当设置 pingTimeout 和 pongTimeout。
• 在弱网环境下，可能需要增加 maxReconnectAttempts 和 reconnectTimeout 的值。