即时通讯功能在现在的业务系统里几乎成了标配，不管是客服工单、协同办公还是社交类产品，单聊都是最基础也最核心的一环。很多同学一听到"即时通讯"四个字，第一反应是去接第三方IM SDK，或者干脆上Netty自己撸一套协议栈。但如果你面对的场景只是后台管理系统里的消息通知、内部员工的一对一沟通，或者一个中小型Web应用里的私信功能，用Java原生的WebSocket配合Spring框架，其实就能把单聊这件事做得又稳又干净。我自己在好几个项目里都走过这条路，从最早的javax.websocket原生端点，到后来Spring的WebSocketHandler，再到STOMP协议那一套，踩过的坑不算少。这篇就把"Java使用WebSocket实现即时通讯单聊"这件事从头到尾拆开讲一遍，包括为什么这么选、连接怎么建、消息怎么路由、离线怎么办、心跳怎么保活，以及那些文档里不会写但实际一跑就出问题的地方。
1. 单聊场景下为什么优先考虑WebSocket而不是轮询
1.1 从HTTP轮询到长连接的演进逻辑
在WebSocket普及之前，做单聊最朴素的办法是Ajax轮询。客户端每隔两三秒发一次HTTP请求问服务器"有没有我的新消息"，服务器查库返回。这个方案能跑通，但问题很明显：假设一个用户在线一小时，按3秒一次轮询，就是1200次请求，其中绝大多数是空响应。连接建立、请求头传输、数据库查询这些开销全部白费，服务器连接数也被大量无效请求占着。
后来有了长轮询（Comet），客户端发一个请求，服务器hold住不返回，直到有新消息或者超时才响应。这比短轮询省了不少空请求，但本质上还是"一问一答"的HTTP模型，每次消息推送都要重新建立一次请求周期，服务端要维护大量挂起的请求线程，并发一上来线程池就顶不住。
WebSocket解决的就是这个根本矛盾。它在一次HTTP握手之后，把TCP连接升级成全双工通道，之后客户端和服务端可以随时互相推消息，不需要每次重新握手。对于单聊这种"消息随时可能来、且要求低延迟"的场景，WebSocket是天然契合的。我实测过一个简单的对比：同样1000个在线用户，轮询方案下服务器QPS峰值能到300多，而WebSocket方案下稳定在个位数，差距非常直观。
1.2 单聊与群聊在连接模型上的本质差异
很多人把单聊和群聊混在一起讲，其实两者的连接模型和消息路由逻辑差别不小。群聊的核心是"一个消息扇出给多个人"，服务端要维护群成员列表，做广播或者组播，消息去重和顺序保证是难点。而单聊的核心是"点对点"，一条消息只有一个确定的接收方，路由逻辑简单得多，但难点转移到了另外两个地方：一是如何精准定位接收方的连接，二是如何处理接收方不在线的情况。
单聊的连接模型可以理解为一张userId -> WebSocketSession的映射表。发送方发消息时，服务端从消息体里解析出接收方userId，去这张表里查对应的session，查到就推，查不到就说明对方不在线，走离线存储。这个模型听起来简单，但实际做的时候，session的生命周期管理、并发读写映射表、多实例部署下的session共享，都是要仔细处理的点。我见过不少项目单机跑得好好的，一上集群就出现"消息发出去对方收不到"，根子就在这张映射表没有做跨实例同步。
1.3 什么规模的系统适合自研WebSocket单聊
这里要给一个务实的判断标准，避免过度设计或者设计不足。如果你的系统同时在线用户在一万以内，单聊消息的峰值QPS在几百这个量级，且没有跨机房、跨地域的强要求，那么用Spring WebSocket自研一套单聊是完全够用的，成本低、可控性强、排查问题方便。
但如果你的在线规模到了十万级以上，或者需要消息必达、历史消息漫游、多端同步这些复杂能力，那自研的维护成本会急剧上升，这时候评估成熟的IM中间件或者云服务反而更划算。我个人的经验是：先想清楚业务到底需要哪些能力，别一上来就照着大厂架构抄，很多能力你的业务根本用不到，抄过来只是给自己增加运维负担。单聊这个功能，80%的场景用一套干净的WebSocket实现就能覆盖。
2. 搭建WebSocket单聊服务端的关键决策点
2.1 原生Endpoint与Spring STOMP的选型对比
Java里实现WebSocket服务端有两条主流路线。一条是用JSR-356标准的原生注解，@ServerEndpoint配合@OnOpen、@OnMessage、@OnClose这些生命周期回调；另一条是Spring生态的WebSocketHandler或者更高层的STOMP协议。
原生Endpoint的优点是轻量、直接，不依赖Spring的WebSocket抽象，你对连接和消息的控制粒度最细。缺点是它和Spring的依赖注入体系结合得不够自然，@ServerEndpoint标注的类默认不是Spring管理的Bean，想注入Service得用一些技巧，比如静态持有或者自定义ServerEndpointExporter的配置。
STOMP的优点是它定义了一套消息帧格式和订阅发布模型，天然支持"订阅某个目的地、往某个目的地发消息"这种语义，做单聊时可以用/user/{userId}/queue/messages这样的用户目的地，Spring会自动帮你路由到对应session，省去了自己维护映射表的麻烦。缺点是它引入了一层协议抽象，调试时看到的帧格式对新手不太友好，而且STOMP的一些默认行为（比如心跳、消息确认）需要额外配置才符合预期。
我的建议是：如果团队对Spring生态熟悉，且希望快速落地，选STOMP；如果追求极致的可控性和轻量，或者项目本身不是Spring Boot，选原生Endpoint。下面我以原生Endpoint为主线讲，因为它的原理最透明，理解了它再去看STOMP会轻松很多。
2.2 连接建立时如何绑定用户身份
WebSocket握手阶段是一个HTTP请求，这意味着你可以在握手时拿到请求头、Cookie、URL参数。绑定用户身份最稳妥的做法是在握手阶段完成鉴权，而不是等连接建立后再让客户端发一条"我是谁"的消息。
具体做法是实现一个ServerEndpointConfig.Configurator，重写modifyHandshake方法，在握手时从请求参数或者token里解析出userId，塞进ServerEndpointConfig.getUserProperties()里。这样在@OnOpen回调中就能通过session.getUserProperties()拿到userId，直接建立userId -> session的映射。
为什么不在@OnOpen之后让客户端发身份消息？因为那样存在一个时间窗口：连接已经建立但身份还没绑定，如果此时有消息要推给这个用户，服务端找不到映射，消息就丢了。而且客户端发身份消息这个动作本身也可能失败或者延迟，增加了不确定性。握手阶段鉴权是原子性的，连接建立即身份确定，逻辑最干净。
public class AuthConfigurator extends ServerEndpointConfig.Configurator { @Override public void modifyHandshake(ServerEndpointConfig config, HandshakeRequest request, HandshakeResponse response) { // 从URL参数或请求头解析token，校验后取出userId String token = extractToken(request); String userId = tokenService.verifyAndGetUserId(token); if (userId == null) { throw new RuntimeException("鉴权失败"); } config.getUserProperties().put("userId", userId); } }2.3 会话容器的数据结构选择与并发考量
userId -> WebSocketSession这张映射表是整个单聊服务的心脏。选什么数据结构，直接影响到并发安全和性能。
最直觉的是HashMap，但它不是线程安全的。WebSocket的连接建立和断开是并发的，多个用户同时上线或下线时，对HashMap的读写会出问题，轻则数据错乱，重则死循环（JDK8之前的HashMap并发扩容有环形链表问题）。所以必须用并发容器。
ConcurrentHashMap是首选。它的读操作几乎无锁，写操作分段加锁，非常适合"读多写少"的session映射场景——实际上单聊里查session（读）的频率远高于上下线（写）。我一般会定义一个ConcurrentHashMap<String, WebSocketSession>，key用userId，value用session。
但这里有个细节：一个用户可能多端登录，比如同时用PC和手机。如果key只用userId，后登录的会覆盖先登录的session，导致先登录的端收不到消息。要支持多端，value得改成ConcurrentHashMap<String, WebSocketSession>，外层key是userId，内层key是设备标识或者sessionId。这样推送时遍历内层map，给该用户所有在线端都发一份。是否要多端，取决于业务需求，但数据结构上提前留好扩展空间是明智的。
// 单端登录 private static final ConcurrentHashMap<String, WebSocketSession> SESSIONS = new ConcurrentHashMap<>(); // 多端登录 private static final ConcurrentHashMap<String, ConcurrentHashMap<String, WebSocketSession>> MULTI_SESSIONS = new ConcurrentHashMap<>();3. 消息收发链路的完整实现与路由细节
3.1 消息协议的设计：JSON字段怎么定
单聊的消息体建议用JSON，字段设计要提前想清楚，不然后期扩展很痛苦。一个够用的消息协议至少包含这几个字段：type（消息类型，比如单聊文本、心跳、已读回执）、fromUserId、toUserId、content、timestamp、msgId（客户端生成的消息唯一标识，用于去重和回执关联）。
msgId这个字段很多人会忽略，但它在实际中非常有用。客户端发消息时生成一个UUID，服务端原样带回给接收方，接收方收到后可以据此判断是否重复。同时发送方可以用msgId来关联服务端的ACK回执，确认消息是否送达。没有msgId的话，消息去重和状态追踪都无从谈起。
type字段决定了服务端如何处理这条消息。服务端收到消息后先解析type，如果是心跳就直接回一个心跳响应，不进入业务逻辑；如果是单聊消息就走路由；如果是已读回执就更新消息状态。用一个字段做分发，比用多个端点或者多个方法要清晰。
{ "type": "CHAT", "msgId": "c7f3a1e2-...", "fromUserId": "1001", "toUserId": "1002", "content": "在吗", "timestamp": 1710000000000 }3.2 服务端消息路由的核心逻辑
服务端收到一条单聊消息后，处理链路大致是：解析消息 -> 校验发送方身份（防止伪造fromUserId）-> 查找接收方session -> 在线则推送，离线则落库 -> 给发送方回ACK。
校验发送方身份这一步很关键。fromUserId不能信任客户端传来的值，必须用当前session绑定的userId覆盖它。否则恶意客户端可以伪造任意fromUserId，冒充别人发消息。这个安全漏洞在实际项目中我见过不止一次，都是因为图省事直接用了客户端传的fromUserId。
查找接收方session就是查前面那张映射表。查到后调用session.getBasicRemote().sendText(json)推送。这里要注意getBasicRemote()和getAsyncRemote()的区别：BasicRemote是阻塞的，AsyncRemote是非阻塞的。在高并发推送场景下，用BasicRemote如果某个客户端网络慢，会阻塞当前线程，拖累其他消息的推送。所以生产环境建议用getAsyncRemote()，它把发送操作交给容器管理的线程池，不会阻塞业务线程。
@OnMessage public void onMessage(String message, Session session) { Message msg = JSON.parseObject(message, Message.class); String realFromUserId = (String) session.getUserProperties().get("userId"); msg.setFromUserId(realFromUserId); // 覆盖，防伪造 if ("HEARTBEAT".equals(msg.getType())) { session.getAsyncRemote().sendText("{\"type\":\"PONG\"}"); return; } WebSocketSession target = SESSIONS.get(msg.getToUserId()); if (target != null && target.isOpen()) { target.getAsyncRemote().sendText(JSON.toJSONString(msg)); sendAck(session, msg.getMsgId(), "DELIVERED"); } else { offlineMessageService.save(msg); sendAck(session, msg.getMsgId(), "OFFLINE"); } }3.3 离线消息与上线拉取的配合
接收方不在线时，消息要落库。落库的字段除了消息本身，还要记录一个"是否已送达"的状态。等接收方下次上线时，在@OnOpen回调里查一次该用户的未送达消息，批量推给他，推送成功后把状态更新为已送达。
这里有个容易踩的坑：上线拉取和实时推送可能并发。比如用户A刚上线，正在拉取离线消息，同时用户B给他发了一条实时消息。如果处理不当，可能出现离线消息和实时消息顺序错乱，或者同一条消息被推两次。解决办法是给每个用户的上线拉取过程加一个短暂的锁或者标记，拉取期间到达的实时消息先缓存，拉取完成后再合并推送。或者更简单一点，用消息的timestamp和msgId在客户端做去重和排序，服务端保证不丢就行。
我倾向于客户端做去重排序，服务端只保证"至少送达一次"。因为服务端做严格顺序保证的成本很高，而客户端去重的成本很低。msgId在这里又派上了用场，客户端维护一个最近收到的msgId集合，重复的直接丢弃。
4. 连接保活、断线重连与异常处理
4.1 心跳机制为什么必须自己实现
WebSocket协议本身有ping/pong帧，理论上可以用来保活。但在实际浏览器环境里，前端JavaScript的WebSocket API并不暴露发送ping帧的能力，你没法从浏览器主动发ping。所以实际项目中，心跳都是应用层自己实现的：客户端定时（比如30秒）发一条{"type":"HEARTBEAT"}的文本消息，服务端收到后回PONG。如果服务端连续几个心跳周期没收到某客户端的心跳，就判定该连接已死，主动关闭并清理session。
为什么不能只依赖TCP的keepalive？因为TCP keepalive的默认时间太长了，通常是两小时，而且它探测的是TCP连接层面，中间如果有代理或者负载均衡设备，可能连接早就断了但TCP层还没感知到。应用层心跳能更快地发现死连接，及时清理资源。我一般把心跳间隔设为30秒，服务端容忍3个周期，也就是90秒没心跳就清理。
4.2 断线重连的客户端策略
网络抖动、页面切换、设备休眠都会导致WebSocket断开。客户端必须实现自动重连，否则用户会莫名其妙收不到消息。重连策略的核心是"退避"：第一次断开后等1秒重连，失败等2秒，再失败等4秒，指数增长但设一个上限比如30秒，避免在服务端故障时大量客户端同时疯狂重连把服务端打垮。
重连成功后，客户端要重新拉取断线期间漏掉的消息。这就需要一个"最后收到的消息时间戳"或者"最后收到的msgId"，重连时带上，服务端据此返回之后的消息。这个机制和离线消息拉取可以复用同一套逻辑。
还有一个细节：重连时要重新走鉴权。因为token可能已经过期，重连请求带上token，服务端校验失败就返回特定状态码，客户端收到后跳转登录页，而不是无限重连。
4.3 常见异常场景与排查思路
实际运行中会遇到几类典型异常。第一类是Session已关闭还在发送，抛IllegalStateException。这是因为发送前没检查session.isOpen()，或者检查了但检查之后到发送之间session被关闭了（并发问题）。解决办法是发送时用try-catch包住，捕获异常后清理session，不要让它影响其他消息的推送。
第二类是消息发送阻塞导致线程池耗尽。前面提到用AsyncRemote能缓解，但如果AsyncRemote的发送队列满了，也会有问题。Spring WebSocket可以配置发送缓冲区大小和超时时间，需要根据消息量调整。
第三类是集群环境下session不共享。单机部署时映射表在JVM内存里没问题，多实例部署时用户A连在实例1，用户B连在实例2，B给A发消息，B的请求落在实例2，实例2的映射表里没有A的session，就误判A离线。解决办法是引入Redis做session路由，每个实例把自己的session信息注册到Redis，推送时先查Redis定位目标用户在哪台实例，再通过内部消息通道转发过去。这块内容展开能写一整篇，这里先点出问题，知道有这个坑就行。
| 异常现象 | 可能原因 | 排查方向 |
|---|---|---|
| 消息发出对方收不到 | session映射丢失或跨实例 | 检查映射表、确认是否集群部署 |
| 连接频繁断开 | 心跳未配置或间隔过长 | 检查心跳逻辑、代理超时设置 |
| 服务端CPU飙升 | 同步发送阻塞或死循环重连 | 改用AsyncRemote、加重连退避 |
| 内存持续增长 | session未清理、离线消息堆积 | 检查onClose清理逻辑、离线消息过期策略 |
5. 从单机到集群：单聊服务的扩展性思考
5.1 集群部署下session共享的几种方案
单机跑通之后，业务量上来必然要集群部署，这时候session共享就成了绕不开的问题。主流方案有三种。
第一种是Redis发布订阅。每个实例订阅一个公共频道，推送消息时，如果目标用户不在本实例，就把消息发到Redis频道，所有实例都收到，各自检查目标用户是否在自己这里，是则推送。这个方案实现简单，但有个缺点：消息会广播给所有实例，实例多了之后网络开销大，而且每个实例都要处理大量与自己无关的消息。
第二种是Redis存储路由信息。每个实例启动时把自己的标识注册到Redis，用户连接时把userId -> 实例标识写入Redis。推送时先查Redis知道目标用户在哪个实例，然后通过实例间的内部通道（比如HTTP接口或者专门的消息队列）把消息转发到目标实例。这个方案精准，没有广播浪费，但多了一次Redis查询和一次实例间通信，延迟略高。
第三种是用专门的消息中间件，比如用MQ做实例间的消息转发。这个方案解耦最彻底，但引入了额外的运维组件。
我的经验是：实例数量在10个以内，用Redis发布订阅就够了，简单直接；超过10个，考虑路由方案。别一上来就上MQ，运维成本不低。
5.2 消息顺序性与幂等性的取舍
单聊里消息顺序重要吗？对于聊天场景，顺序错乱会让人困惑，比如"好的"出现在"帮我个忙"前面。但严格保证全局顺序的成本很高，尤其是在集群和离线消息混合的场景下。
务实的做法是保证"单会话内有序"。也就是同一个发送方发给同一个接收方的消息，按发送顺序到达。实现上可以给消息带一个递增的序列号，接收方按序列号排序。跨会话的顺序不保证，因为那本来也没有意义。
幂等性方面，前面说的msgId去重是基础。服务端在推送和落库时，可以用msgId做唯一约束，重复的消息直接忽略。这样即使因为重试导致消息重复投递，也不会产生重复记录。
5.3 监控指标与容量评估
上线之后要盯几个关键指标：当前在线连接数、消息推送成功率、平均推送延迟、离线消息积压量、心跳超时清理数。这些指标能帮你提前发现容量瓶颈。
容量评估上，单个WebSocket连接占用的内存很小，主要开销在连接对象本身和相关的缓冲区。一台4核8G的机器，用Tomcat跑WebSocket，支撑几千到一万个连接是比较稳的，具体数字取决于消息频率和消息大小。消息频率高、消息体大的话，连接数要相应下调。压测的时候重点测"大量连接同时在线且有一定消息频率"的场景，而不是只测连接数，因为消息处理才是真正的负载来源。
6. 几个实际落地时容易忽略的细节
6.1 跨域与代理配置的坑
开发环境前端和后端不同端口，WebSocket握手会被浏览器同源策略拦截。服务端要配置允许跨域，原生Endpoint可以在Configurator里设置，Spring的话用setAllowedOrigins。生产环境如果前面有Nginx，要配置WebSocket的升级头转发，也就是Upgrade和Connection这两个头，以及proxy_read_timeout要设得比心跳间隔长，否则Nginx会在空闲一段时间后主动断开连接，表现为"用户一段时间没操作就掉线"。
这个Nginx超时的坑我踩过，当时排查了很久，因为服务端日志显示连接是正常关闭的，看不出异常，最后才发现是Nginx的默认60秒超时把空闲连接断了。把proxy_read_timeout调到300秒，配合30秒心跳，问题就解决了。
6.2 消息体大小限制与分片
WebSocket单帧消息有大小限制，不同容器默认值不同，Tomcat默认是8KB左右。如果单聊要支持发图片、文件，不能直接把二进制塞进一帧里发，要么走分片，要么先把文件传到对象存储，消息里只传URL。后者更简单也更常用。如果确实要传大文本，记得调整容器的缓冲区配置，否则会抛MessageTooBigException。
6.3 优雅关闭与连接清理
服务重启时，如果直接kill进程，所有WebSocket连接会突然断开，客户端触发重连，可能瞬间给新实例造成压力。优雅的做法是关闭前先停止接受新连接，然后给现有连接发送一个"服务即将重启"的通知，让客户端主动断开并延迟重连。同时确保@OnClose回调里的清理逻辑被执行，把映射表里的session移除干净，避免内存泄漏。
@OnClose的清理逻辑一定要写健壮，用remove(key, value)这种带值校验的移除，而不是直接remove(key)。因为存在这种可能：用户A断开，清理时用户A已经用新连接重新上线了，映射表里是新session，如果直接remove(key)会把新session误删。用remove(key, oldSession)只有当value还是旧session时才删除，避免误伤。
@OnClose public void onClose(Session session) { String userId = (String) session.getUserProperties().get("userId"); if (userId != null) { // 只移除自己这个session，避免误删重连后的新session SESSIONS.remove(userId, session); } }这套单聊实现我在几个中小型项目里都用过，从最初的单机版到后来的Redis路由版，整体稳定性不错。核心体会是：WebSocket本身的API不复杂，复杂的是连接生命周期管理和异常边界处理。把session映射、心跳保活、离线补偿、优雅清理这四件事做扎实，单聊功能基本就不会出大问题。至于集群扩展，等真正有需求了再上，别提前给自己加戏。
