WebSocket聊天室实战：Java后端与心跳机制避坑指南

简介：一份基于JavaScript、jQuery与Java的WebSocket聊天室项目源码，面向Web前后端学习者或需要搭建实时通讯场景的开发者，完整实现了多人聊天、私聊与在线客服功能。项目采用标准Eclipse工程结构，压缩包共23个文件、约43KB，聚焦Java源码、XML配置、HTML页面及class文件等，并内置Tomcat v7.0服务器配置，便于直接导入工程运行调试。截至当前已有116人学习下载。示例重点展示了WebSocket基于TCP的Upgrade握手建连、双向数据帧收发流程，对比HTTP轮询说明了低延迟全双工通信原理；前端以jQuery简化DOM操作、事件绑定与Ajax交互，后端由Java处理会话维护、在线用户列表、消息广播和私聊定向，同时覆盖登录验证、并发连接、断开重连、隐私安全等关键设计。对于想快速掌握实时通信机制并提升综合开发能力的读者，是一份紧凑而实用的参考。

1. WebSocket聊天室：这套 Java + JavaScript 组合还能打，但坑比你想的多

如果你下载过一个叫WebSocket聊天室.zip的资源包，大概率会看到这样的目录：Java 后端写了WebSocketServer类，前端是index.html加 jQuery 的$.ajax和WebSocket调用，打包好能直接扔进 Tomcat 跑。这套组合解决的真实需求很简单：让浏览器和服务端建立一条持久连接，消息到了立刻推过去，而不是靠客户端每秒setInterval轮询把服务器打爆。适合谁？想做实时弹幕、客服系统、教学白板、或者毕业设计里“实时聊天”模块的人。它也确实能跑通，但很多人跑起来后才发现：连接不稳定、中文乱码、多人消息串台、部署上线后连不上——这些坑不是代码写错，而是对 WebSocket 的协议细节和 Java 后端生命周期理解不够。这篇就照着这套技术栈，把从握手到心跳、从广播到避坑的路径完整讲一遍。

2. WebSocket 协议与 Java 后端选型：为什么不是 HTTP 轮询，也不是 Netty？

2.1 从 HTTP 到 WebSocket：一次握手，双向通道

HTTP 协议是“请求-响应”模型，客户端不发请求，服务端就不能主动推数据。聊天场景里，如果每隔 2 秒轮询一次/getNewMessages，在 1000 人在线时，每秒会产生 500 个 HTTP 请求，其中大部分都是空响应，服务器 CPU 全耗在解析请求头和构建响应上。WebSocket 解决的是这个问题：它通过 HTTP 协议完成一次握手，然后升级为 TCP 长连接，双方都可以随时发数据。

握手过程是 101 状态码，核心在请求头里：

GET /chat?userId=1001 HTTP/1.1 Host: localhost:8080 Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Version: 13

服务端收到后，把Sec-WebSocket-Key加上固定 GUID258EAFA5-E914-47DA-95CA-C5AB0DC85B11做 SHA-1，再 Base64 编码，返回给客户端。这个过程浏览器原生 API 已经封装了，但你得知道为什么后端通常要拦一下Sec-WebSocket-Protocol或 token——因为握手本质是 HTTP，你可以在这里做身份校验，省掉后面所有帧里的鉴权逻辑。

2.2 Java 后端的两种做法：JSR-356 还是 Spring WebSocket？

常见的WebSocket聊天室.zip里，后端有两种写法。第一种是纯 Java EE/Jakarta 的 JSR-356 标准，用@ServerEndpoint("/chat")注解，不需要 Spring，一个javax.websocket包就能跑。第二种是 Spring Boot 的WebSocketConfigurer+TextWebSocketHandler，依赖 Spring 的WebSocketHandler生命周期管理。

我一般建议小项目用 JSR-356，原因有三个：一是依赖最少，Tomcat 自带实现，不需要额外引包；二是注解式端点直观，一个类就是一个聊天室入口；三是和前端new WebSocket("ws://...")的 URL 对应关系很直接。Spring 那套适合你已经在用 Spring Boot 做接口层、需要和 Controller 共享 Service 的场景，但它的拦截器、握手处理器和心跳检测配置比 JSR-356 绕一圈，新手容易被HandlerRegistration绕晕。

