WebSocket 系列—（3）WebSocket API 深入解析

最新推荐文章于 2026-07-05 09:10:29 发布

原创

最新推荐文章于 2026-07-05 09:10:29 发布 · 838 阅读

一、协议与交互模型概述

1. 基本概念

二、协议握手与核心机制

1. 握手阶段（HTTP Upgrade）

2. 数据帧结构

OPCODE 分类

三、浏览器 WebSocket API 详解

2. Java（Spring WebSocket）

3. Python（FastAPI）

五、IoT 场景扩展接口（ESP32 / 嵌入式）

ESP-IDF WebSocket 客户端

六、WebSocket 消息设计规范（API 层）

九、WebSocket 与 REST API 对比

十、扩展：API 调试与监控

十一、API 最佳实践总结

一、协议与交互模型概述

1. 基本概念

WebSocket 是一种建立在 TCP 之上的 全双工通信协议，允许客户端与服务器之间保持持续连接，实现实时数据交互。其生命周期包括：

HTTP 握手 → 协议升级 → 双向通信 → 心跳保活 → 关闭连接

二、协议握手与核心机制

1. 握手阶段（HTTP Upgrade）

客户端通过 HTTP 发起 Upgrade 请求：

GET /ws HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13

服务器响应：

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=

说明：

Sec-WebSocket-Key：客户端生成的 Base64 随机值。
Sec-WebSocket-Accept：服务端计算结果 Base64( SHA1( clientKey + GUID ) )。
握手成功后即进入二进制帧通信阶段。

2. 数据帧结构

每条消息以 Frame（数据帧） 传输，核心字段如下：

字段	位数	说明
FIN	1	是否为消息的最后一帧
RSV1-3	3	扩展用途（压缩、保留）
OPCODE	4	数据类型（1=text, 2=binary, 8=close, 9=ping, 10=pong）
MASK	1	客户端必须置1，用于掩码加密
Payload len	7/16/64	载荷长度
Masking-key	32	掩码密钥
Payload data	可变	实际消息数据

OPCODE 分类

OPCODE	类型	说明
0x1	文本帧	UTF-8 文本
0x2	二进制帧	设备或文件数据
0x8	关闭连接	Close
0x9	Ping	心跳请求
0xA	Pong	心跳应答

三、浏览器 WebSocket API 详解

浏览器原生支持 WebSocket 对象。

基础用法

const ws = new WebSocket("wss://example.com/ws");

//  连接建立
ws.onopen = () => {
  console.log("Connected");
  ws.send("Hello Server!");
};

//  接收消息
ws.onmessage = (event) => {
  console.log(event.data);
};

//  错误处理
ws.onerror = (err) => {
  console.error( err);
};

//  关闭连接
ws.onclose = () => {
  console.log("Connection closed");
};

API 属性与方法

属性/方法	类型	说明
url	String	连接地址（ws:// 或 wss://）
readyState	Number	连接状态（0:CONNECTING, 1:OPEN, 2:CLOSING, 3:CLOSED）
protocol	String	子协议（Sec-WebSocket-Protocol）
send(data)	Function	发送数据（字符串 / 二进制）
close(code?, reason?)	Function	关闭连接
onopen/onclose/onerror/onmessage	Function