Spring Boot实战：Bot管理CRUD与WebSocket集成全解析-北京尧图网络

1. 项目整体链路Bot管理、匹配系统与WebSocket三者怎么衔接1.1 这个项目现在做到哪一步了这个系列做到第十二篇项目已经从最基础的“Hello Spring Boot”走到现在这个节点用户注册登录、JWT鉴权、后台管理这些能力都已经就位。现在要面对的问题很实际——怎么让普通用户真正用起来。在Bot对战平台里用户必须能创建自己的Bot、修改代码、删除旧的然后才能进入匹配池参与对战。所以这一篇的核心工作有两块第一把前端页面Bot的CURD功能完整跑通第二为匹配系统准备通信基础也就是集成WebSocket。这两块看似独立实际上是一条链路上的两个环节。没有Bot管理匹配系统不知道该拉取哪个Bot进入对局没有WebSocket匹配成功的结果无法实时推送到用户页面。很多同学会问Bot的CURD用普通HTTP接口就好为什么还要专门集成WebSocket因为对战平台的“匹配中—匹配成功”这个过程需要服务端主动推送HTTP的请求响应模型在这里非常别扭。WebSocket能把服务端和客户端之间的通道变成双向的、长久的连接匹配线程一旦发现两个玩家可以配对就能立刻通知双方。所以这一篇的内容可以理解成先把基础数据入口建好再把实时通信管道铺通匹配系统本身放在下一阶段细化。1.2 Bot、匹配池、WebSocket三者的数据流我习惯在动手编码前先把数据流画清楚。用户在前端填写Bot名称、描述、代码点击保存后后端把这个Bot写入数据库。随后用户进入匹配页选中一个Bot点击“开始匹配”前端通过WebSocket发送一条start_match消息后端取出这台Bot构造一个匹配请求放进匹配池。匹配线程负责扫描匹配池当两个用户满足配对条件时后端调用WebSocketSession把match_found消息分别推给两个用户。这里有一个关键点Bot的CURD操作频率低、实时性要求不高走HTTP完全足够但匹配状态必须走WebSocket因为匹配成功是后端在任意时刻主动发生的事件前端无法预测何时发起请求。我们不可能让前端每秒钟轮询一次“我匹配到了吗”那样既浪费资源延迟又高。所以这一篇里WebSocket承担的是“服务端主动推送”职责Bot的HTTP接口负责“用户主动读写”职责两者通过userId和botId关联起来。2. 后端Bot CRUD接口表结构、Service权限校验与统一返回2.1 Bot表设计需要哪些字段才够用先设计表结构。我的bot表包含这些字段id主键自增user_id记录归属用户title保存Bot名称description保存描述content保存Bot代码rating保存评分另外加上create_time和update_time。为什么要有rating因为后面做匹配系统时要对玩家Bot的实力进行匹配如果现在不加这个字段到时候还要改表结构不如一次到位。建表SQL我直接贴在下面你可以复制到MySQL里执行CREATE TABLE bot ( id INT AUTO_INCREMENT PRIMARY KEY, user_id INT NOT NULL COMMENT 所属用户ID, title VARCHAR(100) NOT NULL COMMENT Bot名称, description VARCHAR(255) DEFAULT COMMENT Bot描述, content TEXT COMMENT Bot代码, rating INT DEFAULT 1500 COMMENT 初始评分, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, INDEX idx_user_id (user_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里有一个容易忽略的细节content字段类型用TEXT不要用VARCHAR(255)。用户写的Bot代码动辄几百行255的容量完全不够。建立user_id索引也很关键因为每次查询“当前用户的所有Bot”都靠这个字段过滤如果没有索引数据量大了以后查询会明显变慢。2.2 实体类与MyBatis-Plus使用细节Java实体类和表结构一一对应。我项目里用的是MyBatis-Plus实体类加上TableName(bot)和TableId(type IdType.AUTO)即可。时间字段用LocalDateTime承接JSON序列化时在application.yml里统一配置格式spring: jackson: date-format: yyyy-MM-dd HH:mm:ss time-zone: GMT8不配置的话前端拿到的create_time可能是一长串数组或者时间戳处理起来很痛苦。MyBatis-Plus的BaseMapper已经提供了insert、updateById、deleteById、selectList这些方法Bot这种简单增删改查不需要手写XML或注解SQL。但你要理解框架只帮你省SQL不帮你省业务校验。真正容易出错的地方在于哪些字段能由前端传入哪些字段必须由后端赋值这个边界必须清楚。2.3 Controller层API设计为什么统一用POST这一版的Bot接口我全部用POST没有刻意拆PUT/DELETE。原因是前端封装请求时统一传JSON对象后端接收统一用RequestBody代码写起来最简洁。REST风格作为理想没问题但在实际项目中我宁愿牺牲一点“学院派规范”来换取接口的简单统一。接口设计如下功能路径请求参数说明获取当前用户Bot列表POST /api/bot/list空返回当前登录用户的所有Bot创建BotPOST /api/bot/createtitle,description,content新建一个Bot更新BotPOST /api/bot/updateid,title,description,content修改自己的Bot删除BotPOST /api/bot/removeid删除自己的BotController层的代码很薄核心逻辑放在Service。创建Bot时userId绝对不能从前端接收而是从当前登录上下文里取PostMapping(/create) public RespString create(RequestBody Bot bot) { User user UserContext.getCurrentUser(); bot.setUserId(user.getId()); bot.setRating(1500); botService.save(bot); return Resp.success(创建成功); }用户上下文从哪来是JWT过滤器在解析token后放入ThreadLocal的。前端传userId容易导致越权问题比如我登录A账号传一个userId为2就能给B账号创建Bot。这种接口安全漏洞在真实项目中非常常见写代码时务必把这个口子堵住。2.4 Service权限校验修改/删除只允许操作自己的Bot更新和删除比创建多一道“归属校验”。流程是先根据id从数据库查出Bot再判断bot.getUserId()和当前登录用户是否一致。不一致直接抛业务异常前端统一弹出“无权操作”的提示。我踩过两个坑都损失了不少调试时间。第一次是更新接口漏了校验用A账号把B账号的Bot标题改了个遍还好是测试环境。第二次是删除时直接removeById(id)没有先查一下记录是否存在也没有校验归属结果前端显示“删除成功”但数据库里根本没删掉数据。正确写法应该把这段逻辑抽成一个私有方法先查询再校验再修改private Bot getOwnedBotById(Integer id) { Bot bot botMapper.selectById(id); if (bot null) { throw new BusinessException(Bot不存在); } if (!bot.getUserId().equals(UserContext.getCurrentUser().getId())) { throw new BusinessException(无权操作该Bot); } return bot; }这样三个接口都能复用。记住一个原则凡是对资源进行修改删除后端一定要做二次确认不能信任前端传来的id。3. 前端页面Bot CURD实操列表、表单、删除确认3.1 前端技术选型为什么不写服务端模板而用Vue到了Bot管理页面我建议直接选择Vue或React这类前端框架而不是继续用Thymeleaf套页面。原因很简单这个页面的交互密度比较高有列表渲染、弹窗复用、表单校验、WebSocket状态绑定用服务端模板做非常别扭代码很容易变成一堆拼接字符串和DOM操作。我的前端页面用的是Vue 3加Element Plus。页面结构分为三块顶部是标题和“创建Bot”按钮中间是Bot列表表格包含名称、描述、评分、创建时间和操作按钮弹窗是新增和编辑共用的Dialog内部有三个表单字段——标题、描述、代码。整体不算复杂但涉及到的知识足够你理解前后端协作的基础模式。为什么前后端分离也是这类项目的推荐路线因为后续匹配结果推送、对局列表刷新这些功能前端的状态管理会越来越多。与其在Spring Boot里塞一堆前端代码不如让前端独立开发、独立部署后端只提供接口和WebSocket。工程结构清晰团队协作也方便。3.2 列表加载数据库查什么前端就显示什么页面一加载前端调用POST /api/bot/list获取当前用户的所有Bot。这个接口返回的是一个数组我建议先不做分页因为单个用户创建的Bot数量一般不会很多最多几十条全部渲染没问题。等以后加上“商城式Bot分享”或“公共Bot库”再考虑分页也不迟。前端拿到数组后用el-table渲染。这里有一个体验细节update_time字段如果后端已经格式化成yyyy-MM-dd HH:mm:ss前端直接显示。如果后端返回的是时间戳前端要用dayjs或moment格式化。不要在这里偷懒直接显示一串数字会让页面看起来非常不专业。操作列放两个按钮“编辑”和“删除”。编辑按钮打开Dialog回填当前行数据删除按钮弹出确认框。列表刷新时我的习惯是保留当前滚动位置和选中状态不要一刷新就跳回顶部。用户可能在列表中间操作刷新后跳到顶部会让人很困惑。3.3 创建和编辑复用同一个Dialog的技巧新建和编辑共用一个Dialog用一个isEdit标记区分场景。Dialog内部是一个el-form三个字段title、description、content。代码文本域最少12行高度否则Bot代码一长就很难编辑。保存时前端先做一次校验标题和代码不能为空描述可以为空。这个校验能过滤掉大部分无效请求减轻后端压力。校验通过后根据isEdit决定调/create还是/update接口提交成功后关闭Dialog并调用列表刷新接口。这里我踩过一个小坑新建时表单是干净的编辑时表单已经回填了旧数据如果用户把标题清空并点保存前端校验能拦住但如果用户把描述清空校验拦不住后端也允许空字符串。这不是bug但要考虑是否要提示用户。我的做法是描述允许为空因为有些Bot确实不需要描述。3.4 删除确认前端二次确认加上后端归属校验删除按钮必须加二次确认这是防止误删的底线。Element Plus的ElMessageBox.confirm用起来很简单用户点“确定”后才调删除接口。删除成功后有两种刷新方式一是从当前列表里移除那一行二是重新调/list刷新全量列表。我推荐后者。为什么推荐全量刷新因为删除这个操作背后可能还有后端连带的清理逻辑比如删除Bot关联的匹配记录前端无法知道还有没有其他数据变化。重新拉一次列表虽然多一次请求但能保证页面显示和数据库完全一致。我在实际项目中见过只从列表移除记录、之后刷新页面记录又出现的诡异情况就是删除接口没成功后前端误以为成功导致的。4. 匹配系统准备匹配池设计、队列实现与实时通信选型4.1 匹配池里放什么不是放Bot而是放匹配请求匹配系统的核心是一个“匹配池”。很多新手会直接把Bot对象放进匹配池这不是最优的做法。因为一个用户可能创建多个Bot用户在前端选中哪个Bot参与匹配后端必须把这个关联关系记录下来。匹配池里真正应该放的是“匹配请求”一条请求代表“某个用户用哪个Bot正在等待对局”。我设计了一个MatchRequest对象字段包括public class MatchRequest { private Integer userId; private Integer botId; private Integer rating; private Long createTime; }userId是玩家身份botId是Bot身份rating是用于后续匹配算法的评分createTime用于超时处理。当匹配线程从队列里取出两个或多个请求后根据评分差、段位区间拼接对局。后续如果要取消匹配也能根据userId从池子里移除对应请求。这个设计是匹配系统最基础的地基地基歪了后面写什么都会别扭。4.2 匹配队列的基本实现安全、不阻塞主线程匹配请求肯定不止一个线程在操作。前端通过WebSocket发送start_match消息后后端某个线程负责把请求加入队列另一边匹配线程一直扫描队列准备配对。如果队列用普通的ArrayList两个线程同时修改会抛ConcurrentModificationException。我推荐用ConcurrentLinkedQueue这是一个线程安全的无界队列入队和出队都是非阻塞的非常适合这个场景private final ConcurrentLinkedQueueMatchRequest matchQueue new ConcurrentLinkedQueue();匹配线程需要一个死循环但循环里不能每毫秒都跑否则CPU占用会很难看。我的策略是每500毫秒检查一次队列如果队列长度大于等于2就尝试取出请求进行匹配。这个延迟对用户几乎无感却能大幅降低CPU开销。等匹配到了两人后在同一个同步块里完成出队、发送WebSocket消息的动作防止重复匹配。4.3 为什么选WebSocket而不是HTTP轮询匹配场景最典型的特征就是“服务端主动”。前端不知道什么时候匹配成功也许是1秒后也许是1分钟后。如果用HTTP轮询前端每2秒请求一次“我匹配到了吗”大部分请求都是空响应既浪费带宽又增加服务器压力匹配成功的那一刻用户可能还要多等一个轮询周期才能看到结果。WebSocket的思路完全不同。前端一旦打开WebSocket连接就和服务端保持一条长期存在的双向通道。匹配线程发现配对成功后后端直接通过这条通道把match_found推给用户。从匹配成功到用户收到通知延迟就是匹配线程的扫描间隔通常不到500毫秒。而且用户同时还能收到“已进入匹配队列”的即时回执体验远好于轮询。这也是为什么这一篇必须先把WebSocket集成好否则再好的匹配算法也送不到用户面前。5. Spring Boot集成WebSocket注册、握手鉴权与消息推送5.1 引入依赖与YML配置Spring Boot其实只要一个starterSpring Boot集成WebSocket非常顺滑第一步是引入依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-websocket/artifactId /dependency很多同学会疑惑application.yml里要不要单独配一个WebSocket的配置项其实Spring Boot的WebSocket不需要专门的连接配置只需要配置类注册端点即可。如果你希望把端点路径、允许跨域地址做成可配置项可以用自定义属性注入app: websocket: path: /api/websocket allowed-origins: http://localhost:5173,http://localhost:3000然后配置类里用Value(${app.websocket.path})注入。这样不同环境可以通过配置文件调整不用改代码。5.2 注册WebSocket端点与跨域处理创建一个配置类实现WebSocketConfigurer重写registerWebSocketHandlers。这里要注册处理器、拦截器和允许跨域来源Configuration EnableWebSocket public class WebSocketConfig implements WebSocketConfigurer { Value(${app.websocket.path:/api/websocket}) private String websocketPath; Value(${app.websocket.allowed-origins:}) private String allowedOrigins; Override public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { registry.addHandler(new MatchWebSocketHandler(), websocketPath) .addInterceptors(new AuthHandshakeInterceptor()) .setAllowedOrigins(allowedOrigins.split(,)); } }开发环境我通常把allowed-origins设为*方便调试。但生产环境一定写死来源否则任意第三方网站都能连上这个WebSocket接口配合你后端推送逻辑很容易被刷消息。如果你用的是Spring Boot 3.xsetAllowedOrigins(*)对带凭证的请求可能不生效可以考虑setAllowedOriginPatterns(*)但要清楚两者的差异。5.3 握手拦截器从URL参数解析JWT Token浏览器WebSocket API有个限制创建连接时不能像普通HTTP请求那样自定义请求头。所以最常见的鉴权方式是URL参数携带tokenlet ws new WebSocket(ws://localhost:8080/api/websocket?token token);后端在握手阶段拦截请求解析token把userId放入attributes。等连接建立后处理器就能从这个Map里拿到当前连接对应的用户身份public class AuthHandshakeInterceptor implements HandshakeInterceptor { Override public boolean beforeHandshake(ServerHttpRequest request, ServerHttpResponse response, WebSocketHandler wsHandler, MapString, Object attributes) { String query request.getURI().getQuery(); if (query null || !query.contains(token)) { return false; } String token query.split(token)[1]; Integer userId JwtUtil.getUserId(token); if (userId null) { return false; } attributes.put(userId, userId); return true; } Override public void afterHandshake(ServerHttpRequest request, ServerHttpResponse response, WebSocketHandler wsHandler, Exception exception) { // 握手成功后的回调一般可为空 } }注意解析token时不能只拆一个split就完事因为URL后面可能还有其他参数。更稳妥的做法是用UriComponentsBuilder拿到参数。这里token过期、签名错误、找不到用户id都直接返回false拒绝握手。我之前有一版解析失败时没拦截结果前端页面显示连接已建立后端却不知道这个连接属于谁推送消息时全部落空排查了整整半天。5.4 消息处理器收发消息与在线用户管理核心处理器继承TextWebSocketHandler。定义一个线程安全的在线用户Mapkey是userIdvalue是WebSocketSessionprivate final ConcurrentHashMapInteger, WebSocketSession onlineSessions new ConcurrentHashMap();连接建立时从attributes里取出userId存入Map连接关闭时从Map移除。handleTextMessage方法负责处理前端发来的消息。约定消息格式为JSON{type: start_match, data: {bot_id: 1}}解析出type后分派到不同的业务方法。匹配相关消息统一交给匹配服务处理心跳消息直接回pong。注意不要在handleTextMessage里做太重的数据库操作比如同步查询Bot代码并即时编译这样会阻塞WebSocket的消息线程。建议把耗时操作丢进线程池或者消息队列保持连接的轻快。5.5 服务端主动推送匹配结果如何发给指定用户匹配成功时需要向两个用户发送消息。由于服务端保存了onlineSessions按userId就能找到对应的Sessionpublic void sendMessageToUser(Integer userId, String message) { WebSocketSession session onlineSessions.get(userId); if (session null || !session.isOpen()) { return; } try { session.sendMessage(new TextMessage(message)); } catch (Exception e) { onlineSessions.remove(userId); } }这里有个很重要的判断发送前必须检查isOpen()。匹配线程和用户连接可能不在同一个生命周期里玩家也许已经关闭了浏览器但匹配线程刚扫描到他此时Session是关闭状态直接sendMessage会抛IllegalStateException。每次发送前检查状态发送失败后移除用户能避免僵尸连接堆积。我还会给Session包一层ConcurrentWebSocketSessionDecorator来避免多个线程同时往同一个Session发消息时出现的并发问题。匹配线程和高并发接口都有可能调用sentMessageToUser虽然Java WebSocket规范说Session是线程安全的但实际并发发送时偶尔会出现异常包一层更安心。5.6 心跳机制半小时不掉线是这样做到的WebSocket连接如果长时间没有消息往来中间代理层可能会把它当作死连接关掉。所以必须加上心跳保活。我的方案是前端每隔30秒发一条pingsetInterval(() { if (ws.readyState WebSocket.OPEN) { ws.send(JSON.stringify({ type: ping })); } }, 30000);后端收到ping后回一条pong不做任何业务处理。这条逻辑虽然简单但能显著提升连接的稳定性。我遇到过最长的一次用户挂着匹配页面一个多小时没有断开就是因为心跳一直正常。如果没有心跳连接可能在一个不固定的时间被中间设备切断用户还浑然不知等匹配成功才发现没收到推送那就晚了。6. 实战排查跨域、Token、断线重连与线程安全6.1 WebSocket握手一直404或失败先检查端点与跨域前端new WebSocket报40490%是路径问题。后端的addHandler注册的是/api/websocket前端连接地址就必须是ws://ip:8080/api/websocket不能多一个/api后缀也不能少。另一个常见原因是跨域浏览器控制台显示连接失败但网络面板里能看到请求返回403基本就是setAllowedOrigins没放行当前页面来源。建议前端先用浏览器控制台打印ws.readyState0表示正在连接1表示连接成功3表示已关闭。如果一直是0或2那就要检查握手是否被拒。后端可以临时在AuthHandshakeInterceptor里加一行输出打印收到的请求头快速判断是否because跨域拦截。6.2 Token放在URL参数里的安全习惯用URL传JWT虽然方便但存在安全风险token可能被浏览器历史、服务器访问日志、反向代理日志记录下来。所以握手成功后token不要打印到任何日志里。更好的做法是把token放在Sec-WebSocket-Protocol头里传递后端解析子协议来鉴权这样至少不直接暴露在URL中。但浏览器对子协议值的格式有一定限制需要前后端协商好。我个人的建议是WebSocket使用的token最好用短期有效token过期时间设置在15分钟左右。握手时就算被记录攻击者拿到后也无法长期使用。用户每次重新进入匹配页面都会拿到新token不影响体验。6.3 断线重连不能只靠一次new WebSocket网络抖动、服务器发布、反向代理超时都会导致WebSocket断开。如果前端只创建一次连接断开后就再也没法自动恢复用户体验非常差。我的做法是封装一个connectWebSocket()方法在onclose回调里判断是否用户主动关闭如果不是就延迟3秒重连let ws null; let manualClose false; function connectWebSocket() { manualClose false; ws new WebSocket(ws://localhost:8080/api/websocket?token getToken()); ws.onclose function() { if (!manualClose) { setTimeout(connectWebSocket, 3000); } }; }重连成功后前端要判断之前有没有正在进行的匹配请求如果有就重新发送一条start_match让服务端把用户再次加入匹配队列。要注意在重连前关闭旧连接否则服务端Map里可能同时存在两个同一个userId的Session推送消息时不知道该发哪个还会导致两条重复消息。6.4 匹配线程操作WebSocket时的并发问题匹配线程和其他线程同时操作匹配队列和在线Session最容易出现两个并发问题。第一个是ConcurrentModificationException解决办法是使用ConcurrentLinkedQueue或对遍历加锁。第二个是重复匹配匹配线程第一次扫描发现A和B都符合条件但还没发消息下一次扫描又看到了A和B于是又给两人各发一遍匹配成功。这会导致对局状态非常混乱。我的解决办法是把“出队”和“发送匹配结果”放在同一个同步块里synchronized (matchQueue) { MatchRequest p1 matchQueue.poll(); MatchRequest p2 matchQueue.poll(); if (p1 ! null p2 ! null) { sendMatchFound(p1, p2); sendMatchFound(p2, p1); } }这样同一个队列内不会有其他线程在发送期间插入重复匹配。同步锁在用户量很大的时候会成为热点但这个阶段的用户规模完全够用。重点是先把正确性做扎实后面的优化比如分段锁、桶队列再根据监控数据来做。6.5 前端WebSocket消息乱码和收到空数据刚开始联调时前端经常收到{type:match_found,data:{}}这种空数据多半是后端构造JSON时出了问题。不要手动拼接字符串而是用JSONObject构建结构保证data字段有值再put进去。除了序列化前端还有一个高频问题onmessage里拿到的event.data是字符串必须用JSON.parse()转成对象再访问字段。我见过不少同学直接拿event.data.type半天都取不到值就是因为没有先parse。如果发现有乱码检查两处一是后端是否在发送前设置了TextMessage为UTF-8编码二是浏览器是否以application/octet-stream收到了Blob数据而不是文本数据。解决办法是前端在创建WebSocket时只传字符串消息后端也只发文本消息这个问题就不会出现。最后再分享一个我自己的体会这一篇已经完成了Bot管理的CURD和WebSocket基础通道但真正联调之前一定要先做一个最小闭环验证。我建议先把匹配逻辑简化为“任意两个人点击开始匹配立刻返回匹配成功”用两个浏览器窗口同时测确认推送正常后再加入评分差、段位区间这些业务规则。我先通匹配算法和WebSocket一起调结果问题混在一起折腾了一天才定位到是线程安全问题。先通通道再优化逻辑这条经验能帮你省下大量时间。匹配系统的核心策略下一篇再展开聊。

Spring Boot实战：Bot管理CRUD与WebSocket集成全解析

相关推荐

RAG检索降级三级方案：向量库故障时如何保证回答可信

Keras分类训练后获取验证集y_true与y_preds的三种方案

行为型设计模式详解：策略、模板方法、观察者、迭代器、责任链

更多资讯

Cursor配额重置教程：合法解绑设备+净化指纹实现续杯

AWS ALB SSL证书配置问题排查与解决方案

STM32F407ZG智能门锁实战：舵机闭环、蓝牙原子指令与防误触键盘设计

C++学生管理系统源码解析：从编译运行到二次开发全指南

无约束凸优化算法解析：从梯度下降到拟牛顿法与工程实践

Agentic Collaboration实战：从单Agent到多Agent协作的企业级架构设计

今日更新

声子晶体仿真：三角晶格与六角晶格的能带计算实战

度假村安保定岗定编：岗位梳理、编制测算与排班设计

COMSOL等离子体模块实战：氩气双层DBD仿真建模全解析

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？