WebSocket 消息类型（WsMessage）完整文档

概述

WsMessage 是 WebSocket 通信中使用的统一消息格式，支持四种消息类型：

Request (req): 客户端向服务端发送的请求
Response (rsp): 服务端对客户端请求的响应
Push (psh): 服务端主动推送的消息（广播）
Notification (ntf): 服务端发送的通知消息

所有消息都使用紧凑的 JSON 格式，字段名使用单字母缩写以减小消息体积。消息类型通过 C (Category) 字段区分。

字段说明

字段	全称	说明	类型
`C`	Category	消息类别：`"req"` / `"rsp"` / `"psh"` / `"ntf"`	string
`i`	ID	请求/响应 ID，用于匹配请求和响应	string \| number
`M`	Method	请求方法名	string
`P`	Params	请求参数（可选，为 `null` 时不序列化）	object \| null
`c`	Code	响应状态码（0：成功，非0：错误）	number
`m`	Message	响应消息或错误信息（可选，为 `null` 时不序列化）	string \| null
`d`	Data	响应数据（可选，为 `null` 时不序列化）	object \| null
`t`	Type	推送/通知类型	string
`p`	Payload	推送/通知数据	object

注意事项

ID 匹配: 响应的 id 必须与对应请求的 id 相同，用于匹配请求和响应。
可选字段: params、msg、data 字段如果为 null 或不存在，则不会出现在 JSON 中。
状态码: 响应状态码 0 表示成功，非 0 表示错误。
字段缩写: 所有字段名都使用单字母缩写以减小消息体积。
序列化规则:
- 请求方法序列化为字符串（如 "cri"）
- 响应和通知的 payload 根据字段自动识别类型
错误处理: 如果客户端发送未知的请求方法，服务端会返回错误响应，状态码为非 0，并在 m 字段中包含错误信息。

1. Request (客户端请求)

类型说明

客户端通过此消息类型向服务端发送请求。服务端会返回对应的 Response 消息。

JSON 格式：

{
  "C": "req",              // Category: 消息类别，固定为 "req" 表示请求消息
  "i": "request_id",       // ID: 请求唯一标识符，可以是字符串或数字，用于匹配响应
  "M": "method_name",      // Method: 请求方法名，如 "cri" 表示 GetCurrentRoundId
  "P": { ... }             // Params: 可选的请求参数，如果为 null 则不会出现在 JSON 中
}

2. Response (服务端响应)

类型说明

服务端对客户端 Request 的响应。响应中的 id 必须与对应请求的 id 相同。

JSON 格式：

{
  "C": "rsp",              // Category: 消息类别，固定为 "rsp" 表示响应消息
  "i": "request_id",       // ID: 对应的请求 ID，必须与请求的 ID 相同
  "c": 0,                  // Code: 响应状态码，0 表示成功，非 0 表示错误
  "m": "message",          // Message: 可选的错误消息，通常用于错误响应，为 null 时不出现
  "d": { ... }             // Data: 可选的响应数据，通常用于成功响应，为 null 时不出现
}

3. Push (服务端推送)

类型说明

服务端主动向所有连接的客户端推送的消息（广播）。

JSON 格式：

{
  "C": "psh",              // Category: 消息类别，固定为 "psh" 表示推送消息
  "t": "push_type",        // Type: 推送事件类型
  "p": { ... }             // Payload: 推送数据 payload
}

4. Notification (服务端通知)

类型说明

服务端向客户端发送的通知消息，用于推送重要事件，如轮次更新等。

JSON 格式：

{
  "C": "ntf",              // Category: 消息类别，固定为 "ntf" 表示通知消息
  "t": "notification_type", // Type: 通知类型，如 "ru" 表示 RoundUpdate
  "p": { ... }             // Payload: 通知数据 payload
}

已定义的类型

Request

方法	标识	参数	响应 Payload
GetCurrentRoundId	`"cri"`	无	`{"i": round_id}`

GetCurrentRoundId

方法标识: "cri"

说明: 请求获取当前正在进行的游戏轮次 ID。

请求格式:

{
  "C": "req",              // Category: 消息类别，固定为 "req"
  "i": "req_001",          // ID: 请求 ID，客户端生成的唯一标识符
  "M": "cri"               // Method: 方法名，固定为 "cri"（GetCurrentRoundId）
}

响应格式（成功）:

{
  "C": "rsp",              // Category: 消息类别，固定为 "rsp"
  "i": "req_001",          // ID: 与请求的 ID 相同
  "c": 0,                  // Code: 状态码，0 表示成功
  "d": {                   // Data: 响应数据
    "i": 1001              // ID: 当前轮次的 ID（round_id）
  }
}

响应格式（错误）:

{
  "C": "rsp",              // Category: 消息类别，固定为 "rsp"
  "i": "req_001",          // ID: 与请求的 ID 相同
  "c": 1,                  // Code: 状态码，非 0 表示错误
  "m": "Error message"     // Message: 错误描述信息
}

Response 类型

Payload 类型	字段	说明
GetCurrentRoundId	`i` (round_id)	轮次 ID

Push 类型

推送类型	标识	说明
None	`"none"`	占位类型（暂未使用）

当前状态: 暂未实现具体的推送类型，仅包含占位符 None。

注意事项: 当前 WsPush 仅包含 None 作为占位类型，未来可以根据需要添加更多的推送类型。

Notification 类型

通知类型	标识	Payload 字段	说明
RoundUpdate	`"ru"`	`i` (round_id)	轮次更新通知

RoundUpdate (轮次更新)

通知标识: "ru"

说明: 当游戏轮次状态发生变化时，服务端会向所有连接的客户端发送此通知。

触发时机:

此通知在以下情况会被发送：

投注事件
轮次状态改变

通知格式:

{
  "C": "ntf",              // Category: 消息类别，固定为 "ntf" 表示通知消息
  "t": "ru",               // Type: 通知类型，固定为 "ru"（RoundUpdate）
  "p": {                   // Payload: 通知数据
    "i": 1001              // ID: 更新的轮次 ID（round_id），更新后的游戏轮次唯一标识符
  }
}