【WebSocket】文本帧Text Frame

WebSocket 的文本帧Text Frame是 WebSocket 协议中用于传输文本消息的一种数据帧，通常用来传输 JSON 格式的聊天消息。

1. WebSocket 文本帧的底层格式

1.1 格式

前两个字节为基础帧头，后面可能有扩展长度、掩码密钥和消息数据。

字段	作用
FIN	是否为一条消息的最后一帧；消息可以分片
RSV1~3	保留位，通常为 0
Opcode	帧类型，`0x1` 表示文本帧，`0x2`二进制帧
MASK	是否使用掩码，客户端发往服务端必须为 1
Payload Length	消息长度，可能需要额外 2 或 8 字节表示
Masking Key	掩码密钥，客户端发送时使用
Payload Data	实际文本内容，以 UTF-8 编码

1.2 Payload Length 的三种情况

7 bit 长度字段	后续扩展字段	实际消息长度
0--125	无	0--125 字节
126	额外 16 bit	126--65,535 字节
127	额外 64 bit	65,536 字节及以上（最高位必须为 0）

2. 结合聊天项目理解

Netty + WebSocket 聊天项目中，客户端 A 向服务端发送的 JSON 消息格式为：

json 复制代码

{
  "version": 1,
  "requestId": "7f8b8aa7-6a17-42c5-a11f-27d2c0d04ab1",
  "type": "chat",
  "data": {
    "sessionId": 12345,
    "clientMessageId": "97330cc5-3267-493d-9458-082b57543bb9",
    "type": 0,
    "content": "你好"
  }
}

这段 JSON 就是 WebSocket 文本帧的 Payload Data，而不是整个 WebSocket 帧。

2.1 JSON 字段的作用

字段	含义
`version`	业务协议版本号，用于协议兼容
`requestId`	请求唯一标识，用于关联请求和响应，例如 ChatAck
`type: "chat"`	消息类型，表示发送聊天消息
`data.sessionId`	聊天会话 ID
`data.clientMessageId`	客户端消息唯一 ID，用于发送重试和幂等去重
`data.type: 0`	聊天内容类型，具体含义取决于项目约定
`data.content`	实际聊天内容，这里是"你好"

requestId 管请求，sessionId 管会话，clientMessageId 管消息。

2.2 Netty 如何解析这个消息？

Netty 的 WebSocket 解码器会处理底层帧头、掩码等协议细节，业务代码通常只需要处理消息内容。

java 复制代码

if (frame instanceof TextWebSocketFrame textFrame) {

    // 1. 获取 JSON 文本
    String json = textFrame.text();

    // 2. 解析外层业务协议
    JsonNode root = objectMapper.readTree(json);

    int version = root.get("version").asInt();
    String requestId = root.get("requestId").asText();
    String type = root.get("type").asText();

    // 3. 解析聊天业务数据
    if ("chat".equals(type)) {
        JsonNode data = root.get("data");

        long sessionId = data.get("sessionId").asLong();
        String clientMessageId =
            data.get("clientMessageId").asText();
        String content = data.get("content").asText();

        // 后续交给聊天业务逻辑处理
    }
}

实际项目中还需要进行字段校验、鉴权、幂等处理等。

3. 面试需要掌握的几个关键点

文本帧 Opcode = 0x1，二进制帧 Opcode = 0x2。
一个 WebSocket 消息可以拆分成多个帧；后续分片使用 Opcode = 0x0（Continuation Frame）。
客户端向服务端发送的帧必须加掩码，服务端向客户端发送的帧不能加掩码。
WebSocket 的帧格式负责网络传输，JSON 中的 type、sessionId 等是自己定义的业务协议字段。