GraphQL 订阅 (WebSocket)

本页面说明如何连接到奖励系统 GraphQL API WebSocket 以获取实时更新

奖励系统 GraphQL API 提供一个单独的 WebSocket 订阅 (StatusUpdate)，用于实时推送以下通知：
  1. XP 和等级变更
  2. 虚拟货币余额更新
  3. 轮盘令牌授予和使用
  4. 挑战进度和完成
  5. 奖励发放
所有更新都是用户范围的，需要身份验证。

连接设置

端点

协议

WebSocket 使用 graphql-ws 协议（也称为 graphql-transport-ws）。这是现代的 GraphQL over WebSocket 协议，而非传统的 subscriptions-transport-ws 协议。
在建立连接时，客户端必须：
  1. 将 HTTP 连接升级为 WebSocket
  2. 发送带有身份验证参数的 connection_init 消息
  3. 等待 connection_ack 后再进行订阅

身份验证

身份验证在 WebSocket 握手过程中通过 connectionParams（在 connection_init 消息中发送）进行。
必需参数：
参数类型描述
connection_id
string
必需。 此连接的唯一标识符（如 UUID）。用于跟踪每个用户的多个连接。
Authorization
string
推荐。 JWT Bearer 令牌（如 Bearer eyJhbGci...）。
您必须提供 Authorization。带有 JWT 的 Authorization 头是首选方法。
JWT 令牌要求：
  1. 必须是用配置的密钥（RSA 或 HMAC）签名的有效 JWT
  2. 必须包含用户身份声明
  3. 会验证令牌过期时间

连接参数

订阅更新

连接并验证身份后，订阅 StatusUpdate 订阅：
GraphQL 订阅：
响应格式：
字段类型描述
Type
string
更新类型（见事件类型）
Timestamp
string
更新发生时的 ISO 8601 时间戳
UserID
int
此更新所属的用户 ID
Data
string
包含更新详情的 JSON 编码载荷

处理断开连接

WebSocket 连接可能因各种原因中断：
  1. 网络问题
  2. 服务器重启
  3. 令牌过期
  4. 空闲超时

推荐的重连策略

实施带抖动的指数退避：

连接状态管理

跟踪连接状态并处理状态转换：
  1. 连接中 - 初始连接尝试
  2. 已连接 - 收到 connection_ack
  3. 已订阅 - 订阅活跃，正在接收事件
  4. 已断开 - 连接丢失，应尝试重连
  5. 错误 - 身份验证失败或不可恢复的错误