SpringBoot+WebSocket轻量级聊天室：握手、Session管理与Nginx部署全拆解
简介：这是一款面向计算机相关专业在校学生、初学者及课程设计者的轻量级在线聊天室实战项目，基于SpringBoot与WebSocket构建，解决传统JSP+XML方案维护性差、技术栈陈旧等问题，适用于毕设、课设、作业演示及全栈技能进阶学习。资源包共115个文件，含21个核心Java后端类（涵盖WebSocket配置、消息处理与用户管理）、7个前端JS交互逻辑、4个CSS样式文件（含bootstrap.css、sweetalert.css等响应式与提示组件）、2个HTML页面（Thymeleaf模板）、2个配置文件（application.yml与properties）及1个初始化SQL脚本，整体仅1.59MB，结构清晰、去冗余、注解驱动，便于快速理解与二次开发。已有171人下载学习，项目源自高分毕设（答辩均分96分），所有代码经实测运行无误，并附完整README说明文档，提供从环境搭建、登录注册、实时消息推送到群聊/私聊的全流程实现细节与典型GIF操作演示，助力开发者掌握SpringBoot整合WebSocket的核心实践模式。 手头正好有一个小巧的 SpringBoot + WebSocket 在线聊天室项目，源码和说明文档都齐全。当初从零搭起来花了三天，跑通以后发现很多同学卡在同样的几个坑上：握手阶段怎么带用户认证、Session 管理为什么要用 Map、Nginx 代理 WebSocket 为什么会 502、连接莫名断开报 1006 怎么排查。这些点我全部踩过一遍，这篇就把整个项目的设计思路、核心代码、部署方案和排障记录完整拆给你，照着抄就能出一个轻量级聊天室。
1. 项目概述与整体设计方案
1.1 为什么选 SpringBoot 原生 WebSocket 而不是 Netty 或 STOMP
这个聊天室起名“轻量级”，本质上就是拒绝重框架。一开始我也纠结过要不要上 Netty，后来想到核心需求就是几十人规模的在线群聊，不需要百万级长连接，没必要引入 Netty 那种复杂的 Reactor 模型和 Pipeline 链。SpringBoot 内置的spring-boot-starter-websocket打包后不到 2MB，启动一个内嵌 Tomcat 就能跑，对毕设、个人项目、快速原型完全够用。
再看 STOMP 协议，它是基于 WebSocket 的消息子协议，Spring 也支持@MessageMapping那套注解开发，但要配置 Broker、目的地前缀、心跳间隔，还要理解订阅链路，学习成本和代码量反而比原生 API 高。对于“就是要把消息从一个浏览器推到另一个浏览器”这个场景，原生 WebSocket 的三板斧——握手拦截器、WebSocketHandler、WebSocketSession——直来直去，反而干净利落。
技术选型最终定下来是这样：SpringBoot 2.7 + 原生javax.websocket相关依赖 + 前端原生 WebSocket API，不用任何消息中间件，不用 Redis 做分布式，Session 直接存在 JVM 内存里。这套方案的上限大概能支撑单机几百个在线连接，再往上就该考虑集群和 Redis 了，但那是下一篇的故事。
1.2 需求拆解与功能清单
做项目前先列需求，我给自己定的是“纯聊天，不花哨”。最终落地的功能点如下：
- 用户输入昵称进入聊天室，后端分配一个颜色标识，不用账号密码登录
- 聊天室广播消息，所有在线用户实时收到
- 展示在线用户列表，有人进入或离开时系统自动广播提示
- 支持私聊功能，消息格式里带上目标用户 ID
- 前端页面用纯 HTML + JavaScript 实现，不引入 Vue / React 等框架
- 后端提供两个接口：一个用于用户进入聊天室时获取历史消息（可选），一个用于 WebSocket 连接握手时的参数校验
这个功能清单最核心的价值在于：它覆盖了 WebSocket 开发中 90% 的常见操作——连接建立、参数传递、Session 管理、消息广播、点对点发送、连接关闭清理。把这些跑通，你就能举一反三写出更复杂的即时通讯系统。
1.3 目录结构与工程搭建
工程结构按 SpringBoot 标准分包，ChatEndpoint是 WebSocket 入口，ChatSessionManager管 Session，Message是消息体，WebSocketConfig负责把 Endpoint 注册到 Spring 容器。前端只有一个chat.html，静态资源直接放resources/static下面。
chat-room/ ├── pom.xml └── src/main/ ├── java/com/example/chatrooom/ │ ├── ChatRoomApplication.java │ ├── config/WebSocketConfig.java │ ├── endpoint/ChatEndpoint.java │ ├── manager/ChatSessionManager.java │ ├── model/Message.java │ └── interceptor/AuthHandshakeInterceptor.java └── resources/ ├── application.yml └── static/chat.htmlpom.xml里依赖极简，就spring-boot-starter-web和spring-boot-starter-websocket两个核心依赖。这里有个重要提醒：SpringBoot 2.x 用javax.websocket包下的 API，SpringBoot 3.x 换了jakarta.websocket命名空间，包名不一样，代码几乎要逐行改。建议做这个项目直接用 SpringBoot 2.7.x，教程和踩坑资料都最全，避开学 SpringBoot 3 时的命名空间地狱。
2. 核心接口与关键原理解读
2.1 WebSocket 握手机制与 HTTP 的升级请求
WebSocket 能实现全双工通信，核心在于握手阶段通过 HTTP 协议完成“协议升级”。浏览器发一个带Upgrade: websocket头的 HTTP 请求，服务端处理完回101 Switching Protocols，后续双方就在这条 TCP 连接上自由收发帧（Frame）数据。
这个机制决定了 WebSocket 开发的第一个重点：握手阶段是携带用户信息的唯一机会。因为一旦连接建立，HTTP 的请求头就没了，服务端拿不到 Cookie 之外的任何信息。实际项目里常见的做法是让前端在连接 URL 上拼接参数，比如ws://localhost:8080/chat?username=测试用户，后端在握手时把这个参数读出来保存，后续整个连接生命周期都用它标识用户。
我在AuthHandshakeInterceptor里就是这么做用户认证的：
public class AuthHandshakeInterceptor implements HandshakeInterceptor { @Override public boolean beforeHandshake(ServerHttpRequest request, ServerHttpResponse response, WebSocketHandler wsHandler, Map<String, Object> attributes) { if (request instanceof ServletServerHttpRequest) { ServletServerHttpRequest servletRequest = (ServletServerHttpRequest) request; String username = servletRequest.getServletRequest().getParameter("username"); if (username == null || username.trim().isEmpty()) { return false; // 拒绝握手 } attributes.put("username", username); // 把用户信息放进会话属性 } return true; } @Override public void afterHandshake(ServerHttpRequest request, ServerHttpResponse response, WebSocketHandler wsHandler, Exception exception) { // 握手完成后的回调，一般不需要实现 } }attributes这个 Map 是关键，它是握手阶段和WebSocketSession之间的数据通道，握手时放进去的内容，在ChatEndpoint的afterConnectionEstablished里通过session.getAttributes()拿到。
2.2 SpringBoot 原生 WebSocket 的注册方式与配置类
SpringBoot 集成原生 WebSocket 有两种写法，一种是服务端实现@ServerEndpoint("/chat")注解并使用ServerEndpointExporter，另一种是继承TextWebSocketHandler并通过WebSocketConfigurer注册。我选了第二种，因为WebSocketConfigurer可以顺手注册拦截器和自定义WebSocketHandler，代码组织更优雅，调试时链路也清楚。
配置类WebSocketConfig的关键代码：
@Configuration @EnableWebSocket public class WebSocketConfig implements WebSocketConfigurer { @Override public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { registry.addHandler(chatEndpoint(), "/chat") .addInterceptors(authHandshakeInterceptor()) .setAllowedOrigins("*"); } @Bean public WebSocketHandler chatEndpoint() { return new ChatEndpoint(); } @Bean public HandshakeInterceptor authHandshakeInterceptor() { return new AuthHandshakeInterceptor(); } }setAllowedOrigins("*")是开发阶段的配置，允许任何来源的跨域连接，部署时建议改成具体域名。很多同学遇到“前端一直连接不上但后端也没报错”的问题，八成就是这里没放行跨域，浏览器控制台里会出现Origin is not allowed之类的提示。
2.3 WebSocket 的 Session 管理为什么不用 ConcurrentHashMap 就行
整个项目中最重要的类是ChatSessionManager。它是一个单例管理器，维护所有在线用户的连接会话。核心数据结构是两个ConcurrentHashMap：一个以 userId 为 key 存用户信息，一个以 userId 为 key 存WebSocketSession。
@Component public class ChatSessionManager { private final Map<String, WebSocketSession> sessionMap = new ConcurrentHashMap<>(); private final Map<String, String> usernameMap = new ConcurrentHashMap<>(); public void addSession(String userId, WebSocketSession session) { sessionMap.put(userId, session); } public void removeSession(String userId) { sessionMap.remove(userId); usernameMap.remove(userId); } public WebSocketSession getSession(String userId) { return sessionMap.get(userId); } public Collection<WebSocketSession> getAllSessions() { return sessionMap.values(); } public int getOnlineCount() { return sessionMap.size(); } }有人会问，为什么不用CopyOnWriteArraySet存所有 Session，然后遍历发送？因为私聊功能需要精准找到“某个用户”的 Session，用 Set 就得遍历，效率低且代码绕。以 userId 为 key 的 Map 是点对点通信的天然选择，取 Session 的时间复杂度是 O(1)。
这里有个极其容易踩的坑：WebSocketSession 不是线程安全的。如果两个线程同时对同一个 Session 调用sendMessage，可能出现消息交错甚至异常。我处理的方式是把发送操作包在synchronized代码块里，以每个 Session 的 ID 作为锁的粒度，避免全局锁影响性能。
public void sendMessageToUser(String userId, String message) throws IOException { WebSocketSession session = sessionMap.get(userId); if (session != null && session.isOpen()) { synchronized (session.getId().intern()) { session.sendMessage(new TextMessage(message)); } } }2.4 消息协议设计：用 JSON 的 type 字段区分消息类型
消息对象Message是前后端通信的唯一契约，设计得是否清晰直接决定聊天室能扩展出多少功能。我用一个统一的 JSON 结构，通过type字段区分不同场景：
{ "type": "chat", "fromUserId": "u001", "fromUsername": "小明", "toUserId": "u002", "content": "你好", "timestamp": 1690000000000 }type目前有四种取值：chat表示普通聊天消息，system表示系统通知（有人进入/离开），online表示在线用户列表更新，private表示私聊消息。后端解析时用ObjectMapper转成 JsonNode，再取出type字段做分发：
public void handleTextMessage(WebSocketSession session, TextMessage message) throws Exception { JsonNode node = objectMapper.readTree(message.getPayload()); String type = node.get("type").asText(); switch (type) { case "chat": broadcastChatMessage(node, session); break; case "private": sendPrivateMessage(node); break; default: // 忽略未知类型 break; } }消息协议的设计是很多教程容易忽略的地方，但恰恰是最值得花时间的部分。一个字段位没说清楚的错误协议，会让你在扩展功能时痛不欲生。参考成熟协议的做法，前期的 type 分派就能让代码结构保持整洁。
3. 完整实现：从后端到前端的全套代码
3.1 后端核心类：ChatEndpoint 的完整实现
ChatEndpoint是整个聊天室的心脏，它继承TextWebSocketHandler，重写连接建立、收到消息、连接断开三个生命周期方法。完整代码如下：
@Component public class ChatEndpoint extends TextWebSocketHandler { private final ObjectMapper objectMapper = new ObjectMapper(); private final ChatSessionManager sessionManager = new ChatSessionManager(); @Override public void afterConnectionEstablished(WebSocketSession session) throws Exception { // 从握手拦截器放入的 attributes 中拿用户信息 String username = (String) session.getAttributes().get("username"); String userId = UUID.randomUUID().toString().substring(0, 8); // 保存 Session 和用户信息 sessionManager.addSession(userId, session); // 给当前用户发送一条连接成功的消息，附带自己的 userId Map<String, Object> welcome = new HashMap<>(); welcome.put("type", "system"); welcome.put("content", "欢迎进入聊天室，你的ID是 " + userId); welcome.put("fromUsername", "系统"); welcome.put("myUserId", userId); session.sendMessage(new TextMessage(objectMapper.writeValueAsString(welcome))); // 广播系统消息：xxx 进入了聊天室 broadcastSystemMessage(username + " 进入了聊天室"); // 广播在线用户列表 broadcastOnlineUsers(); } @Override protected void handleTextMessage(WebSocketSession session, TextMessage message) throws Exception { JsonNode node = objectMapper.readTree(message.getPayload()); String type = node.get("type").asText(); String fromUserId = node.get("fromUserId").asText(); String fromUsername = node.get("fromUsername").asText(); switch (type) { case "chat": String content = node.get("content").asText(); // 构造广播消息 Map<String, Object> chatMsg = new HashMap<>(); chatMsg.put("type", "chat"); chatMsg.put("fromUserId", fromUserId); chatMsg.put("fromUsername", fromUsername); chatMsg.put("content", content); chatMsg.put("timestamp", System.currentTimeMillis()); broadcastMessage(objectMapper.writeValueAsString(chatMsg)); break; case "private": String toUserId = node.get("toUserId").asText(); String privateContent = node.get("content").asText(); Map<String, Object> privateMsg = new HashMap<>(); privateMsg.put("type", "private"); privateMsg.put("fromUserId", fromUserId); privateMsg.put("fromUsername", fromUsername); privateMsg.put("toUserId", toUserId); privateMsg.put("content", privateContent); privateMsg.put("timestamp", System.currentTimeMillis()); String msgJson = objectMapper.writeValueAsString(privateMsg); // 发送给接收方 sessionManager.sendMessageToUser(toUserId, msgJson); // 也发一份给发送方自己，用于回显 sessionManager.sendMessageToUser(fromUserId, msgJson); break; default: break; } } @Override public void afterConnectionClosed(WebSocketSession session, CloseStatus status) throws Exception { String username = (String) session.getAttributes().get("username"); // 找出对应的 userId 并移除 for (Map.Entry<String, WebSocketSession> entry : sessionManager.getAllSessionsWithId().entrySet()) { if (entry.getValue().equals(session)) { sessionManager.removeSession(entry.getKey()); break; } } broadcastSystemMessage(username + " 离开了聊天室"); broadcastOnlineUsers(); } private void broadcastSystemMessage(String content) throws Exception { Map<String, Object> sysMsg = new HashMap<>(); sysMsg.put("type", "system"); sysMsg.put("content", content); sysMsg.put("fromUsername", "系统"); sysMsg.put("timestamp", System.currentTimeMillis()); broadcastMessage(objectMapper.writeValueAsString(sysMsg)); } private void broadcastOnlineUsers() throws Exception { Map<String, Object> onlineMsg = new HashMap<>(); onlineMsg.put("type", "online"); onlineMsg.put("onlineCount", sessionManager.getOnlineCount()); onlineMsg.put("users", sessionManager.getAllUsernames()); broadcastMessage(objectMapper.writeValueAsString(onlineMsg)); } private void broadcastMessage(String messageJson) throws Exception { for (WebSocketSession s : sessionManager.getAllSessions()) { if (s.isOpen()) { synchronized (s.getId().intern()) { s.sendMessage(new TextMessage(messageJson)); } } } } }这个实现里藏着几个实用细节：UUID.randomUUID().toString().substring(0, 8)生成短 ID 方便展示；连接关闭时通过遍历 Session 找到对应的 userId，这是 Map 反向查找的常见处理；synchronized (s.getId().intern())把锁的粒度控制在会话级别，避免不同用户之间的发消息互相阻塞。
3.2 前端页面：一次完整的 WebSocket 生命周期演示
前端chat.html用原生 JS 实现，浏览器 WebSocket API 本身就自带onopen、onmessage、onclose、onerror四个回调，正好对应连接的生命周期。
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>轻量级在线聊天室</title> <style> /* 篇幅原因省略，完整样式在源码包里 */ body { font-family: 'Microsoft YaHei', sans-serif; margin: 0; padding: 20px; background: #f5f7fa; } .chat-container { max-width: 800px; margin: 0 auto; background: #fff; border-radius: 8px; box-shadow: 0 2px 12px rgba(0,0,0,0.1); } .header { padding: 20px; background: #4a90d9; color: #fff; border-radius: 8px 8px 0 0; } /* ... */ </style> </head> <body> <div class="chat-container"> <div class="header"> <h2>轻量级在线聊天室</h2> <div> <input id="username" placeholder="输入昵称" style="padding: 8px; width: 200px;"> <button id="connectBtn" style="padding: 8px 16px;">连接</button> <span id="onlineCount" style="margin-left: 20px;">在线人数: 0</span> </div> </div> <div id="messages" style="height: 400px; overflow-y: auto; padding: 20px;"></div> <div style="padding: 20px; border-top: 1px solid #eee; display: flex; gap: 10px;"> <input id="msgInput" placeholder="输入消息，@用户ID 可私聊" style="flex: 1; padding: 10px;" disabled> <button id="sendBtn" style="padding: 10px 20px;" disabled>发送</button> </div> </div> <script> let ws = null; let myUserId = null; const usernameInput = document.getElementById('username'); const connectBtn = document.getElementById('connectBtn'); const msgInput = document.getElementById('msgInput'); const sendBtn = document.getElementById('sendBtn'); const messagesDiv = document.getElementById('messages'); const onlineCountSpan = document.getElementById('onlineCount'); connectBtn.addEventListener('click', () => { const username = usernameInput.value.trim(); if (!username) { alert('请输入昵称'); return; } // 关键：把用户名拼在 WebSocket URL 上 ws = new WebSocket(`ws://${location.host}/chat?username=${encodeURIComponent(username)}`); bindEvents(); }); function bindEvents() { ws.onopen = () => { msgInput.disabled = false; sendBtn.disabled = false; }; ws.onmessage = (event) => { const data = JSON.parse(event.data); switch (data.type) { case 'system': if (data.myUserId) { myUserId = data.myUserId; } appendMessage(`【${data.fromUsername}】 ${data.content}`, 'system'); break; case 'chat': appendMessage(`【${data.fromUsername}】 ${data.content}`, 'normal'); break; case 'private': appendMessage(`【${data.fromUsername} 私聊你】 ${data.content}`, 'private'); break; case 'online': onlineCountSpan.textContent = `在线人数: ${data.onlineCount}`; break; } }; ws.onclose = () => { msgInput.disabled = true; sendBtn.disabled = true; }; ws.onerror = (error) => { console.error('WebSocket 错误', error); }; } sendBtn.addEventListener('click', sendMessage); msgInput.addEventListener('keypress', (e) => { if (e.key === 'Enter') sendMessage(); }); function sendMessage() { const content = msgInput.value.trim(); if (!content) return; // 解析 @用户ID 私聊指令 const privateMatch = content.match(/^@(\w+)\s+(.+)$/); let payload = {}; if (privateMatch) { payload = { type: 'private', fromUserId: myUserId, fromUsername: usernameInput.value.trim(), toUserId: privateMatch[1], content: privateMatch[2] }; } else { payload = { type: 'chat', fromUserId: myUserId, fromUsername: usernameInput.value.trim(), content: content }; } ws.send(JSON.stringify(payload)); msgInput.value = ''; } function appendMessage(text, type) { const div = document.createElement('div'); div.textContent = text; if (type === 'system') { div.style.color = '#888'; div.style.fontSize = '14px'; } else if (type === 'private') { div.style.color = '#e67e22'; } messagesDiv.appendChild(div); messagesDiv.scrollTop = messagesDiv.scrollHeight; } </script> </body> </html>前端代码有两个实用技巧值得注意。第一个是encodeURIComponent(username)，用户昵称里如果有中文、空格、特殊字符，不编码会导致 URL 不合法甚至连接失败，这个细节我在帮人调 bug 时经常发现他们漏掉。第二个是私聊指令的解析，/^@(\w+)\s+(.+)$/这个正则匹配@用户ID 消息内容的格式，简单但实用，用户不需要额外点击头像就能发起私聊。
3.3 代码演示：开两个浏览器窗口模拟多用户
启动 SpringBoot 项目后，浏览器访问http://localhost:8080/chat.html，开两个标签页，分别输入昵称“小明”和“小红”。
第一个标签页连接后，页面会显示“系统：欢迎进入聊天室，你的ID是 3f2a1b8c”。第二个标签页连接后，第一个标签页立刻会收到“小明 进入了聊天室”的系统消息，同时在线人数从 1 变成 2。
小明输入“大家好”，点击发送，两个页面都会显示“【小明】 大家好”。小明输入“@3f2a1b8c 小红你好”，小红页面出现“【小明 私聊你】 小红你好”，而小明的页面也会回显这条私聊消息。实时性基本是零延迟，因为 WebSocket 的消息从服务端推送到客户端，没有 HTTP 轮询那种 2-3 秒的延迟感。
4. 部署配置与 Nginx 代理 WebSocket 的完整指南
4.1 本地运行与 JAR 包配置
开发调试时直接mvn spring-boot:run即可。生产部署建议打成可执行 JAR：
mvn clean package -DskipTests nohup java -jar chat-room-0.0.1-SNAPSHOT.jar --server.port=8080 > chat.log 2>&1 &application.yml里我做了基础配置，内嵌 Tomcat 的 WebSocket 缓冲区调大了一些，防止传长消息时被断连：
server: port: 8080 spring: application: name: chat-room # 内嵌 Tomcat 对 WebSocket 的支持配置 server.tomcat.websocket: buffer-size: 8192这个buffer-size不是必须的，但如果你在传图片 Base64 或稍长文本时遇到莫名其妙的连接断开，可以优先检查这个值。
4.2 Nginx 代理 WebSocket 的配置模板
部署到服务器后，不能让用户直接访问 8080 端口，通常用 Nginx 做反向代理。WebSocket 和普通 HTTP 在 Nginx 配置上的核心区别在于：需要显式声明Upgrade和Connection头，否则 Nginx 不会把 101 切换协议的状态码正确转发给客户端。
完整的 Nginx 配置反向代理配置如下：
map $http_upgrade $connection_upgrade { default upgrade; '' close; } server { listen 80; server_name chat.example.com; # HTTP 接口代理，用于访问聊天室页面 location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } # WebSocket 代理 location /chat { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_set_header Host $host; proxy_read_timeout 60s; proxy_send_timeout 60s; } }map指令的作用是把请求头里的Upgrade值映射到Connection头。如果客户端发的是Upgrade: websocket，则转发Connection: Upgrade；如果是普通 HTTP 请求，没有 Upgrade 头，就设成close。这个处理能同时兼容 HTTP 和 WebSocket 走同一个 location。
proxy_read_timeout 60s是经常被忽略的一个参数。Nginx 默认的 read 超时是 60 秒，如果 WebSocket 连接在 60 秒内没有任何数据流动，Nginx 会主动切断连接，导致前端出现 1006 非正常关闭。要么把超时时间调大（比如3600s），要么让前端写心跳包定期 ping 服务端，我的项目里用了后者，30 秒发一次心跳，保证连接永远处于活跃状态。
4.3 前端连接地址的兼容写法
本地调试和线上部署的 WebSocket 连接地址是不一样的。本地是ws://localhost:8080/chat，线上是ws://chat.example.com/chat。如果前端代码直接写死地址，每次切换环境都要改代码，很蠢。
我推荐的做法是用location.host动态拼地址，同时支持 HTTPS 下的wss://：
const wsProtocol = location.protocol === 'https:' ? 'wss://' : 'ws://'; const ws = new WebSocket(`${wsProtocol}${location.host}/chat?username=${encodeURIComponent(username)}`);这样前端代码在本地、测试、生产环境通用，不用改一行代码。注意如果用wss://，Nginx 需要配 SSL 证书，同时proxy_set_header X-Forwarded-Proto $scheme;也可以加上，方便后端识别请求来源协议。
5. 常见问题与排查技巧实录
5.1 连接状态码 1006 与 1000 的区别
WebSocket 关闭状态码里，1000 是正常关闭，1006 是异常关闭。我遇到过最多的就是前端报WebSocket connection to 'ws://...' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED或者 1006。这个问题要按下面顺序排查：
第一，确认后端进程还在，端口有没有被占用。netstat -tlnp | grep 8080看端口监听状态。
第二，确认请求是不是到了后端。在ChatEndpoint的afterConnectionEstablished方法第一行打日志或断点。如果后端没反应，大概率是 Nginx 配置没有正确转发 Upgrade 头，按上面的模板检查。
第三，确认握手拦截器的返回值。beforeHandshake返回false时，服务端会拒绝连接，前端收到403或直接 1006。我当时就犯过这个错——校验用户名时不小心把参数名拼错，导致所有连接都被拦截。
第四，检查浏览器控制台。打开 F12，点击 Network，找到chat那条 WebSocket 请求，看 Status Code 是不是 101。如果显示 200 但连接失败，说明 Nginx 把 WebSocket 升级请求当成普通 HTTP 处理了。
5.2 “发送消息没有反应”与“消息丢失”的排查
消息发出去但别人看不到，这个问题的根源通常在三个地方。第一，前端ws.send()的 JSON 格式和后端解析字段对不上——比如前端发的是toUser，后端取的是toUserId，取出来就是 null。第二，后端广播时抛了异常，我踩过的一个具体坑是：objectMapper.writeValueAsString对含有特殊字符的消息（比如 emoji）偶尔出错，后来统一改用String.format或保证消息按 JSON 格式构造就好了。第三，Session 已经关闭但还在广播列表里。sessionMap里的过期 Session 没有清理干净，sendMessage时抛IOException，我当时没有对单连接异常做 try-catch，导致一个用户断线，广播循环中断，后面的人都收不到消息。
所以广播循环里的每一条发送都要包 try-catch，不要让单个连接的问题拖垮全局。这是我实战中印象最深的一次故障根因。
5.3 SpringBoot 版本太高引发的兼容问题
热搜词里出现了“springboot 版本太高”和“springboot 4 源码”，这两个说法其实指向同一类问题：SpringBoot 版本升级带来的 API 变动。如果你 Starter 用的是 SpringBoot 3.2 以上版本，javax.websocket依赖已经移除了，改成jakarta.websocket，代码里的import全部要改。更坑的是，SpringBoot 3 对WebSocketConfigurer的实现机制有调整，某些老教程里的写法直接编译不过。
我的建议非常明确：聊天室这种教学型项目，固定用 SpringBoot 2.7.x，Java 8 就够了。Java 17 用户用 SpringBoot 3.2.x 就得同步改造代码，但即便如此，也建议等到你完全理解了 WebSocket 底层原理后再迁移，否则报错时新旧 API 混在一起，排查难度会翻倍。
以下是我的核心依赖完整版：
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.7.18</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-websocket</artifactId> </dependency> </dependencies>5.4 断线重连机制：让前端自动恢复连接
网络波动、服务端重启、Nginx 超时，都会导致 WebSocket 连接断开。用户刷新页面能恢复，但体验很差。我在前端加了一个断线重连机制：当onclose触发时，如果用户之前成功连接过，则每隔 3 秒尝试重新连接一次。
let reconnectAttempts = 0; const maxReconnectAttempts = 10; ws.onclose = () => { msgInput.disabled = true; sendBtn.disabled = true; if (reconnectAttempts < maxReconnectAttempts) { setTimeout(() => { reconnectAttempts++; ws = new WebSocket(`ws://${location.host}/chat?username=${encodeURIComponent(usernameInput.value.trim())}`); bindEvents(); }, 3000); } };这个逻辑里要控制重连次数，否则服务端挂了之后前端会无限地发起无效连接。10 次重连后放弃，提示用户手动刷新，是比较稳妥的方案。
5.5 WebSocket 鉴权：别把 Token 放在 URL 里
我在做这个项目时同步整理了前后端安全对接的规范。很多人直接在 URL 里拼 Token：ws://localhost:8080/chat?token=xxx。问题在于 WebSocket URL 会出现在 Nginx 日志、浏览器历史、代理日志等位置，明文 Token 很容易泄露。
更安全的做法是在握手时用 Cookie 或 Authorization 头传递 Token。beforeHandshake方法里可以读请求头：
String token = servletRequest.getServletRequest().getHeader("Authorization");但浏览器原生 WebSocket API 不能自定义 Header，所以实际项目中大多用 Cookie 保存会话标识，后端从手请求中读取 Cookie 来鉴权。如果你只是玩票性质，URL 拼参也能凑合；但如果是公司项目或毕设答辩，建议把鉴权方式升级成 Cookie + Session 或 JWT 方案，这个点做好了能在答辩时加分。
6. 扩展方向与架构升级参考
6.1 点对点聊天、消息持久化与 Redis 集成
当前项目把所有消息都放在内存里，重启就丢。如果要做成能长期运行的产品，第一个要补的是消息持久化。最简单的做法是用 Spring Data JPA 把消息存进 MySQL，收到消息时先存库再广播。查询历史消息时可以提供一个 HTTP 接口，用户进入聊天室时加载最近 50 条，这样聊天室就有“记忆”了。
如果用户量上来想要横向扩展，单机内存的 Session Map 就不够了。常规做法是引入 Redis Pub/Sub 做消息广播，每个应用实例把消息发布到 Redis 频道，所有实例订阅同一频道并推送给各自负责的客户端。再进一步可以用 Redis 的 Hash 结构存储 Session 与用户的关系，这样即使某台机器宕机，也能根据在线状态把用户连接重新路由到其他实例。
6.2 在线状态与心跳机制的进阶设计
基础版聊天室用WebSocketSession.isOpen()判断连接是否存活，但 TCP 连接在极端网络场景下会出现“假死”——客户端已经断网，服务端却不知道，Session 还是 open 状态。标准解法是心跳机制：客户端每 30 秒发一个{"type": "ping"}，服务端收到后回一个{"type": "pong"}，如果服务端 90 秒没收到某个客户端的心跳，就主动关闭该连接并清理 Session。
实现心跳的代码在这个项目里也预留了位置，handleTextMessage的 switch 里加一个pingcase 即可。
6.3 用 Spring Security 做 WebSocket 授权
如果项目要接登录系统，Spring Security 对 WebSocket 有专门支持。核心思路是在握手前通过ChannelInterceptor拦截CONNECT命令，判断用户是否已认证。这个方案和原生 WebSocket 的HandshakeInterceptor不同，Spring Security 的拦截器走的是 STOMP 协议的CONNECT帧，因此需要在配置类里启用 STOMP 端点支持。如果你不想引入 STOMP，也可以直接在HandshakeInterceptor里检查 Spring Security 的SecurityContextHolder，判断当前用户是否已登录，逻辑更简单。
我在实际项目中用的是后者，对原生 WebSocket API 的侵入最小，前端不用改动就能无缝接入认证逻辑。核心代码就是在beforeHandshake里加一句SecurityContextHolder.getContext().getAuthentication()判断，不通过就返回false。
7. 个人经验总结与源码使用建议
这套轻量级聊天室跑通以后，我对 WebSocket 的全链路理解比看十篇教程都深刻。框架本身不难，难的是握手、Session 管理、代理配置、断线重连这些边缘细节。我把这些细节尽量都处理进了项目里，比如 Session 线程安全、Nginx 的 Upgrade 头、心跳机制，你拿到源码后可以逐个删掉这些功能点，看看会出现什么问题，这比按部就班地抄代码更能提升水平。
使用源码时有三点提醒：第一，源码和文档在我的仓库里是配套的，建议先读 README 跑起来，再对照这篇博文一项项改；第二，注释我写得很详细，但核心的ChatSessionManager和ChatEndpoint建议你手敲一遍，这两个类的设计逻辑是 WebSocket 开发的通用套路；第三，项目自带前端页面只是演示用，接你自己的项目时，前端逻辑可以直接搬，后端接口字段基本不用动。
最后再分享一个小技巧：WebSocket 开发时一定要善于利用浏览器的开发者工具。Network 面板里筛选WS类型，可以实时查看每一条 WebSocket 消息的收发，配合后端的日志和断点，绝大多数问题半小时内能定位。遇到状态码 1006、连接被拒绝、消息不广播这类问题，先看 Network 面板确认握手是否成功、消息是否发出、收发是否符合预期，再决定从哪一层开始排查。养成这个习惯，以后做任何长连接项目都会顺手很多。
本文还有配套的精品资源，点击获取