请求协议 - AnySport

WebSocket 连接上流转的所有消息都是 JSON 文本帧，但根据发送方向和用途不同，分为三种结构：客户端发起的请求、服务端对请求的业务应答、以及服务端主动推送的连接级异常。搞清楚这三种结构的区别，能帮你在客户端写出干净的消息路由逻辑（按 type 或 code 字段分流处理）。

客户端请求（根字段）

所有客户端主动发送的消息（订阅、取消订阅、心跳）都遵循同一个根结构：

客户端请求示例

{
  "code": 20000,
  "trace": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {}
}

trace 字段的价值在于排查问题。如果某次订阅没有成功，你可以在日志里搜索对应的 trace 值，快速定位到服务端返回的具体应答，建议用 UUID 生成器为每次请求生成唯一值。

针对客户端发出的每条请求，服务端都会返回一条业务应答，用来告知这次操作是成功还是失败：

{
  "code": 20001,
  "trace": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "msg": "ok"
}

{
  "code": 40301,
  "trace": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "msg": "错误说明"
}

连接级异常是服务端主动推送的，不对应任何一次具体请求（比如心跳超时、触发限频），因此不带 trace 字段：

字段	必填	类型	说明
`type`	是	string	固定 `error`
`message`	是	string	错误原因，如心跳超时、限频

Websocket 连接级异常示例

{
  "type": "error",
  "message": "request frequency limit exceeded (60/min)"
}

客户端做消息分流时，可以先判断消息是否带 type 字段。带 type 的是连接级事件（connected/error）或业务推送（situation_update 等）；不带 type 但带 code 的，是对某次请求的业务应答。