8. Error Handling (错误处理)

8.1 Handling Errors in UTF-8-Encoded Data (处理UTF-8编码的数据错误)

当接收到Text帧（Opcode 0x1）时，有效载荷数据必须是有效的UTF-8编码文本。

验证UTF-8

实现必须 (MUST) 验证接收到的文本数据是否为有效的UTF-8。

function isValidUTF8(buffer) {
  try {
    // Node.js会在无效UTF-8时抛出错误
    const str = buffer.toString('utf8');
    // 验证往返转换
    return Buffer.from(str, 'utf8').equals(buffer);
  } catch (e) {
    return false;
  }
}

ws.on('message', (data, isBinary) => {
  if (!isBinary && !isValidUTF8(data)) {
    // 关闭代码1007 = Invalid frame payload data
    ws.close(1007, 'Invalid UTF-8 in text frame');
  }
});

错误处理流程

当检测到无效UTF-8时：

1. 停止处理消息
2. 发送Close帧，状态码1007
3. 关闭连接

其他常见错误

协议违规

错误类型	关闭代码	处理方式
收到未掩码的客户端帧	1002	立即关闭连接
收到掩码的服务器帧	1002	立即关闭连接
无效的Opcode	1002	立即关闭连接
分片的控制帧	1002	立即关闭连接
控制帧超过125字节	1002	立即关闭连接
无效的UTF-8	1007	发送Close帧后关闭
消息过大	1009	发送Close帧后关闭

错误处理最佳实践

ws.on('error', (error) => {
  console.error('WebSocket错误:', error);
  // 记录错误
  // 通知监控系统
});

ws.on('close', (code, reason) => {
  if (code !== 1000 && code !== 1001) {
    console.error(`异常关闭: ${code} - ${reason}`);
    // 实施重连逻辑
    setTimeout(() => reconnect(), 5000);
  }
});

参考链接

• 上一章: 7. Closing the Connection
• 下一章: 9. Extensions