WebSocket close code 的客户端重连分类

WebSocket 断开后要不要重连，不能只写成“onclose 里再 new 一个连接”。客户端至少要同时看关闭码、wasClean、是否由本地主动停止，以及当前认证是否仍然有效。一个实用的分类是：正常结束直接停止；网络短暂中断使用退避重连；协议、权限或数据格式错误先修复状态，不要循环撞击服务端。

本文只讨论浏览器客户端如何把 CloseEvent 映射为重连策略。reason 是服务端或子协议约定的文本，不能替代稳定的关闭码和本地状态。

读取关闭事件的三个信号

浏览器在 WebSocket 连接关闭时派发 CloseEvent。MDN 定义了三个最有用的只读属性：code 表示关闭码，reason 是原因文本，wasClean 表示关闭握手是否完整。它们回答的是不同问题：

• code：对端或浏览器给出了什么关闭类别；
• wasClean：这次连接有没有完成正常的关闭握手；
• 本地状态：是不是用户退出、页面销毁或认证已失效。

例如，1000 通常代表正常关闭，1001 表示一端离开或正在下线；1006 则是本地观察到没有收到 Close 帧的异常关闭，不能把它当成服务端主动发送的普通业务码。判断重连时，应该把关闭码当作分类输入，而不是把某个数字直接等同于“必须重连”。

建立三类重连策略

从客户端风险控制看，可以把关闭原因分成三类。第一类是“停止重连”：用户主动退出、1000 正常关闭，或明确的权限/协议错误。第二类是“退避重连”：1006 异常断开、临时网络错误、服务重启等可恢复情况。第三类是“先处理状态”：认证过期时刷新令牌，协议不兼容时升级客户端，消息过大或数据格式错误时修正发送逻辑。

用退避和认证状态控制重连

下面的分类器把策略返回为三个明确动作：stop、retry 和 refresh-auth。示例中的自定义码只是应用双方的约定，换成真实项目的协议值时要同步服务端文档。

// 只把可恢复的断开交给重连调度器，避免 onclose 无限递归建连。
function classifyClose(event, state) {
  // 用户主动停止、页面退出或组件卸载时，任何关闭码都不再重连。
  if (state.manualStop || state.pageLeaving) return { action: "stop" };

  // 认证失效先刷新凭据，不能用旧凭据反复撞击服务端。
  if (event.code === 4001 || event.code === 4003) {
    return { action: state.canRefreshToken ? "refresh-auth" : "stop" };
  }

  // 协议和数据类错误通常是代码或版本问题，默认停止并记录原因。
  const permanentCodes = new Set([1002, 1003, 1007, 1008, 1009]);
  if (permanentCodes.has(event.code)) return { action: "stop", reason: event.reason };

  // 正常结束不需要把已经完成的会话重新拉起。
  if (event.code === 1000) return { action: "stop" };

  // 1001、1006、1012、1013 等情况交给带退避的调度器处理。
  return { action: "retry", code: event.code, clean: event.wasClean };
}

function nextDelay(attempt, random = Math.random()) {
  // 指数退避限制上界，并加入抖动，避免大量客户端同时重连。
  const capped = Math.min(30_000, 1_000 * 2 ** Math.min(attempt, 5));
  return Math.round(capped * (0.8 + random * 0.4));
}

分类器只负责决定方向，真正的重连调度还要保证同一时刻只有一个连接尝试，并在成功打开后把次数归零。网络类断开可以限制最大尝试次数或使用更长的上限；如果服务端通过 1013 表示暂时无法服务，客户端尤其应该遵守退避，而不是立即并发创建多个连接。

处理认证刷新与人工停止

认证错误是最容易形成重连风暴的场景。建议把“刷新凭据”与“重新连接”拆成两个状态：刷新成功才允许重新连接，刷新失败则转为登录页或人工处理。不要把 reason 中的 “token expired” 当成唯一判断依据，因为原因文本由服务端和子协议决定，可能变化，也可能为空。

// 认证刷新只允许一个进行中的请求，避免多个 close 事件重复刷新。
let refreshPromise = null;

async function refreshOnce() {
  // 复用同一个 Promise，多个连接失败只触发一次刷新。
  if (!refreshPromise) {
    refreshPromise = refreshAccessToken().finally(() => {
      // 请求完成后释放锁，下次失效可以重新刷新。
      refreshPromise = null;
    });
  }
  return refreshPromise;
}

async function handleClose(event, state) {
  const decision = classifyClose(event, state);
  if (decision.action === "stop") return;
  if (decision.action === "refresh-auth") {
    // 刷新失败不再重试旧令牌，交给登录流程接管。
    await refreshOnce();
    return scheduleReconnect(0);
  }
  // retry 分支使用递增 attempt 和抖动延迟，避免重连同步发生。
  return scheduleReconnect(nextAttempt(), nextDelay(currentAttempt()));
}

本地的 manualStop 必须优先级最高。比如用户点击“退出账号”时，先设置停止标志，再调用 socket.close(1000, "logout")；否则 onclose 可能把一次明确的退出误判成网络故障。

常见误判与边界

• 把所有非 1000 都重连：1002、1007、1008 等错误往往说明客户端或权限状态需要修复，盲目重连只会放大请求。
• 把 wasClean 当成业务成功：握手干净只说明关闭过程完整，不代表业务消息已经保存或用户操作已经提交。
• 把 1006 当成服务端发送的码：RFC 6455 将它用于本地观察到未收到 Close 帧的异常关闭，它更像传输层线索。
• 自定义码没有协议文档：3000–3999 和 4000–4999 可以由应用使用，但具体含义必须由客户端、服务端共同约定。
• 没有退避和单实例锁：断网恢复或服务重启时，多个组件可能同时触发重连，应统一调度并加入抖动。

落地时可以先记录 code、wasClean、当前认证状态和重连次数，再按表格决定动作。这样既能保留异常线索，也能让“正常结束”和“可恢复断开”拥有不同的生命周期。

相关问题

WebSocket 的 1006 可以由客户端主动发送吗？

不能把 1006 当作普通应用关闭码发送。它表示本地没有收到 Close 帧时的异常关闭观察结果，客户端应在日志中记录它，并结合网络、页面生命周期和服务端状态排查。

reason 为空时还能决定是否重连吗？

可以。优先依据 code、wasClean 和本地状态；reason 只用于补充诊断，不应成为稳定分支条件。

为什么正常关闭后仍然出现重连？

通常是主动关闭标志设置得太晚，或多个组件各自拥有重连定时器。把停止状态提升到连接管理器，并在关闭前取消已有定时器即可避免这种竞态。