WebSocket客服系统核心是消息精准可靠投递，需手动维护userId→Session映射、处理离线队列、强制JSON序列化、实现心跳与typing状态同步、客户端上报已读回执、服务端校验token并解耦连接与登录态。
WebSocket 实现客服系统实时人工在线对话，核心不是“能不能连上”，而是“消息能不能精准、可靠、不丢、不乱序地送到指定人”。直接用 WebSocket 原生 API 做单聊，90% 的坑出在连接管理、用户标识绑定和消息路由逻辑上，而不是协议本身。
如何让客服和客户一对一通信，而不是群发广播
原生 WebSocket 服务端（如 Java 的 @ServerEndpoint 或 Node.js 的 ws 库）默认没有内置“用户 ID”概念。群聊靠遍历所有 Session 广播，单聊必须自己维护映射关系：
- 连接建立时，客户端必须把
userId（比如客户手机号或登录态 token 解析出的 ID）作为路径参数或首次send()的内容传给服务端，不能只靠session.getId()—— 这个 ID 每次刷新页面就变，无法关联真实用户 - 服务端要用线程安全的结构（如 Java 的
ConcurrentHashMap<String, Session>，Node.js 的Map）存userId → Session映射，键必须是业务唯一 ID，不是临时 session ID - 发消息时，不再遍历全部连接，而是查
sessionMap.get(receiverUserId)，拿到目标Session后调用session.getBasicRemote().sendText()（Java）或ws.send()（Node） - 务必加空值判断：如果
receiverUserId对应的Session不存在（对方已断线），这条消息就得进离线队列，不能静默丢弃
为什么 onmessage 收到的是乱码或解析失败的 JSON
常见错误是前端 ws.send() 发了对象但没序列化，或者后端没做类型判断就强转：
WebSocket 8.18.2
下载
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
- 前端必须显式
ws.send(JSON.stringify({type: 'msg', from: 'u123', to: 'c456', content: '你好'}))，不能直接ws.send({ ... }) - 后端收到
String后要先校验 JSON 格式（比如用ObjectMapper.readTree()或JSON.parse()try-catch），再取字段；否则一个错字就会导致整个连接被@OnError关闭 - 不要依赖
Content-Type头——WebSocket 帧里没有这个字段，text和binary帧由应用层约定，服务端必须按协议文档解析 payload - 调试时可在
@OnMessage方法开头加日志：System.out.println("Raw message: " + message);，确认收到的是纯文本而非二进制帧
连接频繁断开、重连失败，客服看不到“对方正在输入”状态
这不是 WebSocket 协议问题，而是心跳与状态同步没做实：
- 浏览器标签页切走、手机锁屏、网络抖动都会触发
ws.onclose，但服务端不会立刻感知；必须由客户端每 30 秒发一次ping心跳包（如ws.send('{"type":"ping"}')），服务端响应pong，超时未收则主动清理Session - “正在输入”状态本质是临时事件，不能靠长连接保活来维持；正确做法是客户开始打字时发一条
{type: 'typing', to: 'cs789', status: true}，客服端收到后启动本地倒计时（比如 5 秒无新 typing 包就隐藏提示），服务端不持久化该状态 - 不要在
@OnClose里直接删sessionMap条目——可能有竞态；应加锁或用computeIfPresent原子操作 - 移动端 WebView 或某些企业内网环境会强制关闭空闲连接，建议服务端设置
maxIdleTime（如 Tomcat 的maxIdleTime或 Netty 的IdleStateHandler）为 60 秒以上
消息已读回执为什么总是延迟或不准确
已读状态不是服务器“推”出来的，而是客户端“报”上来的，关键在触发时机：
- 客户打开聊天窗口、滚动到底部、聚焦输入框——这些都不是可靠的已读信号；真正可靠的只有“消息 DOM 节点渲染完成 + 用户视线停留超过 1 秒”（需 IntersectionObserver 配合 setTimeout）
- 客服端收到消息后，不能等用户点击“回复”才上报已读；应该在消息插入 DOM 后立即发
{type: 'read', msgId: 'm12345'}到服务端，服务端更新数据库is_read = true并广播给客户 - 如果客户离线，已读回执要缓存到消息表的
read_at字段，等客户重连后拉取未读消息时一并返回已读状态，避免“客户上线看到消息却没标记已读” - 别用
localStorage存已读状态——多标签页或客服换设备就不同步；状态必须落库，由服务端统一裁决
最易被忽略的一点：WebSocket 连接生命周期和用户登录态必须解耦。用户 token 过期后，WebSocket 不会自动断开，但后续鉴权失败的消息会被拒绝。你得在每次 @OnMessage 开头校验 token 有效性，过期就主动 session.close() 并返回错误码，前端监听 onclose 后跳转登录页——否则客服可能还在发消息，客户却早已掉线不知情。
