简介一份基于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 轮询也不是 Netty2.1 从 HTTP 到 WebSocket一次握手双向通道HTTP 协议是“请求-响应”模型客户端不发请求服务端就不能主动推数据。聊天场景里如果每隔 2 秒轮询一次/getNewMessages在 1000 人在线时每秒会产生 500 个 HTTP 请求其中大部分都是空响应服务器 CPU 全耗在解析请求头和构建响应上。WebSocket 解决的是这个问题它通过 HTTP 协议完成一次握手然后升级为 TCP 长连接双方都可以随时发数据。握手过程是 101 状态码核心在请求头里GET /chat?userId1001 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 的WebSocketConfigurerTextWebSocketHandler依赖 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 ConcurrentHashMapString, 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收到新连接就放进静态MapOnMessage收到一条消息就遍历所有人广播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是原生 APIjQuery 并没有封装WebSocket。jQuery 能帮你做的只是 DOM 操作、事件绑定和$.ajax这种 HTTP 请求。而 WebSocket 的onopen、onmessage、onclose、send()都是原生方法这个包里的 JavaScript 代码写的其实是这些原生方法jQuery 只用来优化页面交互。所以不要去找“jQuery WebSocket 插件”没有这个东西。你真正要学的是原生WebSocket的四个回调和一个readyState状态。这比 jQuery 的$(document).ready重要得多。前端代码结构通常长这样// 连接 WebSocketURL 中的 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里判断文本内容单独回一个pongOnMessage 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前面提到用ConcurrentHashMapString, Session存在线用户这个 key 的选择直接影响业务。常见三种选择key 类型优点缺点适用场景用户名直观便于查某个用户同名用户会被覆盖单设备登录Session.getId()唯一不会冲突不知道是谁得额外维护用户映射匿名连接用户 ID 设备 ID支持多端代码复杂移动端Web端同时在线的场景大多数聊天室资源包用的是用户名。如果你要做多端登录建议用session.getId()做外层 key内部再维护MapString, SetString 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里查对方 sessionOnMessage 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 配置如果URIEncodingUTF-8没设置Tomcat 会按 ISO-8859-1 解码 URL 中的参数导致PathParam乱码。Tomcat 8.5 之后默认URIEncodingUTF-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.EntryString, 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 的发送不并发。更常见的是把同步发送换成异步并捕获SendResultsession.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% 的代码量但它们决定了一个聊天室能不能撑过真实使用。我见过太多资源包下载下来本地能聊得很欢一上服务器就翻车——原因几乎都出在没处理半开连接和代理超时上。希望这篇能帮你避开那些我已经踩过的坑让你拿到这类项目后不是只跑通演示而是真敢拿出去给别人用。本文还有配套的精品资源点击获取
简介一份基于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 轮询也不是 Netty2.1 从 HTTP 到 WebSocket一次握手双向通道HTTP 协议是“请求-响应”模型客户端不发请求服务端就不能主动推数据。聊天场景里如果每隔 2 秒轮询一次/getNewMessages在 1000 人在线时每秒会产生 500 个 HTTP 请求其中大部分都是空响应服务器 CPU 全耗在解析请求头和构建响应上。WebSocket 解决的是这个问题它通过 HTTP 协议完成一次握手然后升级为 TCP 长连接双方都可以随时发数据。握手过程是 101 状态码核心在请求头里GET /chat?userId1001 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 的WebSocketConfigurerTextWebSocketHandler依赖 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 ConcurrentHashMapString, 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收到新连接就放进静态MapOnMessage收到一条消息就遍历所有人广播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是原生 APIjQuery 并没有封装WebSocket。jQuery 能帮你做的只是 DOM 操作、事件绑定和$.ajax这种 HTTP 请求。而 WebSocket 的onopen、onmessage、onclose、send()都是原生方法这个包里的 JavaScript 代码写的其实是这些原生方法jQuery 只用来优化页面交互。所以不要去找“jQuery WebSocket 插件”没有这个东西。你真正要学的是原生WebSocket的四个回调和一个readyState状态。这比 jQuery 的$(document).ready重要得多。前端代码结构通常长这样// 连接 WebSocketURL 中的 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里判断文本内容单独回一个pongOnMessage 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前面提到用ConcurrentHashMapString, Session存在线用户这个 key 的选择直接影响业务。常见三种选择key 类型优点缺点适用场景用户名直观便于查某个用户同名用户会被覆盖单设备登录Session.getId()唯一不会冲突不知道是谁得额外维护用户映射匿名连接用户 ID 设备 ID支持多端代码复杂移动端Web端同时在线的场景大多数聊天室资源包用的是用户名。如果你要做多端登录建议用session.getId()做外层 key内部再维护MapString, SetString 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里查对方 sessionOnMessage 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 配置如果URIEncodingUTF-8没设置Tomcat 会按 ISO-8859-1 解码 URL 中的参数导致PathParam乱码。Tomcat 8.5 之后默认URIEncodingUTF-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.EntryString, 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 的发送不并发。更常见的是把同步发送换成异步并捕获SendResultsession.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% 的代码量但它们决定了一个聊天室能不能撑过真实使用。我见过太多资源包下载下来本地能聊得很欢一上服务器就翻车——原因几乎都出在没处理半开连接和代理超时上。希望这篇能帮你避开那些我已经踩过的坑让你拿到这类项目后不是只跑通演示而是真敢拿出去给别人用。本文还有配套的精品资源点击获取
方法)