但这不代表 JSR-356 没有坑。@ServerEndpoint的类默认是单例还是多例？答案是每次连接创建一个实例。所以千万别把“在线用户列表”这种状态存在字段里——每个连接一个实例，字段互不相见。正确的做法是用静态ConcurrentHashMap或一个单独的SessionManager来共享状态。

2.3 用 Java 写最小可跑的服务端：注解端点与生命周期

下面用 JSR-356 写一个能收发文本消息的最小服务端。这里我用了jakarta.websocket包，Tomcat 10+ 用这个，Tomcat 9 及以下得把jakarta换成javax。

import jakarta.websocket.*; import jakarta.websocket.server.PathParam; import jakarta.websocket.server.ServerEndpoint; import java.io.IOException; import java.util.concurrent.ConcurrentHashMap; @ServerEndpoint("/chat/{username}") public class ChatServer { // 静态变量：所有连接实例共享这一份在线用户表 private static final ConcurrentHashMap<String, Session> onlineUsers = new ConcurrentHashMap<>(); @OnOpen public void onOpen(Session session, @PathParam("username") String username) throws IOException { onlineUsers.put(username, session); // 广播上线消息 for (Session s : onlineUsers.values()) { s.getBasicRemote().sendText("【系统】" + username + " 上线了，当前在线：" + onlineUsers.size()); } } @OnMessage public void onMessage(String message, Session session, @PathParam("username") String username) throws IOException { for (Session s : onlineUsers.values()) { if (s.isOpen()) { s.getBasicRemote().sendText(username + ": " + message); } } } @OnClose public void onClose(Session session, @PathParam("username") String username) throws IOException { onlineUsers.remove(username); for (Session s : onlineUsers.values()) { s.getBasicRemote().sendText("【系统】" + username + " 下线了，当前在线：" + onlineUsers.size()); } } @OnError public void onError(Session session, Throwable error) { // 这里别把堆栈打到前端，记日志即可 System.err.println("WebSocket error: " + error.getMessage()); } }

这段代码的逻辑很直白：@OnOpen收到新连接就放进静态Map；@OnMessage收到一条消息就遍历所有人广播；@OnClose移除并广播。但注意三个点：一是onlineUsers是静态的，这才能跨实例共享；二是sendText必须放在s.isOpen()判断里，否则对方关掉连接后遍历会抛IOException；三是@OnError不能屏蔽太死，否则连接异常时@OnClose不会被调用，Map 里会留下死连接。

跑起来很简单：把这个类放进 Web 项目，Tomcat 启动后，前端new WebSocket("ws://localhost:8080/你的项目名/chat/张三")就能连上。这就是整条链路的最小闭环。

3. 前端接入：原生 JavaScript API 与 jQuery 的取舍，以及心跳机制实现

3.1 用原生 JS 还是 jQuery？其实 WebSocket API 是同一个

聊到前端，很多人纠结“这个资源包是 JavaScript 还是 jQuery 的”。真相是：浏览器提供的WebSocket是原生 API，jQuery 并没有封装WebSocket。jQuery 能帮你做的只是 DOM 操作、事件绑定和$.ajax这种 HTTP 请求。而 WebSocket 的onopen、onmessage、onclose、send()都是原生方法，这个包里的 JavaScript 代码写的其实是这些原生方法，jQuery 只用来优化页面交互。

所以不要去找“jQuery WebSocket 插件”，没有这个东西。你真正要学的是原生WebSocket的四个回调和一个readyState状态。这比 jQuery 的$(document).ready重要得多。前端代码结构通常长这样：

// 连接 WebSocket，URL 中的 username 作为房间标识 const username = prompt("请输入昵称"); const ws = new WebSocket(`ws://${location.host}${location.pathname}chat/${username}`); // 连接打开后，把按钮置为可用 ws.onopen = function () { document.getElementById('status').textContent = '已连接'; sendBtn.disabled = false; }; // 收到服务端消息，用 jQuery 往消息列表追加一条 ws.onmessage = function (event) { const msg = event.data; $('#messageList').append($('<div>').text(msg)); // 滚动到底部 $('#messageList').scrollTop($('#messageList')[0].scrollHeight); }; // 发送消息 function sendMessage() { const input = $('#messageInput'); const content = input.val().trim(); if (!content) return; ws.send(content); input.val(''); } // 关闭后给用户一个提示 ws.onclose = function () { document.getElementById('status').textContent = '连接已断开'; sendBtn.disabled = true; };

逻辑说明：onmessage里的event.data是字符串；如果你传的 JSON，需要JSON.parse。jQuery在这里只用了$选择器和.append/.val，替代了原生document.querySelector的繁琐写法。send()只接受字符串或ArrayBuffer，别直接传对象，ws.send({type:"chat"})会静默失败——正确写法是ws.send(JSON.stringify({type:"chat"}))。

3.2 心跳机制：为什么浏览器连接会在 1 分钟后自动断开？

这是websocket 心跳机制实现搜索量最高的痛点。现象：前端连接后 1~2 分钟，onclose被触发，但服务端没关连接。原因多半是中间有代理（Nginx、公司防火墙、云平台的负载均衡）把空闲连接回收了。TCP 层没有活跃数据传输时，代理默认 60 秒左右断开。

解决方案是“心跳包”：客户端每隔 N 秒发一条ping文本（或者ws.ping()帧），服务端收到后回一条pong，连接就一直有流量，代理不会回收。很多人知道发 ping，但没注意两个细节：一是心跳包不能让业务层感知——发的内容要约定好，比如{"type":"ping"}，服务端收到后不回广播；二是要设置失败重连，不能只发心跳不管连接是否还活着。

下面是一段带心跳和重连的前端代码，常见做法是把它放进一个reconnect函数里：

let ws = null; let heartbeatTimer = null; const HEARTBEAT_INTERVAL = 30000; // 30秒发一次心跳 const RECONNECT_INTERVAL = 3000; // 断开后3秒重连 function connect() { ws = new WebSocket('ws://' + location.host + '/chat/' + username); ws.onopen = function () { console.log('连接成功'); startHeartbeat(); }; ws.onmessage = function (event) { const data = event.data; // 忽略心跳响应，不显示在聊天列表 if (data === 'pong') return; // 业务消息处理... }; ws.onclose = function () { stopHeartbeat(); // 断线后自动重连 setTimeout(connect, RECONNECT_INTERVAL); }; ws.onerror = function (err) { // 错误后通常会触发 onclose，这里只做日志 console.error('WebSocket error:', err); }; } function startHeartbeat() { stopHeartbeat(); // 每30秒发送一个ping文本帧 heartbeatTimer = setInterval(() => { if (ws && ws.readyState === WebSocket.OPEN) { ws.send('ping'); } }, HEARTBEAT_INTERVAL); } function stopHeartbeat() { if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; } } connect();

参数说明：HEARTBEAT_INTERVAL建议设为代理超时时间的一半。比如 Nginx 默认的proxy_read_timeout是 60 秒，你设 30 秒发一次就安全；如果代理超时设置成了 120 秒，你最好设 50 秒。RECONNECT_INTERVAL不能太短，否则服务端onClose还没处理完，你就重连了，容易把服务端 Session 表刷爆；设 3 秒是常见值，也可以做指数退避——第一次 1 秒，第二次 2 秒，最大 30 秒，避免服务端宕机时客户端疯狂重连。

3.3 服务端的心跳响应：别让心跳包进聊天记录

Java 服务端收到ping时，不能当作普通聊天消息广播，否则每个人都会看到“ping”。正确做法是在@OnMessage里判断文本内容，单独回一个pong：

@OnMessage public void onMessage(String message, Session session, @PathParam("username") String username) throws IOException { if ("ping".equals(message)) { // 心跳包，只回 pong，不广播 session.getBasicRemote().sendText("pong"); return; } // 业务消息广播... }

这里还有一个坑：有些实现用session.getAsyncRemote().sendText("pong")，异步方法不阻塞，但要注意并发。如果你同时发送多条消息，getBasicRemote()同步发送是线程安全的，getAsyncRemote()则需要你自己控制队列。小项目用getBasicRemote()就够，除非你在循环里发大量消息导致阻塞。

4. 从单机到多人聊天室：消息广播、Session 管理与在线列表

4.1 在线用户列表：Map 的 key 用用户 ID 还是会话 ID？

前面提到用ConcurrentHashMap<String, Session>存在线用户，这个 key 的选择直接影响业务。常见三种选择：

大多数聊天室资源包用的是用户名。如果你要做多端登录，建议用session.getId()做外层 key，内部再维护Map<String, Set<String>> userSessions，即一个用户对应多个会话。否则手机端一上线，Web 端就被顶掉了，而且旧 Session 可能还没关闭，广播时会向已经失效的连接发消息。

4.2 消息类型设计：把聊天、系统、上线、下线分开

前端拿到的消息不能都是裸字符串。聊天室里至少要区分chat（普通消息）、system（系统通知）、online（在线列表）三种类型。用 JSON 包裹是通行做法。服务端广播的消息结构长这样：

{ "type": "chat", "from": "张三", "content": "大家好", "timestamp": 1699876543210 }

对应的服务端发送逻辑：

private void broadcast(String type, String from, String content, Long timestamp) throws IOException { JsonObject msg = Json.createObjectBuilder() .add("type", type) .add("from", from == null ? "系统" : from) .add("content", content) .add("timestamp", timestamp == null ? System.currentTimeMillis() : timestamp) .build(); String json = msg.toString(); for (Session s : onlineUsers.values()) { if (s.isOpen()) { s.getBasicRemote().sendText(json); } } }

注意这里我把timestamp放到了服务端生成，不要用用户传的时间，原因很简单：客户端时间不可信，尤其是跨时区的用户。前端收到后判断type，是chat就追加到聊天区，是system就特殊样式显示，是online就刷新用户列表。

4.3 私聊实现：session 定位与离线消息的岔路口

私聊和广播的差别只在“发给谁”。按用户名私聊，代码就是在onlineUsers里查对方 session：

@OnMessage public void onMessage(String message, Session session, @PathParam("username") String username) throws IOException { // 假设前端消息格式: {"to":"李四","content":"你好"} JsonObject obj = Json.createReader(new StringReader(message)).readObject(); String to = obj.getString("to"); String content = obj.getString("content"); Session targetSession = onlineUsers.get(to); if (targetSession != null && targetSession.isOpen()) { targetSession.getBasicRemote().sendText( Json.createObjectBuilder() .add("type", "private") .add("from", username) .add("content", content) .build().toString() ); // 也给发送者回执，否则他不知道自己发送成功了 session.getBasicRemote().sendText("{\"type\":\"private_ack\",\"to\":\"" + to + "\"}"); } else { session.getBasicRemote().sendText("{\"type\":\"error\",\"content\":\"对方不在线\"}"); } }

这里要注意：如果对方在线但忙（比如浏览器被切后台，心跳还在，但onmessage可能不显示），消息还是会推过去的，只是前端 UI 没反应。所以私聊必须配合“消息记录”功能——服务端把消息落库，对方上线后去查离线消息。很多聊天室资源包为了省事不做落库，于是“对方不在线你就永远收不到这条消息”成了用户骂娘的点，这属于功能缺失而不是技术难点。

5. 避坑：WebSocket 聊天室最容易翻车的 5 个问题

5.1 连接频繁断开，浏览器控制台出现WebSocket is closed before the connection is established

现象：前端打开页面，onclose立刻触发，有时候onopen都没执行。原因多半是握手阶段就失败了。一个是 URL 路径不对：你后端@ServerEndpoint("/chat/{username}")，部署在demo工程下，那么前端必须连ws://localhost:8080/demo/chat/张三，少了工程名就 404。另一个是握手时带了自定义 Header，原生WebSocket无法设置 Header，只能靠 URL 参数传 token，所以不要尝试ws.onopen前给headers赋值。

解决：先浏览器地址栏访问http://localhost:8080/demo/chat/张三，看是不是 404；再用wscat或测试工具直接连，确认服务端根路径。前端写成动态获取路径：

const wsProtocol = window.location.protocol === 'https:' ? 'wss://' : 'ws://'; const wsUrl = wsProtocol + window.location.host + '/demo/chat/' + encodeURIComponent(username);

encodeURIComponent是必须的，用户名里有中文或空格时，直接拼在 URL 里会被 Tomcat 解析失败。

5.2 中文消息乱码，变成???或一堆问号

现象：英文消息正常，中文发过去显示问号。原因基本是握手响应声明的编码和连接不一致。WebSocket 文本帧默认使用 UTF-8，但 Tomcat 早期版本对request.setCharacterEncoding处理不彻底，尤其是 Tomcat 8 之前的版本。另外，前端prompt输入的用户名如果是中文，URL 没有 encode，服务端@PathParam拿到的是乱码。

解决：一是前端用户名必须encodeURIComponent；二是服务端在@OnMessage方法里不要额外处理编码，只认 UTF-8 字符串；三是检查服务端的 Connector 配置，如果URIEncoding="UTF-8"没设置，Tomcat 会按 ISO-8859-1 解码 URL 中的参数，导致@PathParam乱码。Tomcat 8.5 之后默认URIEncoding="UTF-8"，老版本要手动加。

5.3 Nginx 代理后总是连接失败，报 400/502

现象：本地直连 normal，压测或上线后经过 Nginx 就不行。原因：WebSocket 升级依赖Upgrade和Connection头，Nginx 配置默认只转发 HTTP 头，没有开启 WebSocket 支持。另外代理超时设置不当，也会导致空闲连接被切断。

解决：Nginx 的location配置里必须显式设置：

location /demo/chat { proxy_pass http://backend_server; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 3600s; proxy_send_timeout 3600s; }

注意proxy_pass后面不要带 URI。如果你写成proxy_pass http://backend_server/;，Nginx 拼接路径时很可能丢掉 WebSocket 的升级路径，导致连接挂掉。proxy_read_timeout和proxy_send_timeout设置成 1 小时，避免空闲心跳不及时时代理先断。

5.4 服务端内存飙升，在线用户数不准

现象：服务跑一天后，onlineUsers.size()越来越大，但实际在线用户远没那么多。原因：客户端非正常断开（断网、浏览器直接关掉）时，@OnClose不一定立刻触发。TCP 连接还处在半开状态，服务端不知道客户端消失。这也是心跳机制要落地的原因——服务端也要定期检查，而不是只靠客户端发心跳。

解决：服务端加一个定时任务，扫描onlineUsers里的 Session，看它是否满足超时条件：

// 每秒检查一次 ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor(); scheduler.scheduleAtFixedRate(() -> { long now = System.currentTimeMillis(); for (Map.Entry<String, Session> entry : onlineUsers.entrySet()) { Session s = entry.getValue(); long lastActive = (long) s.getUserProperties().getOrDefault("lastActive", now); if (now - lastActive > 60000) { // 60秒没有收过消息就断开 try { s.close(new CloseReason(CloseReason.CloseCodes.GOING_AWAY, "timeout")); } catch (IOException e) { // 忽略 } onlineUsers.remove(entry.getKey()); } } }, 10, 10, TimeUnit.SECONDS);

这块需要你在@OnMessage里更新lastActive，每次收到任何消息（包括心跳）就把当前时间戳放进去。这样如果客户端掉了，最多 60 秒后服务端会主动清理，不会让 Map 无限膨胀。

5.5 消息拥塞：发消息时偶发IOException: Broken pipe

现象：消息量大时，后端sendText抛异常，连接退出。原因：getBasicRemote()是阻塞式发送，如果对方 TCP 接收窗口满了，sendText会阻塞，阻塞时间过长会引发连接重置。高并发下应该用getAsyncRemote()，配合发送队列。

解决：简单场景用ConcurrentHashMap保证每个 Session 的发送不并发。更常见的是把同步发送换成异步，并捕获SendResult：

session.getAsyncRemote().sendText(json, result -> { if (result.getException() != null) { // 发送失败，可能是对方已断开，记录并清理 onClose(session, null); } });

6. 进阶：让聊天室从“能跑”变成“能上线”——消息确认、离线缓存与压力验证

6.1 消息确认与重发：JSON 里加一个msgId

聊天室最容易被投诉的是“我发的消息丢了”。TCP 保证不丢包，但 WebSocket 应用层不保证消息处理成功。常见做法是：前端生成一个唯一的msgId，服务端收到后立即回ack确认消息；前端如果在一定时间内没收到ack，就自动重发。

在@OnMessage里，你收到消息先回一个确认：

// 消息体: {"msgId":"uuid-xxx","content":"你好","type":"chat"} @OnMessage public void onMessage(String message, Session session) throws IOException { JsonObject obj = Json.createReader(new StringReader(message)).readObject(); String msgId = obj.getString("msgId"); // 先回 ack，再广播 session.getBasicRemote().sendText("{\"type\":\"ack\",\"msgId\":\"" + msgId + "\"}"); broadcast("chat", username, obj.getString("content"), System.currentTimeMillis()); }

前端在sendMessage时带上msgId，用setTimeout等待 2 秒，没收到对应ack就重新发送同一条消息，重发次数限制 3 次。注意这个逻辑要和输入框 UI 配合：显示“发送中”状态，收到ack变成“已送达”，重发三次失败则显示“发送失败”。这样用户至少知道消息可能没到，而不是默默丢消息。这个机制听起来简单，但很多商业聊天系统都靠它保证可靠性。

6.2 离线消息：用 ConcurrentLinkedQueue 还是数据库？

如果聊天室只是纯在线娱乐，离线消息可以不实现。但要作为客服或协作工具，离线消息是刚需。最简单可靠的方式是先把消息写入 MySQL（或抛到 Redis 里），用户上线时查未读。在@OnOpen里，查离线表发给对方即可。

这里给一条 SQL 思路，不贴完整建表：

CREATE TABLE offline_message ( id INT AUTO_INCREMENT PRIMARY KEY, to_user VARCHAR(64) NOT NULL, from_user VARCHAR(64) NOT NULL, content TEXT NOT NULL, create_time BIGINT NOT NULL, is_read TINYINT DEFAULT 0 );

服务端在@OnMessage里，如果私聊目标不在线，就插入这张表；在@OnOpen里，查询to_user = 当前用户名 AND is_read = 0，直接通过 session 推过去，然后更新is_read = 1。这个方案不需要引入消息中间件，单机几百人在线下足够。缺点是数据库压力随消息量增长，后期需要把ChatMessage和OfflineMessage分开，并且给to_user加索引。

6.3 压测验证：别用浏览器 F5 测试并发

最后一个落地的建议是：聊天室上线前，写一个模拟客户端脚本做压测，而不是自己开 10 个浏览器页面。用 Java 自带 API 写个简易客户端比你想的简单：

import java.net.URI; import java.net.http.HttpClient; import java.net.http.WebSocket; import java.util.concurrent.CompletionStage; public class WSChatClient { public static void main(String[] args) throws Exception { HttpClient client = HttpClient.newHttpClient(); WebSocket ws = client.newWebSocketBuilder() .buildAsync(URI.create("ws://localhost:8080/demo/chat/loadtest_" + args[0]), new Listener()) .join(); // 每秒发一条消息 for (int i = 0; i < 100; i++) { ws.sendText("{\"type\":\"chat\",\"content\":\"msg_" + i + "\"}", true); Thread.sleep(1000); } } static class Listener implements WebSocket.Listener { @Override public CompletionStage<?> onText(WebSocket webSocket, CharSequence data, boolean last) { System.out.println("收到: " + data); webSocket.request(1); return null; } } }

这个脚本的Listener必须调用webSocket.request(1)，它是在告诉 JDK 的 HttpClient 继续接收后续消息，不写这行，后边的消息会积压不回调。压测时你开 50 个线程各起一个客户端，观察服务端 CPU、内存和消息到达延迟。如果延迟超过 500ms，优先检查服务端是不是用了同步发送导致阻塞，然后看是不是心跳定时任务里有耗时操作。

做聊天室这个方向，我最深的体会是：把连接生命周期管好，比把消息动画做得华丽重要一百倍。心跳、断线重连、消息确认这几个机制，看起来占用了 30% 的代码量，但它们决定了一个聊天室能不能撑过真实使用。我见过太多资源包下载下来，本地能聊得很欢，一上服务器就翻车——原因几乎都出在没处理半开连接和代理超时上。希望这篇能帮你避开那些我已经踩过的坑，让你拿到这类项目后不是只跑通演示，而是真敢拿出去给别人用。

本文还有配套的精品资源，点击获取