quick-share/docs/03-WebSocket连接管理（连接-订阅-心跳-重连）.md

03 - WebSocket连接管理（连接 / 订阅 / 心跳 / 重连）

功能目标

• 建立浏览器到服务端的 WebSocket 连接（SockJS + STOMP）。
• 订阅房间广播通道，实时接收消息。
• 具备心跳保活与自动重连；UI 显示连接状态。

前端（Vue）

• 封装层：src/api/websocket.js
  • connect(url, onConnect, onError)：创建 STOMP Client，启用 reconnectDelay 与心跳参数。
  • subscribe(destination, callback)：按 destination 保存订阅，便于统一退订。
  • send(destination, body)：publish JSON 消息。
  • disconnect()：取消订阅并关闭连接。
• 连接时序（建议）
  1. connect 成功
  2. subscribe /topic/room/{roomCode}
  3. send /app/room/{roomCode}/join
  4. 开始收发消息
• 连接状态 UI
  • 显示：连接中 / 已连接 / 断开 / 重连中
  • 重连成功后：自动重新 subscribe + 重新 join

后端（Spring Boot）

• WebSocket 配置
  • 端点：/ws/data-transfer
  • broker：/topic
  • 应用前缀：/app
  • SockJS：.withSockJS()
• 跨域与握手
  • setAllowedOriginPatterns("*")（开发期）
  • 生产期建议：限制 Origin + 启用 WSS
• 心跳
  • 与前端 STOMP 心跳保持一致（如需更严格，改用外部 broker 或自定义心跳策略）

协议与通道

• 订阅（接收）
  • /topic/room/{roomCode}：房间内通用消息广播
  • /topic/room/{roomCode}/file/{fileId}：某文件分片通道（可选设计）
• 发送（服务端处理）
  • /app/room/{roomCode}/join
  • /app/room/{roomCode}/leave
  • /app/room/{roomCode}/message
  • /app/room/{roomCode}/file/chunk

边界与注意点

• 重连后的状态恢复：需要重新 join 才能恢复在线用户列表与系统消息一致性。
• 订阅泄漏：房间切换、页面卸载必须 disconnect/退订，避免重复订阅造成重复消息。
• 代理/反代：生产 Nginx 需支持 Upgrade，/ws 走 ws 反代。