@ServerEndpoint路径必须带参数（如/client/{uid}）才能支持单聊，因Session.getId()随机且重连即变，需握手时通过URL路径传递uid并绑定到ConcurrentHashMap，否则只能群聊；须避免查询参数、注意URL编码、处理发送异常、集群下用Redis PUB/SUB同步。

为什么@ServerEndpoint路径带参数才支持单聊

因为WebSocket连接本身不携带业务身份，服务端靠Session维持长连接，但Session.getId()是随机字符串，每次重连都变，没法对应真实用户。必须让客户端在握手时就把uid塞进URL路径（比如/api/websocket/client/{uid}），服务端才能在@OnOpen里提取并绑定到内存Map中。

• 不带参数的@ServerEndpoint("/chat")只能做群聊，所有消息往一个广播池里扔
• 路径参数必须用@PathParam接收，不能靠查询参数（?uid=123）——WebSocket握手阶段Servlet容器不解析Query String
• 注意URL编码：如果uid含特殊字符（如@、/），客户端得encodeURIComponent()，服务端不用额外解码

webSocketClientMap存引用但没加锁，真没问题？

问题很大。Java WebSocket容器（如Tomcat）默认为每个连接分配独立线程处理@OnMessage，多个客户端同时发消息时，HashMap并发put可能引发死循环或数据丢失——这是典型的“内存可见性+线程安全”双坑。

• 必须换成ConcurrentHashMap，别信“只是存个引用不会出事”的直觉
• AtomicInteger计数在线人数是对的，但记得在@OnClose里decrementAndGet()，否则断网重连后人数虚高
• 更稳妥的做法是把ConcurrentHashMap声明为static且加@Component交由Spring管理生命周期，避免类加载器隔离导致Map不共享

广播消息时，session.getBasicRemote().sendText()抛IOException怎么处理

这是最常被忽略的“假稳定”：连接看似建着，其实网络已中断，但TCP层面还没触发RST，sendText()会卡住几秒后直接抛异常。不捕获会导致整个广播流程中断，其他正常用户收不到消息。

Java 接口排错助手

在调试 Java 后端 API 故障时使用此技能，尤其适用于以下任务：分析日志、跨 Controller、Service 和 Mapper 层追踪请求、定位异常根因、检查 SQL 执行或参数流转，以及生成简洁的诊断结论与修复方案。

下载

• 必须对每个session的发送做try-catch，捕获IOException和IllegalStateException（session已关闭）
• 捕获后立即从ConcurrentHashMap里remove()该uid，否则下次发消息还会失败
• 别用session.isOpen()提前判断——它返回true不代表能发成功，本质是伪防御

本地跑通了，上线就丢消息？检查Redis同步逻辑

单机版聊天室靠ConcurrentHashMap就能广播，但生产环境必集群。此时A用户连在服务器1，B用户连在服务器2，光靠各自Map无法互通——必须引入外部中间件做消息中转。

立即学习“Java免费学习笔记（深入）”；

• 选Redis的PUB/SUB而非Stream：延迟低，适合实时通知；但注意订阅关系需在应用启动时建立，别放在@OnOpen里（否则扩容时新节点收不到旧消息）
• 消息体建议只传uid和msgId，具体内容走数据库查——避免Redis消息体过大拖慢吞吐
• 别漏掉@PreDestroy里取消订阅，否则重启应用后Redis连接堆积，最终触发maxclients限制

实际最难的不是写通WebSocket，而是想清楚“谁在什么时候、以什么方式、把消息交给谁”。路径参数、线程安全、异常兜底、集群同步——这四步漏掉任何一环，线上就是静默故障。