简介一套基于Java SpringBoot与Vue全家桶构建的即时通讯管理系统完整代码包面向Java后端与Web前端学习者、毕业设计开发者解决了从零搭建在线聊天交友平台的需求。系统涵盖登录注册、会话列表、通讯录、好友管理、收藏、个人资料维护等模块消息发送支持文本、图片、文件并附带文件下载与图片预览功能前后端分离架构后端集成Mybatis与Redis可方便扩展。资源包共1889个文件约74.55MB以css、less、js、png、java、xml、class等为主其中前端样式与脚本、后端业务代码与配置文件分类清晰另附数据库备份及sql文件方便快速还原环境。目前已有619人学习下载适合需要完整项目参考或在此基础上做二次开发的读者。除源码外还提供部署答疑支持遇到环境配置或启动问题可联系作者获得协助。1. 即时通讯管理系统不是聊天玩具是前后端协同的完整工程很多人第一次拿到《即时通讯管理系统JavaSpringBootvueelementui》这个资源时第一反应是“这不就是个聊天软件嘛”。真跑一遍就会意识到聊天只是表面复杂度全在后端的会话管理、消息协议设计以及前端状态同步这几块上。这套毕设级的系统做的是典型的前后端分离工程SpringBoot负责用户、好友、会话和消息的持久化Vue3配合ElementUI负责界面与实时推送核心通信走WebSocket而不是简单的轮询。适合正在做Java方向毕设的学生、想补全实时通信这块短板的初级后端工程师以及需要给团队快速搭一个内部沟通工具的开发者。下面我按照从拿到代码到跑通部署的实际顺序把架构、后端、前端、避坑和部署逐层拆开。2. 架构拆解为什么是SpringBootVueElementUI以及九大模块怎么切2.1 这套技术栈的组合逻辑Java生态与前端工程化的碰撞选SpringBoot做后端最直接的理由是它对WebSocket和消息推送的支持已经非常成熟spring-boot-starter-websocket一个依赖就能把原生WebSocket端点注册起来不需要自己写复杂的握手逻辑。配合Spring Security或者简单的拦截器做登录鉴权比传统的ServletTomcat方案省掉一大截配置成本。前端选Vue3ElementUI是因为这套组合在“表单密集状态多变”的聊天场景里手感很好ElementUI的卡片、输入框、气泡样式开箱即用Vue的响应式数据模型天然适合渲染实时消息列表。我自己做技术选型时一直遵循一个原则毕设或者中小型内部项目优先选“整个团队都熟”的社区型技术栈而不是追求冷门框架带来的新鲜感。SpringBootVueElementUI恰好是简历上最常见、社区问答覆盖最全的组合遇到报错搜得到答案这比什么都重要。2.2 整体模块划分从网关到消息通道拆出九个关键模块这套系统的后台拆法大致是这样网关层负责路由与登录鉴权用户模块管注册登录和头像资料好友模块管添加好友、好友列表和好友申请会话模块管单聊和群聊会话的创建消息模块管消息的发送、接收和离线补发WebSocket模块管长连接的心跳和推送通知模块管系统公告和好友申请提醒文件模块管聊天图片和附件的上传最后还有一个数据统计模块给管理端看在线人数和消息量。这个九模块的划分不是拍脑袋而是顺着“用户发起行为→经过会话→落到消息→推送对端→必要时持久化”这条链路拆的。做毕设答辩时面试官或者老师最喜欢问的一句话是“你的数据库为什么这么设计”如果你能顺着这条链路把模块边界讲清楚比背一百遍概念都有说服力。每个模块之间通过Service接口互相调用WebSocket模块只依赖消息模块的接口不直接操作Mapper这样后面加离线消息功能时不用改动连接层。2.3 数据模型设计用户、好友、会话、消息四张核心表这套系统的核心表结构不复杂但每一张都有讲究。用户表里除了基本的id、username、password还多两个容易忽略的字段online_status和last_login_time。online_status不是给前端轮询用的而是为了保证WebSocket重连时能快速恢复会话状态last_login_time直接决定“最近一次在线”这个状态的展示去掉它的话好友列表里的在线状态就只能靠实时心跳硬撑一旦用户断网又没来得及发离线包状态就会错乱。好友表用的是“双向冗余”设计A加B时插入两条记录(A,B)和(B,A)都写进去查询时直接查“我是左端或右端”即可避免每次都要做一次双向匹配的联合查询。会话表里只有id、session_type和last_message_timesession_type用0单聊、1群聊区分不存具体成员成员关系单独放到会话成员表。消息表则单独存session_id、from_user、message_type、content、create_time和statusstatus字段的值0未读、1已读、2已撤回。这四张表的关系可以这样记用户和好友是社交关系会话是聊天容器消息是用户产生的具体内容。当初我自己写第一版时贪方便把消息直接挂到用户表下面结果群聊场景没法做“按会话拉历史记录”后来才补了会话成员表这是一笔花了两个晚上才还上的技术债。表名核心字段设计要点userid, username, password, online_status, last_login_timeonline_status配合WebSocket会话恢复不依赖前端轮询frienduser_id, friend_id, create_time双向冗余插入查询免去双向匹配sessionid, session_type, last_message_timesession_type区分单聊群聊成员关系不落在此表session_membersession_id, user_id, unread_count每用户记录未读数撑起聊天列表的红色角标messageid, session_id, from_user, message_type, content, statusstatus支持未读、已读、撤回三种状态提示password字段不要存明文毕设答辩时“密码是否加密存储”是高频问题建议用BCrypt做哈希Spring Security自带的BCryptPasswordEncoder可以直接用。3. 后端实战WebSocket会话管理、统一消息协议与离线补发的三块硬骨头3.1 会话管理用ConcurrentHashMap维护在线用户而不是数据库轮询很多教程喜欢把在线用户塞进数据库然后让前端定时轮询状态这在小规模演示里能跑但并发一上来数据库查询就成瓶颈了。常见做法是后端启动时维护一个ConcurrentHashMapString, WebSocketSessionkey是用户IDvalue是WebSocket会话对象。这样查询在线状态只需要一次内存查找不用碰数据库。这个Map要放在一个独立的会话管理类里用静态方法暴露方便其他Service直接调用。下面是一个标准的SpringBoot WebSocket配置类Configuration EnableWebSocket public class WebSocketConfig implements WebSocketConfigurer { // 把自定义的Handler注册到 /ws 端点 Override public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { registry.addHandler(new ChatWebSocketHandler(), /ws) .setAllowedOrigins(*); // 跨域放开生产环境按域名收窄 } }这里的/ws就是前端连接WebSocket的路径setAllowedOrigins(*)是开发阶段用来解决跨域握手失败的手段部署上线后建议改成具体域名否则任何网站都能连你的长连接安全隐患不小。注册Handler之后核心逻辑都写在ChatWebSocketHandler里它需要重写afterConnectionEstablished、handleTextMessage、handleTransportError和afterConnectionClosed这四个方法。afterConnectionEstablished里做的事就是取出握手时带的userId参数把会话对象放进MapafterConnectionClosed则负责从Map里移除用户同时把离线时间写回数据库。Component public class ChatWebSocketHandler extends TextWebSocketHandler { // 全局在线会话表key为userIdvalue为WebSocketSession private static final ConcurrentHashMapString, WebSocketSession ONLINE_SESSIONS new ConcurrentHashMap(); Override public void afterConnectionEstablished(WebSocketSession session) throws Exception { String userId (String) session.getAttributes().get(userId); ONLINE_SESSIONS.put(userId, session); // 用户变为在线状态供好友列表实时展示 userService.updateOnlineStatus(userId, true); } Override protected void handleTextMessage(WebSocketSession session, TextMessage message) throws Exception { // 解析统一消息体分发到对应会话 ChatMessage chatMessage JSON.parseObject(message.getPayload(), ChatMessage.class); messageService.sendMessage(chatMessage); } Override public void afterConnectionClosed(WebSocketSession session, CloseStatus status) { String userId (String) session.getAttributes().get(userId); ONLINE_SESSIONS.remove(userId); userService.updateOnlineStatus(userId, false); } }逻辑说明afterConnectionEstablished在握手成功后立刻执行把userId作为Map的key存进去handleTextMessage收到任何前端消息时先解析成统一消息体再交给messageService.sendMessage去处理落库和推送给对方。这样WebSocket层不直接操作数据库保持职责单一。参数上要注意session.getAttributes()里的userId需要在握手时通过HandshakeInterceptor提前塞进去否则这里拿不到。3.2 消息协议统一的消息体是避免“各写各的”的唯一出路前后端通信最忌讳的是每个接口各传各的字段今天传content明天传messageContent前端解析逻辑就得跟着写两套。这套系统里用一个统一的消息实体来兜底用type字段区分单聊、群聊和系统通知。实际项目里我会把消息类型写成枚举而不是用魔法数字这样后端判断逻辑可读性更强前端也能直接用枚举值做渲染分支。public class ChatMessage { private String fromUserId; // 发送方ID private String toUserId; // 接收方ID单聊时必填 private String sessionId; // 会话ID决定消息归属哪个会话 private Integer messageType; // 0文本 1图片 2文件 3系统通知 private String content; // 消息内容或文件URL private Long timestamp; // 客户端发送时间用于排序 private Integer chatType; // 0单聊 1群聊 }字段说明sessionId是核心关联键后端收到消息后直接按它找到会话成员决定推送给哪几个人timestamp用客户端时间而不是服务器时间是为了避免消息列表出现“后发先至”的视觉错乱chatType和sessionId其实信息有重叠但保留它可以让前端免一次查会话表就能判断渲染形式。消息发送的核心函数大概长下面这样public void sendMessage(ChatMessage chatMessage) { // 1. 落库status默认0未读 messageMapper.insert(chatMessage); // 2. 判断是单聊还是群聊 if (chatMessage.getChatType() 0) { // 单聊直接找对方在线会话推送 WebSocketSession toSession ONLINE_SESSIONS.get(chatMessage.getToUserId()); if (toSession ! null toSession.isOpen()) { toSession.sendMessage(new TextMessage(JSON.toJSONString(chatMessage))); } } else { // 群聊遍历会话成员表逐个推送 ListString memberIds sessionMemberMapper.listMemberIds(chatMessage.getSessionId()); for (String memberId : memberIds) { if (memberId.equals(chatMessage.getFromUserId())) continue; WebSocketSession memberSession ONLINE_SESSIONS.get(memberId); if (memberSession ! null memberSession.isOpen()) { memberSession.sendMessage(new TextMessage(JSON.toJSONString(chatMessage))); } } } }这段逻辑说明了两个关键点第一落库一定在推送之前这样即使推送失败消息也不会丢下次上线可以补拉第二单聊和群聊的推送路径分开单聊查一次Map群聊查一次数据库成员表避免群聊场景下反复做无效查询。这里用ONLINE_SESSIONS.get(toUserId)返回null就代表对方不在线不走异常分支直接靠离线消息机制兜底。3.3 心跳与离线补发断线重连的兜底方案与数据库补发逻辑WebSocket长连接在真实网络环境里不是永生的公司WiFi切换、手机锁屏、路由器休眠都会让连接变成“假死”状态——TCP层面还连着但实际已经收不到数据了。这套系统的心跳策略是前端每30秒发一个ping类型的消息后端收到后回一个pong后端同时维护一个lastHeartbeatTime超过90秒没收到心跳就主动关闭旧连接。这里有个容易翻车的细节心跳消息不能走handleTextMessage的正常分发路径否则会在数据库里落一堆无意义记录要在协议里单独定义HEARTBEAT类型在处理器最前面拦一下。离线消息补发的逻辑我一般这么做用户上线时拉取status 0且toUserId 当前用户的消息把这些消息通过WebSocket推给前端然后把状态改为已读。关键在于拉取范围要限定在会话内而不是全表拉取否则消息量大时一次上线会卡顿半天。public void sendOfflineMessages(String userId) { // 只拉最近7天的未读消息避免历史消息堆积 ListChatMessage offlineMessages messageMapper.listOfflineMessages(userId, 7); WebSocketSession session ONLINE_SESSIONS.get(userId); if (session null || !session.isOpen()) { return; } for (ChatMessage message : offlineMessages) { session.sendMessage(new TextMessage(JSON.toJSONString(message))); } // 批量更新为已读 messageMapper.batchMarkRead(offlineMessages); }这段代码的执行顺序很讲究先拉未读列表再推送最后更新已读状态。如果先更新已读再推送推送途中连接断开消息就彻底丢了用户什么都看不到。listOfflineMessages(userId, 7)里的7是时间窗口参数可按实际消息量调整如果场景要求全部历史可查这个参数可以去掉但建议额外加一个分页参数防止一次性拉出几千条数据把浏览器卡死。4. 前端实战Vue3ElementUI的消息UI层怎么和WebSocket握手4.1 前端工程初始化与路由设计登录、会话列表、聊天窗口三层跳转前端项目用Vite构建Vue3的script setup语法写起来比Options API简洁不少。路由设计走三级结构/login登录页、/chat会话列表页、/chat/:sessionId聊天窗口页。这里有一个细节值得注意聊天窗口页不应该真的让用户跳转路由而是应该通过点击会话列表项来更新当前激活的会话ID因为路由切换会导致组件重渲染WebSocket连接就可能断掉。所以/chat/:sessionId用同一个组件通过watch监听route.params.sessionId的变化来切换聊天对象。路由配置里还需要加一个全局前置守卫检查本地有没有token没有就直接踢到登录页router.beforeEach((to, from, next) { const token localStorage.getItem(token); if (to.path ! /login !token) { next(/login); } else { next(); } });这段守卫的逻辑很简单放行的前提是“要么去登录页要么带着token”。实际项目里我还会配合ElementUI的ElMessage弹窗提示“登录已过期请重新登录”但为了不打断演示流程守卫里只做跳转不做弹窗。这里提一个常见误用把token放到sessionStorage里关浏览器就丢用户刷新页面就掉线毕设演示时容易翻车建议直接用localStorage持久化。4.2 WebSocket客户端封装连接、订阅、重连与Token鉴权前端不能每个组件都裸写new WebSocket()要封装成一个全局单例。我常用的封装方式是把WebSocket实例放在一个ws.js模块里导出connectWebSocket(userId, token)和sendMessage(msg)两个函数。连接时在URL上拼userId和token两个参数后端握手拦截器从query里取出来校验身份。心跳用setInterval定时发ping每次收到服务端消息就重置一个看门狗计时器——这是我从实际失败里学到的只发心跳不看回应等于没发连接断了心跳还在傻傻继续白费带宽。断线重连要加指数退避第一次1秒、第二次2秒、第三次4秒最大30秒避免服务端还没恢复时客户端疯狂重连把服务打挂。// src/utils/ws.js let ws null; let heartbeatTimer null; let reconnectCount 0; export function connectWebSocket(userId, token) { const protocol window.location.protocol https: ? wss:// : ws://; const url ${protocol}${window.location.host}/ws?userId${userId}token${token}; ws new WebSocket(url); ws.onopen () { console.log(WebSocket连接成功); reconnectCount 0; startHeartbeat(); }; ws.onclose () { stopHeartbeat(); // 指数退避重连 const delay Math.min(1000 * Math.pow(2, reconnectCount), 30000); reconnectCount; setTimeout(() connectWebSocket(userId, token), delay); }; ws.onmessage (event) { const msg JSON.parse(event.data); // 外部通过事件订阅接收不在这个文件里处理业务 window.dispatchEvent(new CustomEvent(ws-message, { detail: msg })); }; } function startHeartbeat() { heartbeatTimer setInterval(() { if (ws ws.readyState WebSocket.OPEN) { ws.send(JSON.stringify({ type: HEARTBEAT })); } }, 30000); } function stopHeartbeat() { clearInterval(heartbeatTimer); heartbeatTimer null; } export function sendMessage(msg) { if (ws ws.readyState WebSocket.OPEN) { ws.send(JSON.stringify(msg)); } else { throw new Error(WebSocket未连接); } }参数说明userId和token拼在query上是为了让后端在握手拦截器里做鉴权不需要额外的鉴权报文心跳间隔30秒是跟后端90秒超时时间对应的留了3倍余量避免网络抖动误杀。window.dispatchEvent这个自定义事件是组件解耦的关键聊天窗口组件只监听ws-message不需要知道WebSocket内部怎么运作。每次连接成功后重置reconnectCount防止旧连接的重连计数器污染新连接的重连节奏。4.3 聊天窗口消息列表渲染、滚动定位与发送状态机聊天窗口是前端最容易被细节绊倒的地方。消息列表用v-for渲染每条消息根据fromUserId是否等于当前用户判断左右对齐然后用ElementUI的el-card或者自绘气泡展示。滚动定位有一个血泪经验消息渲染完成后滚动条要手动拉到最底部而且必须等到nextTick之后再执行否则新消息还没渲染进DOMscrollTop怎么设都白搭。发送消息的状态机也值得说用户点击发送后先把消息push进本地数组再通过sendMessage发给后端等后端推送回确认消息时把本地消息状态从“发送中”改成“已发送”。这套“先入为主、后确认”的策略能极大改善聊天手感用户点了发送立刻在界面上看到自己的消息不用等网络往返。script setup import { ref, nextTick, watch } from vue; import { useRoute } from vue-router; import { sendMessage } from /utils/ws; const route useRoute(); const messageList ref([]); const chatWindowRef ref(null); const inputContent ref(); // 监听路由参数切换会话 watch(() route.params.sessionId, async (newSessionId) { const history await fetchHistory(newSessionId); messageList.value history; scrollToBottom(); }); function handleSend() { const content inputContent.value.trim(); if (!content) return; // 本地先行追加标记status为0表示发送中 messageList.value.push({ fromUserId: currentUserId, content, status: 0, timestamp: Date.now() }); scrollToBottom(); // 真正的WebSocket发送 sendMessage({ fromUserId: currentUserId, sessionId: route.params.sessionId, chatType: route.params.chatType, content }); inputContent.value ; } async function scrollToBottom() { await nextTick(); chatWindowRef.value.scrollTop chatWindowRef.value.scrollHeight; } /script这段代码的核心思路是“本地乐观更新”先把用户输入渲染到界面上再走WebSocket发送视觉上零延迟。status字段在后续收到服务端回执时更新为1前端就能根据状态在消息右下角显示“发送中”或“已发送”的小字。scrollToBottom里的nextTick是硬性依赖少了它滚动条永远停在旧位置。在真实项目中还需要监听ws-message事件把对方发来的新消息追加到messageList同样调用scrollToBottom这样对方的话才会实时出现在屏幕上。5. 避坑记录跑通这套即时通讯系统后我补上的五个重要缺口5.1 跨域导致的WebSocket握手失败现象前端new WebSocket之后永远停在CONNECTING状态控制台报403 Forbidden后端日志完全没有握手请求进来。 原因前端开发服务器跑在localhost:5173后端接口在localhost:8080WebSocket握手请求的Origin头不匹配被Tomcat默认的跨域策略拦下。 解决在后端registerWebSocketHandlers里调setAllowedOrigins(*)开发期放开生产环境改成前端实际访问的域名。另外要注意setAllowedOrigins只能管住WebSocket握手HTTP接口的跨域还得单独配CorsFilter两码事。5.2 消息重复或乱序显示现象同一批历史消息拉取两次聊天窗口里出现重复气泡多设备同时登录时消息顺序忽前忽后。 原因离线消息补发和主动拉历史记录没有做去重前端拿timestamp做排序但客户端和服务器时间有偏差。 解决前端以timestamp为排序键同时用后端返回的messageId做去重渲染前先过滤掉已存在的ID。时间偏差问题靠“服务器时间覆盖”拉取历史记录时返回一次服务器当前时间前端用它校准本地时钟偏移量排序前先加偏移量再排。5.3 Vue打包部署到服务器后白屏现象本地npm run dev一切正常npm run build之后把dist放到Nginx里打开是空白页控制台报资源404。 原因Vite默认base是/打包出来的index.html里引用的是/assets/xxx.js绝对路径部署到子目录或者经过一层转发后路径就对不上了。 解决在vite.config.js里设base: ./用相对路径引用资源。注意改了base之后Vue Router的createWebHistory也要改成createWebHashHistory否则手动刷新页面会404。// vite.config.js export default defineConfig({ base: ./, // 相对路径适配子目录部署 plugins: [vue()], server: { host: 0.0.0.0, port: 5173 } });参数说明base: ./让打包后的CSS和JS都走相对路径index.html放在任何一级目录都能被正确加载createWebHashHistory让路由以#开头刷新时Nginx不会去找/chat这个不存在的真实文件直接回退到index.html。如果部署在域名根路径这两项可以不改但在毕设演示这种“随时可能换个文件夹跑”的场景里改掉更放心。5.4 长时间挂着页面消息突然发不出去现象页面挂了一个小时后再点发送没反应控制台没有报错WebSocket状态显示OPEN。 原因这是经典的“假死连接”。空闲期间路由器NAT表项过期但TCP连接没有收到关闭通知浏览器和服务器都不知道连接已死。 解决前端心跳不能只发ping还要监听onclose事件后端90秒没收到心跳就主动close。前端在onclose里触发重连逻辑重连成功后reconnectCount归零。另外发送消息时加一个readyState ! WebSocket.OPEN的兜底判断触发重连而不是直接抛出异常。5.5 原生WebSocket和STOMP之间的选择现象部分教程推荐用STOMP协议代码写起来确实更简洁但遇到私有协议定制时反而处处受制。 原因STOMP在SpringBoot里用起来有一套自己的订阅模型适合“多房间广播”场景但即时通讯这种“点对点精准推送自定义消息类型”的落地下STOMP的convertAndSendToUser反而把会话管理逻辑藏到了框架黑匣子里出问题时排查链路长。 解决这个系统选择原生WebSocket 自定义JSON协议。理由有三一是依赖极少不需要额外引入spring-messaging和STOMP相关包二是会话管理掌握在自己手里单个用户的连接状态随时可查三是消息协议自己定义前后端都清晰。如果你的场景是标准的“客户端订阅某个频道”用STOMP没问题但如果是点对点聊天原生WebSocket反而更可控。6. 部署与验证用Docker Compose把前后端打包成一个可演示的工程部署这块我踩过不少坑OpenJDK版本不匹配、MySQL编码不对导致中文乱码、Nginx静态文件权限不足每个都能卡住半天。这套系统的部署我建议走Docker Compose编排把MySQL、后端、前端一次拉起。后端打个镜像很简单前端构建完直接让Nginxserve静态文件然后反向代理/api和/ws到后端8080端口。一个可用的nginx.conf关键片段如下server { listen 80; root /usr/share/nginx/html; # 前端路由回退到index.html location / { try_files $uri $uri/ /index.html; } # HTTP接口反向代理 location /api/ { proxy_pass http://backend:8080/api/; proxy_set_header Host $host; } # WebSocket反向代理需要单独配置升级头 location /ws { proxy_pass http://backend:8080/ws; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 300s; } }配置要点WebSocket的location /ws必须设置Upgrade和Connection头否则Nginx会断开长连接proxy_read_timeout从默认60秒改成300秒否则心跳间隔大于60秒时Nginx会主动掐断连接前端就会不断触发重连。这一项我在生产环境里吃过亏默认超时60秒心跳30秒一次理论上没问题但有一次网络抖动超过60秒没收到心跳连接就断了。验证这套系统是否真的可用我建议分三步走第一步打开两个浏览器窗口分别登录两个账号互加好友后互发消息确认实时性和顺序都正常第二步关掉其中一个窗口的网络等30秒后恢复确认离线消息能补发回来第三步按住F5刷新聊天页确认WebSocket能自动重连聊天记录能从历史接口拉回来。做完这三步这套系统的核心链路才算真正走通。有一件事让我印象特别深第一次部署时我用docker logs看后端日志一切正常但前端始终连不上WebSocket后来才发现是Nginx配置里漏了Upgrade头。从那以后每次部署这类前后端分离的项目我都强制走一遍“先看浏览器控制台、再看Nginx访问日志、最后看后端日志”的排查顺序先定位问题在哪一层再动手而不是盲猜配置。希望帮到你。本文还有配套的精品资源点击获取
简介一套基于Java SpringBoot与Vue全家桶构建的即时通讯管理系统完整代码包面向Java后端与Web前端学习者、毕业设计开发者解决了从零搭建在线聊天交友平台的需求。系统涵盖登录注册、会话列表、通讯录、好友管理、收藏、个人资料维护等模块消息发送支持文本、图片、文件并附带文件下载与图片预览功能前后端分离架构后端集成Mybatis与Redis可方便扩展。资源包共1889个文件约74.55MB以css、less、js、png、java、xml、class等为主其中前端样式与脚本、后端业务代码与配置文件分类清晰另附数据库备份及sql文件方便快速还原环境。目前已有619人学习下载适合需要完整项目参考或在此基础上做二次开发的读者。除源码外还提供部署答疑支持遇到环境配置或启动问题可联系作者获得协助。1. 即时通讯管理系统不是聊天玩具是前后端协同的完整工程很多人第一次拿到《即时通讯管理系统JavaSpringBootvueelementui》这个资源时第一反应是“这不就是个聊天软件嘛”。真跑一遍就会意识到聊天只是表面复杂度全在后端的会话管理、消息协议设计以及前端状态同步这几块上。这套毕设级的系统做的是典型的前后端分离工程SpringBoot负责用户、好友、会话和消息的持久化Vue3配合ElementUI负责界面与实时推送核心通信走WebSocket而不是简单的轮询。适合正在做Java方向毕设的学生、想补全实时通信这块短板的初级后端工程师以及需要给团队快速搭一个内部沟通工具的开发者。下面我按照从拿到代码到跑通部署的实际顺序把架构、后端、前端、避坑和部署逐层拆开。2. 架构拆解为什么是SpringBootVueElementUI以及九大模块怎么切2.1 这套技术栈的组合逻辑Java生态与前端工程化的碰撞选SpringBoot做后端最直接的理由是它对WebSocket和消息推送的支持已经非常成熟spring-boot-starter-websocket一个依赖就能把原生WebSocket端点注册起来不需要自己写复杂的握手逻辑。配合Spring Security或者简单的拦截器做登录鉴权比传统的ServletTomcat方案省掉一大截配置成本。前端选Vue3ElementUI是因为这套组合在“表单密集状态多变”的聊天场景里手感很好ElementUI的卡片、输入框、气泡样式开箱即用Vue的响应式数据模型天然适合渲染实时消息列表。我自己做技术选型时一直遵循一个原则毕设或者中小型内部项目优先选“整个团队都熟”的社区型技术栈而不是追求冷门框架带来的新鲜感。SpringBootVueElementUI恰好是简历上最常见、社区问答覆盖最全的组合遇到报错搜得到答案这比什么都重要。2.2 整体模块划分从网关到消息通道拆出九个关键模块这套系统的后台拆法大致是这样网关层负责路由与登录鉴权用户模块管注册登录和头像资料好友模块管添加好友、好友列表和好友申请会话模块管单聊和群聊会话的创建消息模块管消息的发送、接收和离线补发WebSocket模块管长连接的心跳和推送通知模块管系统公告和好友申请提醒文件模块管聊天图片和附件的上传最后还有一个数据统计模块给管理端看在线人数和消息量。这个九模块的划分不是拍脑袋而是顺着“用户发起行为→经过会话→落到消息→推送对端→必要时持久化”这条链路拆的。做毕设答辩时面试官或者老师最喜欢问的一句话是“你的数据库为什么这么设计”如果你能顺着这条链路把模块边界讲清楚比背一百遍概念都有说服力。每个模块之间通过Service接口互相调用WebSocket模块只依赖消息模块的接口不直接操作Mapper这样后面加离线消息功能时不用改动连接层。2.3 数据模型设计用户、好友、会话、消息四张核心表这套系统的核心表结构不复杂但每一张都有讲究。用户表里除了基本的id、username、password还多两个容易忽略的字段online_status和last_login_time。online_status不是给前端轮询用的而是为了保证WebSocket重连时能快速恢复会话状态last_login_time直接决定“最近一次在线”这个状态的展示去掉它的话好友列表里的在线状态就只能靠实时心跳硬撑一旦用户断网又没来得及发离线包状态就会错乱。好友表用的是“双向冗余”设计A加B时插入两条记录(A,B)和(B,A)都写进去查询时直接查“我是左端或右端”即可避免每次都要做一次双向匹配的联合查询。会话表里只有id、session_type和last_message_timesession_type用0单聊、1群聊区分不存具体成员成员关系单独放到会话成员表。消息表则单独存session_id、from_user、message_type、content、create_time和statusstatus字段的值0未读、1已读、2已撤回。这四张表的关系可以这样记用户和好友是社交关系会话是聊天容器消息是用户产生的具体内容。当初我自己写第一版时贪方便把消息直接挂到用户表下面结果群聊场景没法做“按会话拉历史记录”后来才补了会话成员表这是一笔花了两个晚上才还上的技术债。表名核心字段设计要点userid, username, password, online_status, last_login_timeonline_status配合WebSocket会话恢复不依赖前端轮询frienduser_id, friend_id, create_time双向冗余插入查询免去双向匹配sessionid, session_type, last_message_timesession_type区分单聊群聊成员关系不落在此表session_membersession_id, user_id, unread_count每用户记录未读数撑起聊天列表的红色角标messageid, session_id, from_user, message_type, content, statusstatus支持未读、已读、撤回三种状态提示password字段不要存明文毕设答辩时“密码是否加密存储”是高频问题建议用BCrypt做哈希Spring Security自带的BCryptPasswordEncoder可以直接用。3. 后端实战WebSocket会话管理、统一消息协议与离线补发的三块硬骨头3.1 会话管理用ConcurrentHashMap维护在线用户而不是数据库轮询很多教程喜欢把在线用户塞进数据库然后让前端定时轮询状态这在小规模演示里能跑但并发一上来数据库查询就成瓶颈了。常见做法是后端启动时维护一个ConcurrentHashMapString, WebSocketSessionkey是用户IDvalue是WebSocket会话对象。这样查询在线状态只需要一次内存查找不用碰数据库。这个Map要放在一个独立的会话管理类里用静态方法暴露方便其他Service直接调用。下面是一个标准的SpringBoot WebSocket配置类Configuration EnableWebSocket public class WebSocketConfig implements WebSocketConfigurer { // 把自定义的Handler注册到 /ws 端点 Override public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { registry.addHandler(new ChatWebSocketHandler(), /ws) .setAllowedOrigins(*); // 跨域放开生产环境按域名收窄 } }这里的/ws就是前端连接WebSocket的路径setAllowedOrigins(*)是开发阶段用来解决跨域握手失败的手段部署上线后建议改成具体域名否则任何网站都能连你的长连接安全隐患不小。注册Handler之后核心逻辑都写在ChatWebSocketHandler里它需要重写afterConnectionEstablished、handleTextMessage、handleTransportError和afterConnectionClosed这四个方法。afterConnectionEstablished里做的事就是取出握手时带的userId参数把会话对象放进MapafterConnectionClosed则负责从Map里移除用户同时把离线时间写回数据库。Component public class ChatWebSocketHandler extends TextWebSocketHandler { // 全局在线会话表key为userIdvalue为WebSocketSession private static final ConcurrentHashMapString, WebSocketSession ONLINE_SESSIONS new ConcurrentHashMap(); Override public void afterConnectionEstablished(WebSocketSession session) throws Exception { String userId (String) session.getAttributes().get(userId); ONLINE_SESSIONS.put(userId, session); // 用户变为在线状态供好友列表实时展示 userService.updateOnlineStatus(userId, true); } Override protected void handleTextMessage(WebSocketSession session, TextMessage message) throws Exception { // 解析统一消息体分发到对应会话 ChatMessage chatMessage JSON.parseObject(message.getPayload(), ChatMessage.class); messageService.sendMessage(chatMessage); } Override public void afterConnectionClosed(WebSocketSession session, CloseStatus status) { String userId (String) session.getAttributes().get(userId); ONLINE_SESSIONS.remove(userId); userService.updateOnlineStatus(userId, false); } }逻辑说明afterConnectionEstablished在握手成功后立刻执行把userId作为Map的key存进去handleTextMessage收到任何前端消息时先解析成统一消息体再交给messageService.sendMessage去处理落库和推送给对方。这样WebSocket层不直接操作数据库保持职责单一。参数上要注意session.getAttributes()里的userId需要在握手时通过HandshakeInterceptor提前塞进去否则这里拿不到。3.2 消息协议统一的消息体是避免“各写各的”的唯一出路前后端通信最忌讳的是每个接口各传各的字段今天传content明天传messageContent前端解析逻辑就得跟着写两套。这套系统里用一个统一的消息实体来兜底用type字段区分单聊、群聊和系统通知。实际项目里我会把消息类型写成枚举而不是用魔法数字这样后端判断逻辑可读性更强前端也能直接用枚举值做渲染分支。public class ChatMessage { private String fromUserId; // 发送方ID private String toUserId; // 接收方ID单聊时必填 private String sessionId; // 会话ID决定消息归属哪个会话 private Integer messageType; // 0文本 1图片 2文件 3系统通知 private String content; // 消息内容或文件URL private Long timestamp; // 客户端发送时间用于排序 private Integer chatType; // 0单聊 1群聊 }字段说明sessionId是核心关联键后端收到消息后直接按它找到会话成员决定推送给哪几个人timestamp用客户端时间而不是服务器时间是为了避免消息列表出现“后发先至”的视觉错乱chatType和sessionId其实信息有重叠但保留它可以让前端免一次查会话表就能判断渲染形式。消息发送的核心函数大概长下面这样public void sendMessage(ChatMessage chatMessage) { // 1. 落库status默认0未读 messageMapper.insert(chatMessage); // 2. 判断是单聊还是群聊 if (chatMessage.getChatType() 0) { // 单聊直接找对方在线会话推送 WebSocketSession toSession ONLINE_SESSIONS.get(chatMessage.getToUserId()); if (toSession ! null toSession.isOpen()) { toSession.sendMessage(new TextMessage(JSON.toJSONString(chatMessage))); } } else { // 群聊遍历会话成员表逐个推送 ListString memberIds sessionMemberMapper.listMemberIds(chatMessage.getSessionId()); for (String memberId : memberIds) { if (memberId.equals(chatMessage.getFromUserId())) continue; WebSocketSession memberSession ONLINE_SESSIONS.get(memberId); if (memberSession ! null memberSession.isOpen()) { memberSession.sendMessage(new TextMessage(JSON.toJSONString(chatMessage))); } } } }这段逻辑说明了两个关键点第一落库一定在推送之前这样即使推送失败消息也不会丢下次上线可以补拉第二单聊和群聊的推送路径分开单聊查一次Map群聊查一次数据库成员表避免群聊场景下反复做无效查询。这里用ONLINE_SESSIONS.get(toUserId)返回null就代表对方不在线不走异常分支直接靠离线消息机制兜底。3.3 心跳与离线补发断线重连的兜底方案与数据库补发逻辑WebSocket长连接在真实网络环境里不是永生的公司WiFi切换、手机锁屏、路由器休眠都会让连接变成“假死”状态——TCP层面还连着但实际已经收不到数据了。这套系统的心跳策略是前端每30秒发一个ping类型的消息后端收到后回一个pong后端同时维护一个lastHeartbeatTime超过90秒没收到心跳就主动关闭旧连接。这里有个容易翻车的细节心跳消息不能走handleTextMessage的正常分发路径否则会在数据库里落一堆无意义记录要在协议里单独定义HEARTBEAT类型在处理器最前面拦一下。离线消息补发的逻辑我一般这么做用户上线时拉取status 0且toUserId 当前用户的消息把这些消息通过WebSocket推给前端然后把状态改为已读。关键在于拉取范围要限定在会话内而不是全表拉取否则消息量大时一次上线会卡顿半天。public void sendOfflineMessages(String userId) { // 只拉最近7天的未读消息避免历史消息堆积 ListChatMessage offlineMessages messageMapper.listOfflineMessages(userId, 7); WebSocketSession session ONLINE_SESSIONS.get(userId); if (session null || !session.isOpen()) { return; } for (ChatMessage message : offlineMessages) { session.sendMessage(new TextMessage(JSON.toJSONString(message))); } // 批量更新为已读 messageMapper.batchMarkRead(offlineMessages); }这段代码的执行顺序很讲究先拉未读列表再推送最后更新已读状态。如果先更新已读再推送推送途中连接断开消息就彻底丢了用户什么都看不到。listOfflineMessages(userId, 7)里的7是时间窗口参数可按实际消息量调整如果场景要求全部历史可查这个参数可以去掉但建议额外加一个分页参数防止一次性拉出几千条数据把浏览器卡死。4. 前端实战Vue3ElementUI的消息UI层怎么和WebSocket握手4.1 前端工程初始化与路由设计登录、会话列表、聊天窗口三层跳转前端项目用Vite构建Vue3的script setup语法写起来比Options API简洁不少。路由设计走三级结构/login登录页、/chat会话列表页、/chat/:sessionId聊天窗口页。这里有一个细节值得注意聊天窗口页不应该真的让用户跳转路由而是应该通过点击会话列表项来更新当前激活的会话ID因为路由切换会导致组件重渲染WebSocket连接就可能断掉。所以/chat/:sessionId用同一个组件通过watch监听route.params.sessionId的变化来切换聊天对象。路由配置里还需要加一个全局前置守卫检查本地有没有token没有就直接踢到登录页router.beforeEach((to, from, next) { const token localStorage.getItem(token); if (to.path ! /login !token) { next(/login); } else { next(); } });这段守卫的逻辑很简单放行的前提是“要么去登录页要么带着token”。实际项目里我还会配合ElementUI的ElMessage弹窗提示“登录已过期请重新登录”但为了不打断演示流程守卫里只做跳转不做弹窗。这里提一个常见误用把token放到sessionStorage里关浏览器就丢用户刷新页面就掉线毕设演示时容易翻车建议直接用localStorage持久化。4.2 WebSocket客户端封装连接、订阅、重连与Token鉴权前端不能每个组件都裸写new WebSocket()要封装成一个全局单例。我常用的封装方式是把WebSocket实例放在一个ws.js模块里导出connectWebSocket(userId, token)和sendMessage(msg)两个函数。连接时在URL上拼userId和token两个参数后端握手拦截器从query里取出来校验身份。心跳用setInterval定时发ping每次收到服务端消息就重置一个看门狗计时器——这是我从实际失败里学到的只发心跳不看回应等于没发连接断了心跳还在傻傻继续白费带宽。断线重连要加指数退避第一次1秒、第二次2秒、第三次4秒最大30秒避免服务端还没恢复时客户端疯狂重连把服务打挂。// src/utils/ws.js let ws null; let heartbeatTimer null; let reconnectCount 0; export function connectWebSocket(userId, token) { const protocol window.location.protocol https: ? wss:// : ws://; const url ${protocol}${window.location.host}/ws?userId${userId}token${token}; ws new WebSocket(url); ws.onopen () { console.log(WebSocket连接成功); reconnectCount 0; startHeartbeat(); }; ws.onclose () { stopHeartbeat(); // 指数退避重连 const delay Math.min(1000 * Math.pow(2, reconnectCount), 30000); reconnectCount; setTimeout(() connectWebSocket(userId, token), delay); }; ws.onmessage (event) { const msg JSON.parse(event.data); // 外部通过事件订阅接收不在这个文件里处理业务 window.dispatchEvent(new CustomEvent(ws-message, { detail: msg })); }; } function startHeartbeat() { heartbeatTimer setInterval(() { if (ws ws.readyState WebSocket.OPEN) { ws.send(JSON.stringify({ type: HEARTBEAT })); } }, 30000); } function stopHeartbeat() { clearInterval(heartbeatTimer); heartbeatTimer null; } export function sendMessage(msg) { if (ws ws.readyState WebSocket.OPEN) { ws.send(JSON.stringify(msg)); } else { throw new Error(WebSocket未连接); } }参数说明userId和token拼在query上是为了让后端在握手拦截器里做鉴权不需要额外的鉴权报文心跳间隔30秒是跟后端90秒超时时间对应的留了3倍余量避免网络抖动误杀。window.dispatchEvent这个自定义事件是组件解耦的关键聊天窗口组件只监听ws-message不需要知道WebSocket内部怎么运作。每次连接成功后重置reconnectCount防止旧连接的重连计数器污染新连接的重连节奏。4.3 聊天窗口消息列表渲染、滚动定位与发送状态机聊天窗口是前端最容易被细节绊倒的地方。消息列表用v-for渲染每条消息根据fromUserId是否等于当前用户判断左右对齐然后用ElementUI的el-card或者自绘气泡展示。滚动定位有一个血泪经验消息渲染完成后滚动条要手动拉到最底部而且必须等到nextTick之后再执行否则新消息还没渲染进DOMscrollTop怎么设都白搭。发送消息的状态机也值得说用户点击发送后先把消息push进本地数组再通过sendMessage发给后端等后端推送回确认消息时把本地消息状态从“发送中”改成“已发送”。这套“先入为主、后确认”的策略能极大改善聊天手感用户点了发送立刻在界面上看到自己的消息不用等网络往返。script setup import { ref, nextTick, watch } from vue; import { useRoute } from vue-router; import { sendMessage } from /utils/ws; const route useRoute(); const messageList ref([]); const chatWindowRef ref(null); const inputContent ref(); // 监听路由参数切换会话 watch(() route.params.sessionId, async (newSessionId) { const history await fetchHistory(newSessionId); messageList.value history; scrollToBottom(); }); function handleSend() { const content inputContent.value.trim(); if (!content) return; // 本地先行追加标记status为0表示发送中 messageList.value.push({ fromUserId: currentUserId, content, status: 0, timestamp: Date.now() }); scrollToBottom(); // 真正的WebSocket发送 sendMessage({ fromUserId: currentUserId, sessionId: route.params.sessionId, chatType: route.params.chatType, content }); inputContent.value ; } async function scrollToBottom() { await nextTick(); chatWindowRef.value.scrollTop chatWindowRef.value.scrollHeight; } /script这段代码的核心思路是“本地乐观更新”先把用户输入渲染到界面上再走WebSocket发送视觉上零延迟。status字段在后续收到服务端回执时更新为1前端就能根据状态在消息右下角显示“发送中”或“已发送”的小字。scrollToBottom里的nextTick是硬性依赖少了它滚动条永远停在旧位置。在真实项目中还需要监听ws-message事件把对方发来的新消息追加到messageList同样调用scrollToBottom这样对方的话才会实时出现在屏幕上。5. 避坑记录跑通这套即时通讯系统后我补上的五个重要缺口5.1 跨域导致的WebSocket握手失败现象前端new WebSocket之后永远停在CONNECTING状态控制台报403 Forbidden后端日志完全没有握手请求进来。 原因前端开发服务器跑在localhost:5173后端接口在localhost:8080WebSocket握手请求的Origin头不匹配被Tomcat默认的跨域策略拦下。 解决在后端registerWebSocketHandlers里调setAllowedOrigins(*)开发期放开生产环境改成前端实际访问的域名。另外要注意setAllowedOrigins只能管住WebSocket握手HTTP接口的跨域还得单独配CorsFilter两码事。5.2 消息重复或乱序显示现象同一批历史消息拉取两次聊天窗口里出现重复气泡多设备同时登录时消息顺序忽前忽后。 原因离线消息补发和主动拉历史记录没有做去重前端拿timestamp做排序但客户端和服务器时间有偏差。 解决前端以timestamp为排序键同时用后端返回的messageId做去重渲染前先过滤掉已存在的ID。时间偏差问题靠“服务器时间覆盖”拉取历史记录时返回一次服务器当前时间前端用它校准本地时钟偏移量排序前先加偏移量再排。5.3 Vue打包部署到服务器后白屏现象本地npm run dev一切正常npm run build之后把dist放到Nginx里打开是空白页控制台报资源404。 原因Vite默认base是/打包出来的index.html里引用的是/assets/xxx.js绝对路径部署到子目录或者经过一层转发后路径就对不上了。 解决在vite.config.js里设base: ./用相对路径引用资源。注意改了base之后Vue Router的createWebHistory也要改成createWebHashHistory否则手动刷新页面会404。// vite.config.js export default defineConfig({ base: ./, // 相对路径适配子目录部署 plugins: [vue()], server: { host: 0.0.0.0, port: 5173 } });参数说明base: ./让打包后的CSS和JS都走相对路径index.html放在任何一级目录都能被正确加载createWebHashHistory让路由以#开头刷新时Nginx不会去找/chat这个不存在的真实文件直接回退到index.html。如果部署在域名根路径这两项可以不改但在毕设演示这种“随时可能换个文件夹跑”的场景里改掉更放心。5.4 长时间挂着页面消息突然发不出去现象页面挂了一个小时后再点发送没反应控制台没有报错WebSocket状态显示OPEN。 原因这是经典的“假死连接”。空闲期间路由器NAT表项过期但TCP连接没有收到关闭通知浏览器和服务器都不知道连接已死。 解决前端心跳不能只发ping还要监听onclose事件后端90秒没收到心跳就主动close。前端在onclose里触发重连逻辑重连成功后reconnectCount归零。另外发送消息时加一个readyState ! WebSocket.OPEN的兜底判断触发重连而不是直接抛出异常。5.5 原生WebSocket和STOMP之间的选择现象部分教程推荐用STOMP协议代码写起来确实更简洁但遇到私有协议定制时反而处处受制。 原因STOMP在SpringBoot里用起来有一套自己的订阅模型适合“多房间广播”场景但即时通讯这种“点对点精准推送自定义消息类型”的落地下STOMP的convertAndSendToUser反而把会话管理逻辑藏到了框架黑匣子里出问题时排查链路长。 解决这个系统选择原生WebSocket 自定义JSON协议。理由有三一是依赖极少不需要额外引入spring-messaging和STOMP相关包二是会话管理掌握在自己手里单个用户的连接状态随时可查三是消息协议自己定义前后端都清晰。如果你的场景是标准的“客户端订阅某个频道”用STOMP没问题但如果是点对点聊天原生WebSocket反而更可控。6. 部署与验证用Docker Compose把前后端打包成一个可演示的工程部署这块我踩过不少坑OpenJDK版本不匹配、MySQL编码不对导致中文乱码、Nginx静态文件权限不足每个都能卡住半天。这套系统的部署我建议走Docker Compose编排把MySQL、后端、前端一次拉起。后端打个镜像很简单前端构建完直接让Nginxserve静态文件然后反向代理/api和/ws到后端8080端口。一个可用的nginx.conf关键片段如下server { listen 80; root /usr/share/nginx/html; # 前端路由回退到index.html location / { try_files $uri $uri/ /index.html; } # HTTP接口反向代理 location /api/ { proxy_pass http://backend:8080/api/; proxy_set_header Host $host; } # WebSocket反向代理需要单独配置升级头 location /ws { proxy_pass http://backend:8080/ws; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 300s; } }配置要点WebSocket的location /ws必须设置Upgrade和Connection头否则Nginx会断开长连接proxy_read_timeout从默认60秒改成300秒否则心跳间隔大于60秒时Nginx会主动掐断连接前端就会不断触发重连。这一项我在生产环境里吃过亏默认超时60秒心跳30秒一次理论上没问题但有一次网络抖动超过60秒没收到心跳连接就断了。验证这套系统是否真的可用我建议分三步走第一步打开两个浏览器窗口分别登录两个账号互加好友后互发消息确认实时性和顺序都正常第二步关掉其中一个窗口的网络等30秒后恢复确认离线消息能补发回来第三步按住F5刷新聊天页确认WebSocket能自动重连聊天记录能从历史接口拉回来。做完这三步这套系统的核心链路才算真正走通。有一件事让我印象特别深第一次部署时我用docker logs看后端日志一切正常但前端始终连不上WebSocket后来才发现是Nginx配置里漏了Upgrade头。从那以后每次部署这类前后端分离的项目我都强制走一遍“先看浏览器控制台、再看Nginx访问日志、最后看后端日志”的排查顺序先定位问题在哪一层再动手而不是盲猜配置。希望帮到你。本文还有配套的精品资源点击获取
