WebSocket 协议状态码：全面解析及应用建议

WebSocket 协议状态码用于标识连接关闭的原因或状态，帮助客户端和服务器理解连接终止的具体情况。这些状态码由 WebSocket 协议的关闭帧（Close Frame）携带，通常为 16 位无符号整数（0-65535）。以下是状态码的分类和常见代码的解析：

---

1. 标准状态码（0-999 和 1000-1015）

这些状态码由 IANA 注册，具有明确的语义，客户端和服务器应优先使用这些标准状态码。

1000 – 正常关闭

• 含义：连接正常关闭，表示连接目的已完成。
• 使用场景：客户端或服务器主动关闭连接时使用。

1001 – 端点离开

• 含义：连接的一端（如浏览器页面）正在离开，可能是用户关闭了页面或导航到了其他页面。
• 使用场景：浏览器环境下的页面关闭或刷新。

1002 – 协议错误

• 含义：连接的一端检测到协议错误，如数据帧格式不正确或使用了不支持的扩展。
• 使用场景：当收到的数据帧不符合 WebSocket 协议规范时。

1003 – 数据类型错误

• 含义：连接的一端收到无法处理的数据类型（如仅支持文本却收到了二进制数据）。
• 使用场景：数据类型不匹配时。

1005 – 无状态码

• 含义：保留状态码，表示没有设置关闭状态码。
• 使用场景：通常不会主动发送，仅用于接收端判断。

1006 – 异常关闭

• 含义：连接异常关闭，通常是因为连接中断或未发送关闭帧。
• 使用场景：网络中断、服务器崩溃等异常情况。

1007 – 数据格式错误

• 含义：收到的数据格式不符合预期（如文本消息中包含非 UTF-8 字符）。
• 使用场景：数据编码错误时。

1008 – 策略违规

• 含义：收到的消息违反了连接一端的策略（如消息大小超出限制）。
• 使用场景：安全策略或资源限制被触发时。

1009 – 消息过大

• 含义：收到的消息太大，无法处理。
• 使用场景：消息大小超出预设限制时。

1010 – 缺少扩展

• 含义：客户端期望服务器支持某些扩展，但服务器未协商这些扩展。
• 使用场景：WebSocket 扩展协商失败时。

1011 – 内部错误

• 含义：服务器遇到意外情况，无法完成请求。
• 使用场景：服务器内部错误或资源不足时。

1012 – 服务重启

• 含义：服务器正在重启。
• 使用场景：服务器维护或重启时。

1013 – 稍后再试

• 含义：服务器暂时过载，建议客户端稍后重试。
• 使用场景：服务器资源不足或负载过高时。

1014 – 网关错误

• 含义：网关或代理服务器出现问题。
• 使用场景：代理服务器或负载均衡器故障时。

1015 – TLS 握手失败

• 含义：WebSocket 连接无法完成 TLS 握手。
• 使用场景：SSL/TLS 配置错误或证书无效时。

---

2. 保留状态码（1016-2999）

这些状态码由 IANA 保留，供未来使用或扩展。目前未被标准化定义。

---

3. 私有状态码（3000-3999）

这些状态码可用于私有或自定义实现，但不建议在公共应用中使用，以避免冲突。

---

4. 自定义状态码（4000-4999）

这些状态码完全由应用程序定义，通常用于特定场景或业务逻辑。

---

5. 状态码的使用建议

• 优先使用标准状态码：确保兼容性和互操作性。
• 提供关闭原因：在关闭帧中附带状态码和可选的关闭原因（UTF-8 字符串），帮助对方理解关闭原因。
• 处理异常状态：特别是 1006 和 1011，需要实现重连机制或错误处理逻辑。

---

6. 示例

客户端发送关闭帧

const ws = new WebSocket('wss://example.com');
ws.onopen = () => {
  ws.close(1000, 'Normal closure'); // 正常关闭
};

服务器响应关闭帧

服务器收到关闭帧后，通常会返回相同的关闭状态码。例如：

• 客户端发送 1000，服务器响应 1000。
• 如果服务器检测到协议错误，可能发送 1002。

---

7. 常见问题

• 如何处理 1006？
  • 检查网络连接是否稳定。
  • 确保服务器正常运行。
  • 实现断线重连机制。
• 如何处理 1011？
  • 检查服务器日志，定位内部错误。
  • 优化服务器性能，避免资源耗尽。
• 如何避免 1003 和 1007？
  • 确保数据类型和格式符合协议规范。
  • 对输入数据进行验证和清理。

---

总结

WebSocket 状态码是连接管理的重要组成部分，通过标准化的状态码，客户端和服务器可以更清晰地沟通连接关闭的原因。在实际开发中，建议优先使用标准状态码，并实现健壮的错误处理和重连机制，以提高应用的稳定性和用户体验。