Java WebSocket聊天系统课程设计：从协议设计到心跳与并发避坑

简介一套面向网络编程技术课程设计的Java WebSocket聊天系统资源包包含完整源代码与课程设计报告适合Java网络编程、WebSocket应用等课程实践和毕业设计参考。压缩包共74个文件、7.3MB主要涵盖14个Java源文件、HTML/CSS/JavaScript前端页面、SQL数据库脚本、Maven配置及docx报告png/jpg图片为界面截图和文档配图properties和xml为工程配置整体结构清晰便于导入IDE运行。系统实现用户名密码登录、多人同时在线、在线用户同步显示、群聊、私聊、管理员禁言与解禁、历史记录缓存读取数据库保存用户信息和聊天记录覆盖WebSocket长连接、在线用户列表维护、消息推送等关键知识点。附带课程设计报告、README、数据库初始化和Maven包装器可对照文档调试直接复用于课程设计或毕业设计。已有238人学习浏览适合需要完整可运行案例及配套文档的Java学习者。1. WebSocket聊天系统Java课程设计里性价比最高的网络编程题很多人在选课程设计题目时会在传统 TCP Socket 聊天室、HTTP 轮询聊天和 Java 基于 WebSocket 的聊天系统之间犹豫。不少人觉得 WebSocket 带个 Web 字眼要先学前端框架其实恰恰相反服务端用 Java 自带的javax.websocket或jakarta.websocket写一个带注解的类就能跑通全链路浏览器端的 WebSocket 接口更是原生支持的连第三方库都不用引。对课程设计而言这个题目既覆盖了 Socket 网络编程的核心概念又能直观演示浏览器和服务端全程双工通信的实时效果 —— 这是评审老师最认可的亮点之一。适合正在选课题、或者已经选了这个题但被“在线状态、心跳、并发、断线重连”卡住的同学。本文会把一个完整的 WebSocket 聊天系统从协议设计一路拆到代码实现、心跳机制、避坑清单和报告写法源码层面的核心就是一张 Session 管理表加一个端点类。顺着这个脉络走你不仅能交出一份能现场演示的课程设计还能在答辩时把每一步取舍讲清楚。2. 从选型到协议设计先想清楚别急着写ServerEndpoint2.1 为什么是 WebSocket 而不是“TCP Socket 轮询”这个问题基本是课程设计答辩时出现频率最高的问题。三种方案做聊天室老师通常会在看到系统后问如果在线人数到 500你的方案会卡在哪先说传统 TCP Socket 方案。Java 的ServerSocket能做出聊天室但客户端得是 Java 程序或自己写的 Socket 客户端浏览器访问不了。课程设计展示时你要么现场跑一个 Java Swing 客户端要么在主服务器加一个 Servlet 供网页访问那就凭空多出一层序列化协议复杂度立刻上去了。HTTP 轮询方案在 Web 端能跑但轮询的本质是“假实时”前端每 3 秒发一次setInterval请求到 Servlet服务端把最新消息返回来。问题有两个第一大量请求里都是空数据网络被人为放慢了第二消息延迟固定等于轮询间隔用户看到的是“聊天像对讲机”而不是实时消息。在答辩时你很难解释为什么聊天室消息要 3 秒才到达。WebSocket 的思路完全不同它面向浏览器但底层是 TCP 长连接。客户端与服务端完成一次 HTTP Upgrade 握手后连接一直保持。双方随时可以向对方推消息不再有轮询那层无效请求。对课程设计来说它完美覆盖了网络编程课程的关键知识点三次握手、HTTP Upgrade、自定义应用层消息格式、并发会话管理、心跳保活。这是普通聊天室题目很难同时覆盖到的。2.2 Java WebSocket 三条技术线怎么选原生 API、Spring WebSocket、还是 Netty明确了用 WebSocket 后服务端还有一个选型问题。这个选择直接决定你后续写的是几百行还是几千行代码。常见的实现路线有三条技术方案上手成本依赖数量适合场景javax.websocket/jakarta.websocket原生 API最低0~1 个容器课程设计、小规模演示、快速实现Spring Boot spring-boot-starter-websocket中多个 Spring 依赖需要和 Spring 容器、认证、事务整合的项目Netty 实现 WebSocket高1 个 Netty 包高并发、海量长连接、生产级推送服务对这个题目我一般推荐用原生 API也就是ServerEndpoint注解这种写法。原因有两条。第一代码可读性好。一个类就是一个端点逻辑集中小组同学能直接看懂答辩时你能指着代码讲清楚“这个回调什么时候被调用”。如果引入 Spring Boot注册、拦截器、握手配置会铺开在至少三个类里报告也随之变厚说服成本反而高。第二演示环境不容易翻车。原生 API 在 Tomcat、Jetty 里开箱即用。如果做成 Spring Boot 项目ServerEndpoint的类虽然也能注册但和 Spring 容器的整合有一些隐蔽问题我后面第 5 章会专门展开。如果你已经决定用 Spring Boot 写这个题目也不是不行但注入了 Spring Service 的端点类需要额外配置。这个坑很典型后面避坑章节里有完整说明。2.3 消息协议设计先用 JSON 把六种消息类型定下来“聊天系统”最容易做成只发一串纯文本。但一旦涉及上线、下线、在线人数展示、单聊群聊分流纯文本消息就会变成一个个 if-else 黑匣子。标准做法是把所有消息定义为 JSON用一个type字段区分消息类型。我项目里常用的协议结构如下{ type: chat | system | online | offline | ping | pong, from: 用户ID, to: 目标用户ID群聊时为空, content: 消息正文, timestamp: 1700000000000 }字段含义拆开说type消息类型。chat是聊天内容system是系统通知online和offline是用户上下线事件ping和pong是心跳保活报文。from发送者标识我使用登录页传入的 userId。to单聊时填目标用户 ID群聊时填空字符串。content消息正文可以是普通文本也可以约定为富文本 JSON。timestamp毫秒时间戳前端用来排序和展示时间。定义好协议后再设计端点逻辑。服务端拿到typepong时只需要确认连接存活不广播给其他人拿到typechat时才做群发或单发。这里有个细节值得在报告里写一段为什么typechat时不能直接拼好张三说你好再发送因为如果消息包装做在了服务端字符串里前端就无法统一解析更无法区分消息类型。用 JSON 结构体统一收发后续加“表情”、“提醒”、“文件消息”都只需要新增 type 和附件字段前端不用改整体逻辑。3. 服务端核心实现一个 200 行的端点类如何撑起聊天逻辑3.1 项目结构与会话管理ConcurrentHashMap 就是聊天室的“人员登记表”整个项目的核心结构通常只需要这几个 Java 文件src/main/java/com/example/chatsystem/ ├── endpoint/ │ └── ChatEndpoint.java # WebSocket 端点处理连接与消息 ├── model/ │ ├── Message.java # 消息实体对应 JSON 结构 │ └── MessageType.java # 枚举CHAT / SYSTEM / ONLINE / OFFLINE / PING / PONG ├── util/ │ └── JsonUtil.java # JSON 序列化工具Jackson 封装 └── manager/ └── SessionManager.java # 在线会话管理聊天系统的第一个关键点是服务端如何保存和管理所有在线连接。WebSocket 的Session可以理解为一个连接对象它的生命周期就是连接从建立到关闭。我们需要一个线程安全的集合来管理它。标准做法是使用ConcurrentHashMapString, Sessionkey 是用户 IDvalue 是 Session。为什么不能直接用HashMap因为聊天系统天然是多线程并发场景多个客户端同时发消息、一个客户端断开连接都会同时操作这个集合。如果使用普通HashMap并发读写时可能产生数据不一致甚至在高并发下触发环形链表问题表现为在线列表显示错乱、偶发抖动。这是我实际踩过的坑不信你可以把代码切回HashMap压测 20 个并发用户很快就能观察到。以下是会话管理类的完整实现package com.example.chatsystem.manager; import jakarta.websocket.Session; import java.io.IOException; import java.util.Collection; import java.util.concurrent.ConcurrentHashMap; /** * 会话管理工具类。 * 用 ConcurrentHashMap 保存 userId - Session 的映射 * 提供线程安全的添加、移除、遍历方法。 */ public class SessionManager { /** userId - WebSocket Session */ private static final ConcurrentHashMapString, Session ONLINE_SESSIONS new ConcurrentHashMap(); private SessionManager() {} /** 添加或覆盖用户会话 */ public static void add(String userId, Session session) { ONLINE_SESSIONS.put(userId, session); } /** 按 userId 移除会话 */ public static void remove(String userId) { ONLINE_SESSIONS.remove(userId); } /** 获取指定用户的会话可能为 null */ public static Session get(String userId) { return ONLINE_SESSIONS.get(userId); } /** 返回所有在线 Session 的集合 */ public static CollectionSession all() { return ONLINE_SESSIONS.values(); } /** 给所有在线用户群发消息 */ public static void broadcast(String message) { for (Session session : ONLINE_SESSIONS.values()) { try { synchronized (session) { session.getBasicRemote().sendText(message); } } catch (IOException e) { // 单个 Session 发送失败不能影响其他人 removeBySession(session); } } } /** 通过 Session 反查 userId 并移除用于广播失败的清理 */ private static void removeBySession(Session session) { ONLINE_SESSIONS.entrySet().removeIf(entry - entry.getValue().equals(session)); } }这段代码里有三个答辩时容易被追问的点第一为什么用ConcurrentHashMap而不是在方法上直接加synchronized因为ConcurrentHashMap通过分段锁和 CAS 实现了细粒度并发控制读操作基本不加锁广播场景下吞吐量明显更好。课程设计规模通常不会超过几百个连接用它能完全覆盖性能需求。第二broadcast里为什么要synchronized (session)因为 WebSocket 的Session.getBasicRemote()在设计上不允许两个线程同时写入同一个连接。多个用户同时发消息时广播线程可能在给 Session A 发送的同时单聊线程也在给同一个 Session A 推送这时会抛出IllegalStateException: The remote endpoint was in state [TEXT_FULL_WRITING]。锁 Session 本身是一种局部加锁并发粒度最小不会拖累全局。第三removeBySession为什么用removeIf因为广播循环中拿到的只有 Session 对象手里没有 userId。通过entrySet().removeIf()遍历查找并删除是非常直观的做法课程设计规模下性能可以接受。3.2 用ServerEndpoint写端点四个回调方法各干什么接下来是系统的核心文件ChatEndpoint.java。这个类标记了ServerEndpoint(/chat)后容器会在收到匹配路径的 WebSocket 握手请求时为每个连接创建一个端点实例。package com.example.chatsystem.endpoint; import com.example.chatsystem.manager.SessionManager; import com.example.chatsystem.model.Message; import com.example.chatsystem.util.JsonUtil; import jakarta.websocket.*; import jakarta.websocket.server.PathParam; import jakarta.websocket.server.ServerEndpoint; import java.io.IOException; import java.time.Instant; /** * ChatEndpoint 是一个 WebSocket 端点。 * 每个客户端连接持有一个 ChatEndpoint 实例。 */ ServerEndpoint(/chat) public class ChatEndpoint { /** 当前连接对应的用户 ID在 onOpen 时赋值 */ private String currentUserId; /** * 连接建立时调用。 * 客户端握手地址ws://localhost:8080/chat?userIdzhangsan */ OnOpen public void onOpen(Session session, QueryParam(userId) String userId) throws IOException { if (userId null || userId.isBlank()) { session.close(new CloseReason(CloseReason.CloseCodes.VIOLATED_POLICY, userId is required)); return; } this.currentUserId userId; // 同一 userId 重复登录时强制踢掉旧连接 Session oldSession SessionManager.get(userId); if (oldSession ! null oldSession.isOpen()) { oldSession.close(new CloseReason(CloseReason.CloseCodes.NORMAL_CLOSURE, duplicate login)); } SessionManager.add(userId, session); // 广播系统消息xxx 上线了 String systemMsg JsonUtil.toJson( new Message(system, system, , userId 上线了, Instant.now().toEpochMilli()) ); SessionManager.broadcast(systemMsg); } /** * 收到文本消息时调用。消息统一为 JSON 字符串。 */ OnMessage public void onMessage(String rawMessage, Session session) throws IOException { Message message JsonUtil.fromJson(rawMessage, Message.class); if (message null || message.getType() null) { return; // 非法消息直接丢弃 } switch (message.getType()) { case chat: handleChatMessage(message, session); break; case pong: // 心跳响应连接仍存活这里无需处理 break; case ping: // 服务端主动返回 pong确认连接 session.getBasicRemote().sendText(JsonUtil.toJson( new Message(pong, system, currentUserId, , Instant.now().toEpochMilli()) )); break; default: break; } } /** * 处理聊天消息单聊看 to 字段群聊则广播。 */ private void handleChatMessage(Message message, Session session) throws IOException { long now Instant.now().toEpochMilli(); if (message.getTo() null || message.getTo().isBlank()) { // 群聊消息广播给所有在线用户 String payload JsonUtil.toJson( new Message(chat, currentUserId, , message.getContent(), now) ); SessionManager.broadcast(payload); } else { // 单聊消息只发给 to 指定的用户 String payload JsonUtil.toJson( new Message(chat, currentUserId, message.getTo(), message.getContent(), now) ); Session target SessionManager.get(message.getTo()); if (target ! null target.isOpen()) { synchronized (target) { target.getBasicRemote().sendText(payload); } } } } /** * 连接关闭时调用从在线表移除并通知其他人。 */ OnClose public void onClose(Session session, CloseReason closeReason) { if (currentUserId ! null) { SessionManager.remove(currentUserId); String systemMsg JsonUtil.toJson( new Message(system, system, , currentUserId 下线了, Instant.now().toEpochMilli()) ); SessionManager.broadcast(systemMsg); } } /** * 出错时调用连接往往已不可用直接清理。 */ OnError public void onError(Session session, Throwable error) { error.printStackTrace(); if (currentUserId ! null) { SessionManager.remove(currentUserId); } try { if (session.isOpen()) { session.close(); } } catch (IOException ignored) { // 关闭动作本身失败就忽略 } } }服务端全链路就这么长。几个参数要注意QueryParam(userId)依赖容器对 query string 的解析。如果 URL 是ws://localhost:8080/chat?userIdzhangsan这个参数能正确注入。如果发现注入了 null先检查是不是把参数写在了路径里而不是?后面。session.getBasicRemote().sendText()是阻塞式发送发送时会等待消息写完getAsyncRemote().sendText()是非阻塞式但无法立刻知道是否失败。课程设计中用 BasicRemote 更直观几百个连接的性能完全没压力。synchronized (target)解决的是“同一个 Session 同时被两段逻辑推送”的场景。我在 3.1 里已经说明这里再次出现是因为单聊和群聊可能同时命中同一个用户不加锁就会触发TEXT_FULL_WRITING报错。3.3 消息体与 JSON 工具让代码更少的两个小类Message实体类字段要与 JSON 字段一一对应。Jackson 在反序列化时要求类有无参构造函数和 getter/setter。实现如下package com.example.chatsystem.model; /** * 消息实体字段与前端 JSON 报文一一对应。 */ public class Message { private String type; // chat / system / online / offline / ping / pong private String from; // 发送者 userId private String to; // 目标 userId群聊时为空 private String content; // 消息内容 private Long timestamp; // 毫秒时间戳 public Message() { } public Message(String type, String from, String to, String content, Long timestamp) { this.type type; this.from from; this.to to; this.content content; this.timestamp timestamp; } public String getType() { return type; } public void setType(String type) { this.type type; } public String getFrom() { return from; } public void setFrom(String from) { this.from from; } public String getTo() { return to; } public void setTo(String to) { this.to to; } public String getContent() { return content; } public void setContent(String content) { this.content content; } public Long getTimestamp() { return timestamp; } public void setTimestamp(Long timestamp) { this.timestamp timestamp; } }JsonUtil封装了 Jackson 的两个静态方法package com.example.chatsystem.util; import com.fasterxml.jackson.databind.ObjectMapper; public class JsonUtil { private static final ObjectMapper MAPPER new ObjectMapper(); public static String toJson(Object obj) { try { return MAPPER.writeValueAsString(obj); } catch (Exception e) { throw new RuntimeException(JSON 序列化失败, e); } } public static T T fromJson(String json, ClassT clazz) { try { return MAPPER.readValue(json, clazz); } catch (Exception e) { throw new RuntimeException(JSON 解析失败, e); } } private JsonUtil() {} }作为课程设计代码这种实现已经足够而且不会引入额外复杂度。很多同学喜欢在消息处理里用split(:)去解析文本表面看起来“少写了依赖”实际是把协议解析逻辑压进了条件分支后面加“撤回”、“消息”等能力时没人敢动。建议从一开始就用 JSON 结构体。4. 客户端接入与心跳机制浏览器端 100 行 JS但心跳必须做4.1 浏览器原生 WebSocket 对象连接、发送、收消息服务端建好后前端可以用极少的代码接入。现在的浏览器全部支持WebSocket对象不需要引任何库。聊天页面核心 JS 如下// 建立连接URL 前缀由当前页面协议决定 const protocol location.protocol https: ? wss:// : ws://; const ws new WebSocket(protocol location.host /chat?userId encodeURIComponent(currentUserId)); // 连接打开开始心跳 ws.onopen function () { console.log(WebSocket 连接已建立); startHeartbeat(); }; // 收到消息按 type 分发 ws.onmessage function (event) { const msg JSON.parse(event.data); if (msg.type chat) { appendMessage(msg); } else if (msg.type system) { appendSystemTip(msg.content); } else if (msg.type online || msg.type offline) { refreshOnlineList(); } // pong 消息不需要处理连接本身可用即可 }; // 发送聊天消息群聊 function sendChat(content) { const payload { type: chat, from: currentUserId, to: , // 群聊时 to 为空 content: content, timestamp: Date.now() }; ws.send(JSON.stringify(payload)); } // 连接关闭触发重连 ws.onclose function (event) { console.log(连接已关闭code event.code); stopHeartbeat(); reconnect(); };这段代码中要注意event.data在onmessage回调里默认是字符串因为服务端发的是文本帧。如果你的服务端配置了二进制处理器event.data会变成 Blob 或 ArrayBuffer那就需要额外做类型判断。保持两端都用文本帧是最省心的路线。4.2 WebSocket 心跳机制为什么服务端 60 秒就把连接静默断开初学者写完onopen和onmessage后会以为聊天功能完整了但运行几个小时后常见现象是浏览器右下角用户还在线发消息却无人应答。重新连接后在线列表才恢复。原因在服务端。WebSocket 底层是 TCP 连接空闲时间过长时网络设备防火墙、交换机、负载均衡器会静默中断连接服务端和客户端在断开瞬间可能感知不到直到下一次写数据时才抛异常。这个空闲超时时间通常只有 60 到 120 秒。如果不做心跳SessionManager里会堆积大量已死亡的 Session广播时向这些死连接发送拖慢整体效率。正确的做法是协议层带心跳客户端每隔一段时间发送一个ping文本帧服务端可选回复pong。如果连接已断客户端会在发送时立刻发现并触发重连如果连续多次没有收到pong客户端可以主动断开重新走完整的握手流程。实现方式有两种课程设计用第一种就能过。第一种是应用层心跳也就是在 JSON 消息里定义ping类型。浏览器 JS 如下let heartbeatInterval null; function startHeartbeat() { // 每 25 秒发一次应用层 ping heartbeatInterval setInterval(function () { if (ws.readyState WebSocket.OPEN) { ws.send(JSON.stringify({ type: ping, from: currentUserId, timestamp: Date.now() })); } }, 25000); } function stopHeartbeat() { if (heartbeatInterval) { clearInterval(heartbeatInterval); heartbeatInterval null; } }为什么选 25 秒而不是 60 秒因为防火墙的空闲超时通常设置为 60 到 120 秒。客户端发送间隔要远小于这个阈值留出网络延迟和服务端响应的余量。30 秒是常见折中25 秒更保守。第二种是底层 WebSocket 协议控制帧。Java 的Session支持主动发送 Ping 控制帧// 服务端主动发 ping 帧给客户端 session.getBasicRemote().sendPing(ByteBuffer.wrap(heartbeat.getBytes()));但浏览器 JavaScript 无法主动发送 Ping 控制帧只能被动响应。浏览器端做心跳发应用层 JSON 包是唯一没有兼容性问题的办法。所以课程设计项目统一用应用层 JSON 心跳两端逻辑一致好调试也好讲解。服务端这边还需要设置内置空闲超时来兜底。在onOpen方法里加一行// 超过 120 秒没有收到任何文本帧/控制帧容器自动关闭连接 session.setMaxIdleTimeout(120_000L);这里有一个配合关系值得在报告里解释客户端每 25 秒发一次 ping 文本帧虽然服务端收到 ping 后没有业务处理但容器会刷新空闲计时器连接不会因为 120 秒空转被关闭。如果客户端暂时没有数据要发但 ping 照发连接就能保持。这是课程设计里最能展示你理解协议层机制的细节之一。4.3 断线重连给用户一个“后悔药”断线重连是课程设计里的加分项。实现起点是onclose回调。我的做法是使用指数退避防止服务端抖动时大量客户端同时重连造成压力。let reconnectAttempts 0; const MAX_RECONNECT 10; let ws null; function initWebSocket() { const protocol location.protocol https: ? wss:// : ws://; ws new WebSocket(protocol location.host /chat?userId encodeURIComponent(currentUserId)); ws.onopen function () { console.log(WebSocket 连接已建立); reconnectAttempts 0; // 连接成功时重置重连计数 startHeartbeat(); }; ws.onmessage function (event) { // 同上文 4.1 的消息分发逻辑 }; ws.onclose function (event) { stopHeartbeat(); reconnect(); }; } function reconnect() { if (reconnectAttempts MAX_RECONNECT) { console.log(重连次数已达上限停止自动重连); return; } // 退避时间1s, 2s, 4s, 8s最多 30s const delay Math.min(1000 * Math.pow(2, reconnectAttempts), 30000); console.log(将在 delay ms 后重连, 第 (reconnectAttempts 1) 次); setTimeout(function () { reconnectAttempts; initWebSocket(); // 重新创建连接 }, delay); } // 页面加载时调用 initWebSocket();这里有一个关键细节答辩时老师大概率会问如果重连成功后旧的定时器还挂着会怎样答案是会重复发送心跳甚至可能触发旧连接的onclose重复执行。所以每次重连前必须stopHeartbeat()同时使用全局变量ws指向当前连接旧连接的事件回调就自然废弃了。断线重连的另一个角度是服务端视角的正常关闭与异常关闭。在onClose里第二个参数CloseReason携带关闭码可以通过closeReason.getCloseCode()判断是正常关闭NORMAL_CLOSURE还是异常断开GOING_AWAY、ABNORMAL_CLOSURE。课程设计里通常不区分统一广播下线即可但报告里如果写了这个判断逻辑会显得你对异常处理有意识。5. 避坑指南WebSocket 课程设计里最常翻车的 6 个实践问题以下是这题目里频率最高的踩坑记录。每条都按“现象 → 原因 → 解决”写自己遇到时能直接对上号。5.1 并发推送到同一 SessionTEXT_FULL_WRITING 异常现象两个用户几乎同时发消息服务端控制台间歇性抛出IllegalStateException: The remote endpoint was in state [TEXT_FULL_WRITING]。随后某个用户的连接断开甚至 Tomcat 线程池报错。原因Session.getBasicRemote().sendText()本身虽然是同步阻塞方法但 WebSocket 会话对象不支持同一时刻有多个线程同时写入同一个连接。广播线程 A 正在给 Session X 发消息时单聊线程 B 也要给 Session X 写就会触发状态冲突。解决在发送到同一个 Session 的地方加锁且锁必须加在 Session 对象上而不是加在工具类的全局方法上。因为如果锁住SessionManager本身所有连接的发送操作会被串行化广播性能断崖式下降答辩时经不起“为什么你的系统延迟这么高”的追问。我在 3.1 和 3.2 里都做了synchronized (session)这是最小粒度的并发控制。更彻底的办法是每个 Session 内部放一个发送队列由一个消费者线程串行发送。课程设计规模不推荐写了反而显得过度工程。5.2 Spring Boot 项目里ServerEndpoint的依赖注入为 null现象题目叫“Java 基于 WebSocket 的聊天系统”同学用 Spring Boot 创建项目在端点类里写Autowired注入一个业务 Service结果运行时 NullPointerException。原因Spring Boot 默认把ServerEndpoint端点的实例化交给 Tomcat 的 WebSocket 运行时管理不经过 Spring 容器。ChatEndpoint.class上的每个实例都是容器直接new出来的Autowired注解根本没有机会被处理。解决有两个思路。第一种给端点指定 Spring 配置器ServerEndpoint(value /chat, configurator SpringConfigurator.class) public class ChatEndpoint { Autowired private ChatService chatService; // ... }需要保证 Spring 容器中能扫描到SpringConfigurator。如果项目是纯 Spring Boot依赖在spring-boot-starter-websocket里已经包含了。第二种也是我推荐的课程设计路线不要让业务逻辑依赖 Spring 容器。把ChatService的方法写成SessionManager的静态方法端点类直接调用不注入任何 Bean。这样一来项目即使换到纯 Tomcat 环境也能跑报告里还能写清楚“我们通过静态会话管理器隔离了业务层与端点层”。5.3 中文乱码sendText 字符串正常但显示成问号现象服务端广播一条中文消息浏览器收到后全部显示为??英文字符和数字正常。原因大部分时候不是 WebSocket 的问题而是前端页面编码不对。WebSocket 协议规定文本帧使用 UTF-8 编码浏览器解码也没问题。真正的原因是 HTML 页面没有声明 UTF-8浏览器按系统默认编码解析了接收到的文本。解决检查 HTML 头部是否包含meta charsetUTF-8同时确认项目里的 JSP 或模板引擎没有强制覆盖编码。还有一种少见情况如果你在握手阶段用session.getBasicRemote().sendText()推送了带中文的欢迎消息但客户端在onmessage里用了event.data.toString(gbk)之类的转换那也会乱码。统一用JSON.parse(event.data)不要手动做字节转换。5.4 握手 404ServerEndpoint路径配了但连不上现象浏览器控制台报WebSocket connection to ws://localhost:8080/chat failed: Error during WebSocket handshake: Unexpected response code: 404。原因这个问题的排查路径比想象中长。常见情况有三种项目部署在某个 context 下例如访问地址是http://localhost:8080/chatsystem/WebSocket 地址却写成了ws://localhost:8080/chat少了 context 路径。正确地址应是ws://localhost:8080/chatsystem/chat。你用了ServerEndpoint(/chat)但端点类没有被容器扫描到。Tomcat 在启动时扫描带有ServerEndpoint注解的类如果类不在WEB-INF/classes下或者 jar 包冲突导致类加载失败端点就不会注册。Tomcat 版本和javax.websocket/jakarta.websocket包版本不匹配。Jakarta EE 9 之后命名空间从javax.*改成jakarta.*。你导入jakarta.websocket但项目跑在 Tomcat 9 上或者反过来都会导致端点类被忽略。解决按顺序排查。在浏览器 Network 面板看握手请求的完整 URL确认 context 路径。检查部署目录WEB-INF/classes下有没有编译出的ChatEndpoint.class。查看 Tomcat 启动日志中是否有WebSocket[/chat] has been registered之类的记录没有就说明扫描失败。确认容器版本和命名空间匹配Tomcat 9 对应javax.*Tomcat 10 对应jakarta.*。5.5 僵尸连接堆积广播越来越慢现象系统运行一段时间后消息延迟明显升高。发一条消息要 2~3 秒才送达在线人数显示 80实际上活跃用户只有 3 个。原因客户端直接关闭浏览器 Tab 时TCP 四次挥手可能没有正常走完服务端没有及时收到 FIN 包onClose不会被触发。SessionManager里残留了大量isOpen()false的僵尸连接。广播时逐个向这些死连接写数据每次都要等待超时后才抛 IOException发送线程被严重拖慢。解决不依赖onClose做唯一清理路径广播时加活性校验。我在 3.1 的broadcast()里已经处理发送前判断session.isOpen()发送失败捕获 IOException 并立刻移除。同时打开服务端空闲超时session.setMaxIdleTimeout(120_000L);连接超过 120 秒没有任何通信时容器会主动关闭它从而触发onClose从源头减少僵尸连接。这两个机制配合使用问题基本能解决。5.6 局域网演示时连接失败本地却能跑现象本地localhost演示一切正常换到实验室局域网另一台机器访问页面时 WebSocket 一直连接失败HTTP 页面却能打开。原因WebSocket 握手走的是ws://协议如果是 HTTPS 站点浏览器强制要求wss://。另外如果你在代码里写死了ws://localhost:8080其他机器访问时自然连的是它们自己的 localhost当然失败。解决前端不要写死地址使用当前页面的 host 拼 WebSocket 地址。我在 4.1 里写的location.host就是为这个场景服务的。如果是部署在生产环境还要确认反向代理有没有把Upgrade和Connection这两个 HTTP 头透传给后端服务。很多服务器软件包括 Nginx默认会剥离这两个头导致 WebSocket 握手在代理层直接失败。课程设计如果只是局域网演示用location.host就能解决 80% 的问题。6. 课程设计报告与进阶验证把“能跑”变成“经过验证的能跑”6.1 报告怎么搭让评审老师顺着你的思路走这个题目的课程设计报告有相对固定的结构需求分析、总体设计、详细设计、系统实现、测试与结果、总结。我在写报告时习惯把“消息协议设计”单独拎出来写一节而不是混在详细设计里。原因是评审老师最关心三件事你怎么定义消息格式、怎么管理并发会话、怎么处理生命周期。这三块统称协议设计。报告里要画清楚三张图系统总体架构图浏览器 → WebSocket 连接 → ChatEndpoint → SessionManager → 广播/单发。端点状态图连接建立含 userId 校验→ 收发消息chat/pong→ 关闭正常/异常。消息时序图客户端 A 发送一条 chat 到客户端 B 的完整交互链路。不需要花哨的 UML 工具手画的框图拍照放进去即可。重点是让老师一眼看出你知道“一条消息从 A 到 B经过了哪些组件、哪些方法、哪些数据结构”。这是你的源代码在报告层面的落地路径。6.2 验证方法心跳维持测试与并发连接测试课程设计结束后自己先做验证比答辩时临场翻车强。最少做两个测试。第一个是心跳维持测试。用两个浏览器 Tab 登录不同的账号其中一个 Tab 挂后台 30 分钟然后回到前台发一条消息。如果不通说明空闲超时设置或心跳间隔配合有问题。更直接的验证是打开浏览器开发者工具的 Network 面板筛出 WebSocket 连接可以看到客户端每 25 秒发出的ping帧和收到的pong帧记录。第二个是并发连接测试。课程设计不需要上 JMeter用小脚本开 30 个线程同时连接即可。这里要注意一个设计上的差异ServerEndpoint会给每个连接创建一个端点实例各个实例的currentUserId是独立的而SessionManager中的ONLINE_SESSIONS是全局共享的。写并发测试时要验证每个连接的currentUserId没有串号也就是 A 用户发消息只有 A 的会话会带上 A 的身份。可以写一个简单的 Java 客户端测试类import jakarta.websocket.*; import java.net.URI; public class WebSocketClientTest { public static void main(String[] args) throws Exception { WebSocketContainer container ContainerProvider.getWebSocketContainer(); for (int i 1; i 10; i) { int userId i; new Thread(() - { try { Session session container.connectToServer(new Endpoint() { Override public void onOpen(Session session, EndpointConfig config) { System.out.println(客户端 userId 已连接); // 注册文本消息处理器 session.addMessageHandler(String.class, msg - System.out.println(客户端 userId 收到: msg)); } }, URI.create(ws://localhost:8080/chatsystem/chat?userIduser userId)); Thread.sleep(5000L); session.close(); } catch (Exception e) { e.printStackTrace(); } }).start(); } } }这个测试类会创建 10 个并发连接每个连接收到服务端广播时打印自己的 userId。如果打印出来的消息中出现了别的 userId 的广播内容说明你的消息被错误路由了。这个十几行的类在答辩现场是很有说服力的“源代码级验证”。6.3 进阶方向从群聊到单聊、离线消息与跨设备如果你想在这个题目上拿更高分把下面几个点穿插进报告档次会有明显不同。第一个是单聊的可达性处理。群聊系统只需要广播单聊需要根据to字段找到目标 Session发之前校验目标是否在线。如果不在线可以先写入内存MapString, ListMessage暂存离线消息等对方上线后拉取。课程设计阶段用内存方案可以接受但报告里要写清楚“内存方案重启即丢失生产环境需要数据库或 Redis”。第二个是重连后的状态恢复。断线重连虽然做了但重连后currentUserId会重新走一遍onOpen此时SessionManager.add()会把旧 Session 顶掉。这里隐藏一个 bug旧 Session 的onClose如果晚于新 Session 的onOpen触发旧 Session 的下线广播会把刚上线的用户又广播下线。解决办法是在onOpen里加一段重复登录检测检测到旧 Session 存在时先主动关闭它再注册新 Session。我在 3.2 的代码里已经写了这个逻辑可以直接作为参考答案。第三个是部署前的反向代理检查。如果系统要放到有公网域名的服务器上Nginx 这类反向代理默认不会透传Upgrade和Connection头WebSocket 握手会在代理层失败。需要在代理配置里显式增加这两条头信息的转发。这个问题在课程设计局域网演示时不会出现但如果老师问到“为什么部署到云服务器上连不上”能用这个知识点答上会非常加分。最后说说我个人的习惯拿到这种题目我不会先写代码而是先花一晚上敲定协议字段和 Session 管理方式。写完后再回头补整个系统无论如何扩展都没脱离“JSON 协议 SessionManager 注册表 心跳超时”这三个支柱。把这段核心逻辑在报告里讲透以后遇到任何变体题目——在线问答、实时白板、消息推送——都能快速迁移。这是这个题目最值钱的部分也是我做这个题最深的体会希望帮到你。本文还有配套的精品资源点击获取