WebSocket 重连技能

可靠的 WebSocket 连接管理，包含指数退避 + 抖动重连算法、心跳检测和断路器模式。

特性

• - 指数退避重连: 智能重试策略，延迟时间指数增长
• 随机抖动 (Jitter): 防止群震问题 (thundering herd)
• 心跳检测: 自动检测僵死连接并触发重连
• 断路器模式: 三种状态 (CLOSED, OPEN, HALF-OPEN) 防止级联故障
• 最大重试上限: 避免无限重试消耗资源
• 事件驱动: 完整的事件系统用于状态监控

安装依赖

bash
npm install ws

快速开始

基础用法

javascript
const { WebSocketReconnect } = require(./scripts/websocket-reconnect.js);

const ws = new WebSocketReconnect({
url: wss://api.example.com/socket,
maxRetries: 10,
baseDelay: 1000,
maxDelay: 30000
});

// 监听事件
ws.on(open, () => {
console.log(✅ 已连接);
});

ws.on(message, (event) => {
console.log(📨 收到消息:, event.data);
});

ws.on(close, (event) => {
console.log(❌ 已关闭:, event.code, event.reason);
});

ws.on(error, (error) => {
console.error(⚠️ 错误:, error.message);
});

ws.on(retry, (info) => {
console.log(🔄 重试 ${info.attempt}/${info.maxRetries}，等待 ${info.delay}ms);
});

// 连接
ws.connect();

// 发送消息
ws.send(JSON.stringify({ type: subscribe, channel: updates }));

// 关闭连接
// ws.close();

完整配置示例

javascript
const ws = new WebSocketReconnect({
// 连接配置
url: wss://api.example.com/socket,
protocols: [graphql-ws],
websocketOptions: {
headers: {
Authorization: Bearer token123
}
},

// 重连配置
maxRetries: 10, // 最大重试次数
baseDelay: 1000, // 基础延迟 (毫秒)
maxDelay: 30000, // 最大延迟 (毫秒)
multiplier: 2, // 退避倍数
jitter: 0.1, // 抖动系数 (0-1)

// 心跳配置
heartbeatInterval: 30000, // 心跳间隔 (毫秒)
heartbeatTimeout: 5000, // 心跳超时 (毫秒)
heartbeatMessage: JSON.stringify({ type: ping }),

// 断路器配置
circuitBreaker: {
failureThreshold: 5, // 失败阈值
resetTimeout: 60000, // 重置超时 (毫秒)
halfOpenMaxRequests: 3 // 半开状态最大请求数
}
});

重连策略

指数退避计算

重连延迟按指数增长，避免频繁重试：

延迟 = baseDelay × (multiplier ^ 尝试次数)

示例 (baseDelay=1000ms, multiplier=2):

• - 第 1 次重试：1000ms (1 秒)
• 第 2 次重试：2000ms (2 秒)
• 第 3 次重试：4000ms (4 秒)
• 第 4 次重试：8000ms (8 秒)
• ...
• 达到 maxDelay 后不再增长

抖动 (Jitter)

添加随机抖动防止多个客户端同时重试：

javascript
// jitter = 0.1 时，延迟在 ±10% 范围内随机
实际延迟 = 计算延迟 × (0.9 ~ 1.1)

心跳检测机制

工作原理

1. 1. 连接成功后，每隔 heartbeatInterval 发送 ping 消息
2. 等待服务器在 heartbeatTimeout 内回复 pong
3. 如果超时，认为连接已僵死，自动关闭并触发重连

服务器端要求

服务器需要响应 ping 消息：

javascript
// 服务器示例 (Node.js + ws)
wss.on(connection, (ws) => {
ws.on(message, (data) => {
const message = JSON.parse(data);

if (message.type === ping) {
ws.send(JSON.stringify({ type: pong }));
}

// ... 处理其他消息
});
});

自定义心跳消息

如果服务器使用不同的心跳协议：

javascript
const ws = new WebSocketReconnect({
url: wss://api.example.com,
heartbeatInterval: 30000,
heartbeatMessage: PING, // 字符串
// 或者
heartbeatMessage: { cmd: heartbeat } // 对象 (会自动 JSON.stringify)
});

// 监听 pong 响应
ws.on(message, (event) => {
const data = JSON.parse(event.data);
if (data.type === pong) {
console.log(心跳正常);
}
});

断路器模式

三种状态

CLOSED (正常)

• - 请求正常通过
• 跟踪失败次数
• 失败达到阈值时打开

OPEN (熔断)

• - 请求立即失败，不尝试连接
• 防止对故障服务的过载
• 经过 resetTimeout 后自动转为 HALF-OPEN

HALF-OPEN (测试)

• - 允许有限数量的请求通过
• 成功则转为 CLOSED
• 失败则转回 OPEN

状态监控

javascript
ws.on(circuitChange, (state) => {
console.log(断路器状态: ${state});

if (state === OPEN) {
console.log(⚠️ 服务暂时不可用);
}
});

// 手动查询状态
const circuitState = ws.getCircuitState(); // CLOSED, OPEN, 或 HALF-OPEN

手动控制断路器

javascript
// 手动打开断路器
ws.openCircuit();

// 手动关闭断路器 (重置)
ws.closeCircuit();

事件参考

状态监控

获取统计信息

javascript
const stats = ws.getStats();
console.log(stats);
// {
// state: OPEN,
// circuitState: CLOSED,
// retryCount: 2,
// maxRetries: 10,
// circuitFailures: 0,
// failureThreshold: 5,
// lastActivity: 1709532000000,
// uptime: 15000
// }

连接状态

• - CLOSED: 未连接
• CONNECTING: 正在连接
• OPEN: 已连接
• CLOSING: 正在关闭
• BLOCKED: 被断路器阻止
• FAILED: 超过最大重试次数

完整示例

实时聊天客户端

javascript
const { WebSocketReconnect } = require(./scripts/websocket-reconnect.js);

class ChatClient {
constructor(userId) {
this.userId = userId;
this.ws = new WebSocketReconnect({
url: wss://chat.example.com/socket?user=${userId},
maxRetries: 10,
baseDelay: 1000,
maxDelay: 30000,
heartbeatInterval: 30000,
heartbeatTimeout: 5000,
circuitBreaker: {
failureThreshold: 5,
resetTimeout: 60000
}
});

this.setupEventHandlers();
}

setupEventHandlers() {
this.ws.on(open, () => {
console.log(✅ 已连接到聊天服务器);
// 发送上线通知
this.ws.send(JSON.stringify({
type: online,
userId: this.userId
}));
});

this.ws.on(message, (event) => {
const message = JSON.parse(event.data);
this.handleMessage(message);
});

this.ws.on(close, () => {
console.log(❌ 已断开聊天服务器连接);
});