GoodRoad 后端接口文档

接口概览

GoodRoad 分为四个主要阶段的接口调用：

认证与签名

签名校验（可选）

如果后端启用了 GOODROAD_CHANNEL_SECRET 环境变量，所有请求都需要包含签名头。

签名算法

signText = "{channelId}|{timestamp}|{nonce}"
signature = HMAC-SHA256(signText, secret).hex()

必需头部

• x-channel-id: 渠道号
• x-timestamp: 当前 Unix 时间戳（秒），允许偏差 ±300 秒
• x-nonce: 随机字符串，每个时间窗口内一次性使用
• x-signature: 上述签名结果

域名白名单（可选）

如果配置了 GOODROAD_CHANNEL_DOMAIN_MAP，请求时需要在 domain 字段里传当前页面域名，后端会校验是否在该 channel 的白名单内。

最佳实践

错误处理

• 始终检查响应中的 result 字段，非 0 表示出错。
• 对于 SESSION_INVALID 错误，前端应重新初始化流程（从 init-ticket 开始）。
• 对于网络错误，建议实现指数退避重试机制。

性能建议

• 缓存 session_token 直到过期，避免频繁的 exchange 调用。
• snapshot 列表通常可缓存 3-5 秒，再自动刷新。
• 对于高并发场景，使用 Redis 缓存会话和防重放 nonce。

安全建议

• 不要把 session_token 暴露在 URL query 里，优先使用 HTTP 请求头。
• 不要在浏览器控制台输出或记录完整的 token。
• 启用 GOODROAD_CHANNEL_SECRET 时，签名必须在后端完成，不要在前端暴露密钥。
• 定期轮换 channel secret，并通知接入方同步更新。

完整示例

JavaScript/TypeScript 联调示例

async function setupGoodRoadSession() {
  const apiBase = 'http://127.0.0.1:13100';
  
  // 1. 获取 init_ticket
  const initResp = await fetch(`${apiBase}/plugin/v1/init-ticket`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      channel_id: 'demo-channel',
      domain: window.location.origin,
      user_type: 'guest'
    })
  }).then(r => r.json());
  
  if (initResp.result !== 0) {
    throw new Error(`Init failed: ${initResp.code}`);
  }
  
  const initTicket = initResp.data.init_ticket;
  
  // 2. 交换 session_token
  const sessionResp = await fetch(`${apiBase}/plugin/v1/session/exchange`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ init_ticket: initTicket })
  }).then(r => r.json());
  
  if (sessionResp.result !== 0) {
    throw new Error(`Exchange failed: ${sessionResp.code}`);
  }
  
  const sessionToken = sessionResp.data.session_token;
  
  // 3. 获取桌台快照
  const snapshotResp = await fetch(
    `${apiBase}/plugin/v1/tables/snapshot?limit=8`,
    {
      headers: { 'x-session-token': sessionToken }
    }
  ).then(r => r.json());
  
  console.log('Tables:', snapshotResp.data.table_list);
  
  // 4. 进入游戏（需要会员 token）
  // const enterResp = await fetch(`${apiBase}/plugin/v1/game/enter`, {
  //   method: 'POST',
  //   headers: {
  //     'Content-Type': 'application/json',
  //     'x-session-token': sessionToken
  //   },
  //   body: JSON.stringify({ room_id: 1001 })
  // }).then(r => r.json());
}

setupGoodRoadSession().catch(console.error);