FastAPIWebSocket断线重连解决方案

对于一个文章开发者来说，牢固扎实的基础是十分重要的，golang学习网就来带大家一点点的掌握基础知识点。今天本篇文章带大家了解《FastAPI WebSocket 客户端断线重连实现方法》，主要介绍了，希望对大家的知识积累有所帮助，快点收藏起来吧，否则需要时就找不到了！

WebSocket断线后需在onclose中手动重连，采用指数退避策略（1s起，上限30s）并限制最大重试次数（如5次），同时发送前校验readyState并缓存未发消息；FastAPI后端无需特殊处理，但会话状态需依赖token和外部存储。

WebSocket 断线后 onclose 事件能捕获，但不会自动重连

FastAPI 本身不提供客户端逻辑，断线重连必须由前端 JavaScript 实现。浏览器原生 WebSocket 对象在关闭后不会自动重建连接，onclose 触发时连接已销毁，此时需手动调用 new WebSocket(...)。常见误区是只监听 onerror——它不保证触发（比如网络突然中断时可能直接跳到 onclose），所以重连逻辑应统一放在 onclose 中。

用 setTimeout 控制重连间隔，避免雪崩式重试

立即重连容易压垮服务端或触发限流；固定长间隔又影响体验。推荐指数退避策略：首次延迟 1s，失败后翻倍（2s → 4s → 8s），上限设为 30s。同时需限制最大重试次数（如 5 次），防止无限循环。

• 用闭包或类属性保存当前重试次数和延迟时间
• 每次重连前检查 ws.readyState === WebSocket.CLOSED || ws.readyState === WebSocket.CONNECTING，避免重复新建实例
• 重连前清除旧的 setTimeout 句柄，防止内存泄漏

let reconnectTimeout = null;
let retryCount = 0;
const MAX_RETRY = 5;
const BASE_DELAY = 1000;
function connect() {
const ws = new WebSocket("ws://localhost:8000/ws");
ws.onopen = () => {
retryCount = 0; // 成功则重置计数
};
ws.onclose = () => {
if (retryCount < MAX_RETRY) {
const delay = Math.min(BASE_DELAY * Math.pow(2, retryCount), 30000);
retryCount++;
reconnectTimeout = setTimeout(connect, delay);
}
};
ws.onerror = (err) => {
console.error("WS error:", err);
};
}

发送消息前必须校验 ws.readyState === WebSocket.OPEN

重连期间 ws 实例可能处于 CLOSED 或 CONNECTING 状态，此时调用 ws.send() 会抛出 InvalidStateError。不能依赖 onopen 后立刻发送——因为事件回调和业务代码执行有竞态。

• 封装一个 safeSend(ws, message) 函数，内部先判断状态，未就绪则缓存消息并监听 onopen
• 若重连成功，把缓存消息逐条发出（注意顺序）
• 避免在 onclose 里直接调用 send，此时连接已不可用

FastAPI 后端无需特殊处理，但要注意 websocket.close() 的调用时机

FastAPI 的 WebSocket 实例在客户端断开后会自动被清理，你不需要主动 close() 它。但如果在异常路径中手动调用了 websocket.close()（比如在 try/except 里），要确保只调用一次——重复 close 会报 RuntimeError: WebSocket is already closed。更安全的做法是用 try/except 包裹 send 操作，并忽略 WebSocketDisconnect 和 RuntimeError。

真正需要关注的是：客户端重连时，FastAPI 会为每个新连接创建独立的 WebSocket 实例，状态不共享。如果你需要维持用户级会话（比如登录态、房间 ID），得靠 token 鉴权 + 外部存储（Redis）同步状态，而不是依赖 WebSocket 对象本身。

终于介绍完啦！小伙伴们，这篇关于《FastAPIWebSocket断线重连解决方案》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！