WebSocket实战：从零打造在线五子棋对战的消息协议与状态同步

简介这是一套基于WebSocket的在线五子棋对战游戏完整设计源码面向希望掌握C后端与前端实时交互的开发者尤其适合作为课程设计或个人实战项目。项目实现了用户注册登录、对战匹配、实时对局及聊天功能覆盖从服务端通信到页面渲染的完整链路。资源共33个文件压缩包约6.13MB主要包含13个C头文件hpp用于服务端模块封装4个CSS和4个HTML文件构建界面另有SQL、JSON及Makefile等辅助文件结构清晰便于二次开发。目前已有406人学习下载说明具备一定参考价值。通过研读源码可以理解WebSocket协议在游戏场景下的应用方式、多房间匹配机制、数据库交互以及前后端协作的工程组织思路是一份不可多得的实战学习资料。此外Makefile与SQL脚本让环境部署和多人在线匹配逻辑一目了然适合循序渐进地拆解与复现。1. 从选型就开始翻车这个五子棋项目为什么值得用 WebSocket 重写前阵子帮一个计算机专业的学弟调课程设计题目就是“基于 WebSocket 的在线五子棋对战游戏”。他最初抄了一个轮询版本前端每 500 毫秒向后端拉一次棋盘状态也能跑通但联调时暴露了一个尴尬问题两个人同时落子后落的把先落的覆盖了日志里全是脏数据。最后他来找我的时候我直接把轮询删了换成 WebSocket 重写对局模块问题当场消失。五子棋这种应用消息量小、频率高但对时序和通知即时性要求很严格。HTTP 轮询的问题不只是延迟而是“服务端无法主动通知”——对手落子后你的前端要等下一个轮询周期才能看到体验像在玩半盲棋。WebSocket 的长连接语义天然适合这种场景服务端可以在对手落子的同一瞬间把消息推给你双方看到的棋盘永远一致。这个项目也确实是 WebSocket 入门最友好的练手对象协议简单、业务规则明确、不需要处理音视频那种高吞吐数据适合把连接管理、消息协议、状态同步这一套完整走一遍。适合谁做想搞懂 WebSocket 通讯原理的学生和想拿一个完整项目练习前后端联调的新手。源码里最有价值的部分不在画棋盘而在那套消息协议和对局状态机接下来的内容就按这个顺序拆。2. 先把消息协议定死你要同步的不是棋盘是事件WebSocket 上手容易翻车也容易十有八九是栽在“不知道该传什么”上。很多人一上来就在后端写一个sendAll(chessboard)每次落子把整个 15x15 棋盘序列化发过去。这么做不是不行而是把简单问题做复杂了——棋盘数据冗余、对端要全量解析、遇到悔棋和认输这类非落子消息时还得加特殊字段。我在做这个项目时采用的方案是只传事件不传状态。棋盘状态在每个客户端本地维护服务端只广播“发生了什么事”。2.1 消息结构用 type 字段区分五类消息而不是散装 JSON先定协议再写代码。我一般会在项目根目录建一个protocol.md把消息格式固定下来前后端各留一份。以下是这个五子棋项目最核心的协议定义所有消息均为 JSON 文本帧// 客户端 - 服务端 {type: join, playerName: 小明, roomId: room_001} {type: move, x: 7, y: 7, roomId: room_001} {type: chat, content: 该你了, roomId: room_001} // 服务端 - 客户端 {type: match_success, roomId: room_001, color: black, rivalName: 小红} {type: move_ok, x: 7, y: 7, player: black} {type: game_over, winner: black, winLine: [[7,7],[8,8],[9,9],[10,10],[11,11]]} {type: error, code: 1001, msg: 不是你的回合}协议里为什么必须有roomId因为 WebSocket 连接建立后服务端需要知道这条消息属于哪一局。你可以在服务端用 session 对象记录当前用户所在的房间但加上roomId后日志排查和断线重连都会简单得多。真正踩过坑的人会明白省掉一个看似冗余的字段联调时多花两小时。2.2 落子判定为什么必须放服务端一个来自源码的教训这是我从失败版本里总结出来的经验。最初我以为前端判胜负就够了——毕竟五子棋的规则不复杂。直到有个测试同学用浏览器控制台直接调用了 WebSocket 的send方法给自己发了一条move_ok消息客户端弹出了“你赢了”服务端却毫不知情。听众可能觉得这很蠢但这种攻击在课程设计答辩演示时特别容易翻车。正确做法是前端只负责绘制和交互所有逻辑判定放在服务端。服务端维护一份int[15][15]棋盘数组每次收到move消息后先验证五件事是否轮到该玩家坐标是否在 0~14 范围内该位置是否已被占用是否处于对局中状态落子后是否产生五连验证通过才更新棋盘、广播move_ok、检查胜负。客户端可以自己也算一遍用于即时反馈但最终以服务端为准。这个“服务端权威”原则是这个项目源码里最值得抄的设计之一。它避免了一大票想着“前后端各管一半”的坑。2.3 状态机先行对局的四个阶段怎么流转不要一上来就写具体代码先画出对局的状态流转WAITING等待对手→PLAYING对局中→FINISHED已结束→ 重新匹配。状态只有四种但很多实现把状态散落在各种 if 分支里最后变成一团乱麻。我习惯的做法是在服务端建一个GameRoom类内部维护state字段所有状态变更必须经过统一的方法入口public class GameRoom { private String roomId; private Player blackPlayer; private Player whitePlayer; private int[][] board new int[15][15]; private int currentTurn 1; // 1黑棋2白棋 private AtomicBoolean gameOver new AtomicBoolean(false); private volatile RoomState state RoomState.WAITING; public synchronized boolean tryMove(Player player, int x, int y) { // 核心校验逻辑 if (state ! RoomState.PLAYING) { throw new IllegalStateException(对局未开始); } if (!player.getColor().equals(currentTurn)) { return false; // 不是该玩家的回合 } if (board[x][y] ! 0) { return false; // 位置已被占用 } board[x][y] currentTurn; currentTurn 3 - currentTurn; // 切换回合 return true; } }这里的synchronized关键字是必须的。WebSocket 服务端是多线程环境两个玩家几乎同时落子时会出现竞态条件不加锁会出现同一回合双方都落子的异常情况。AtomicBoolean用于防止对局结束后还被重复写入。volatile修饰的state保证多线程可见性。这些细节看起来不起眼但去掉任何一个高并发下都会暴露问题。3. 后端落盘Spring Boot 整合 WebSocket 的房间管理与匹配后端框架的选择我建议直接用 Spring Boot。不是因为 Spring 有多高大上而是它的 WebSocket 模块把连接管理、握手、会话管理都封装好了你只需要关心业务逻辑。Spring Boot 整合 WebSocket 的方式其实不止一种有ServerEndpoint注解版和实现WebSocketHandler接口的版本。这个项目里我推荐后者因为WebSocketHandler能更清晰地处理连接生命周期配合 Spring 的依赖注入也更自然。3.1 核心代码Handler 里不仅要处理连接更要管理房间先看服务端的核心处理类这是整个对局服务的心脏。需要注意的一点是WebSocketSession不是线程安全的不要在 Handler 里直接持有 session 集合做并发遍历下面代码用了ConcurrentHashMap管理房间和玩家会话这是实操中被验证过的安全做法Component public class PlayerHandler extends TextWebSocketHandler { private final ConcurrentHashMapString, GameRoom rooms new ConcurrentHashMap(); private final ConcurrentHashMapString, WebSocketSession playerSessions new ConcurrentHashMap(); private final QueuePlayer waitingQueue new ConcurrentLinkedQueue(); Override public void afterConnectionEstablished(WebSocketSession session) { // 连接建立成功但此时还不知道玩家名字等待第一条 join 消息 playerSessions.put(session.getId(), session); } Override protected void handleTextMessage(WebSocketSession session, TextMessage message) { JSONObject msg JSON.parseObject(message.getPayload()); String type msg.getString(type); switch (type) { case join: handleJoin(session, msg); break; case move: handleMove(session, msg); break; case chat: handleChat(session, msg); break; default: sendError(session, 1000, 未知消息类型: type); } } Override public void afterConnectionClosed(WebSocketSession session, CloseStatus status) { // 清理玩家会话并尝试退出房间 String playerId session.getId(); playerSessions.remove(playerId); GameRoom room findRoomByPlayerId(playerId); if (room ! null) { room.playerOffline(playerId); } } private void handleJoin(WebSocketSession session, JSONObject msg) { String playerName msg.getString(playerName); Player player new Player(session.getId(), playerName); playerSessions.put(session.getId(), session); // 尝试匹配对手如果没有则进入等待队列 Player rival waitingQueue.poll(); if (rival ! null) { createRoom(player, rival); } else { waitingQueue.offer(player); sendMessage(session, {\type\:\waiting\,\msg\:\正在匹配对手\}); } } }逻辑说明handleTextMessage根据type字段做分发这种 switch 写法比 if-else 链清晰得多后续加新的消息类型比如悔棋、求和只需要加一个 case。waitingQueue是匹配队列先来的人等待第二个来的人直接配对。配对成功后两个玩家各自收到match_success消息包含该局的roomId和各自的棋子颜色。参数说明ConcurrentHashMap是必须的因为多个玩家同时加入如果使用普通HashMap会在扩容时产生环形链表导致 CPU 飙到 100%。ConcurrentLinkedQueue是线程安全的 FIFO 队列用来做匹配等待。这两处设计如果你直接抄 J2SE 的HashMap和ArrayList大概率是后面翻车的伏笔。3.2 匹配机制用等待队列做匹配时的三个策略选择很多人觉得匹配逻辑简单两个玩家一凑齐就开局但实现时需要考虑三个实际问题。第一玩家掉线后等待队列怎么清理。如果一个玩家在等待时断开了连接他留在waitingQueue里的对象就成了脏数据后面匹配到它时往一个已关闭的 session 里发消息会抛异常。解决办法是在afterConnectionClosed里同步把等待队列里对应 session 移除waitingQueue.removeIf(p - p.getSessionId().equals(closedSessionId))。第二同一个人重复发 join 怎么处理。用户手滑点了两下“开始匹配”会往队列里塞两条记录。解决方式是在handleJoin前先检查该 session 是否已在某个房间或在队列里如果存在则返回错误消息。这类防御逻辑虽然只在极端情况下触发但是源码质量的加分项。第三匹配成功后房间的创建。createRoom方法里会生成一个 6 位随机roomId存进rooms这个 ConcurrentHashMap。这里还有个细节玩家的移动端和 Web 端如果同时开着两个连接会匹配到自己的问题可以在匹配前校验 session 是否相同或者生成一个设备标识按设备去重。3.3 消息推送的幂等性重发与丢消息一个现实主义话题WebSocket 本身不保证消息一定送达TCP 层保证字节流不丢失但业务层面存在两种情况一是客户端处理消息失败二是连接恰好断开的瞬间消息丢失。五子棋这种低频应用每次落子后服务端给双方各发一条move_ok如果这条消息丢了棋局就不同步了。常见的弥补方式是对局中的每一次落子都带上一个递增的序列号 seq。客户端发现收到的 seq 不连续就主动向服务端发一条sync请求服务端返回当前棋盘的全量状态。这样既有事件驱动的实时性又有状态同步的兜底。这个设计很像游戏领域的“快照同步”与“事件同步”混合模式在这个项目里作为规范做法值得收录。序列号从 1 开始每落一子加一。sync消息里客户端带上自己最后一条消息的 seq服务端比较后返回sync_board内容是完整的 15x15 棋盘和当前回合、当前 seq。每次对局结束后房间对象被销毁序列号归零一局一套不跨局复用。4. 前端棋盘与消息处理Canvas 绘制、点击判定与断线重连后端稳住了前端就容易了。但前端也有两个真正的难点一是棋盘绘制和坐标换算的精确性二是 WebSocket 连接的生命周期管理。Canvas 绘制 15x15 棋盘并不复杂真正容易翻车的是点击坐标换算。很多新手直接把click事件的clientX当棋盘坐标用结果棋子落在交叉点旁边观感很差。4.1 画出棋盘Canvas 的参数与坐标换算公式先看核心绘制代码使用与后端同一套坐标系0~14const BOARD_SIZE 15; const CELL_SIZE 40; const MARGIN 30; const canvas document.getElementById(board); const ctx canvas.getContext(2d); function drawBoard() { ctx.clearRect(0, 0, canvas.width, canvas.height); // 画横线 for (let i 0; i BOARD_SIZE; i) { ctx.beginPath(); ctx.moveTo(MARGIN, MARGIN i * CELL_SIZE); ctx.lineTo(MARGIN (BOARD_SIZE - 1) * CELL_SIZE, MARGIN i * CELL_SIZE); ctx.stroke(); } // 画竖线 for (let i 0; i BOARD_SIZE; i) { ctx.beginPath(); ctx.moveTo(MARGIN i * CELL_SIZE, MARGIN); ctx.lineTo(MARGIN i * CELL_SIZE, MARGIN (BOARD_SIZE - 1) * CELL_SIZE); ctx.stroke(); } // 画星位天元和四个星 const starPoints [[7, 7], [3, 3], [11, 3], [3, 11], [11, 11]]; starPoints.forEach(([x, y]) { ctx.beginPath(); ctx.arc(MARGIN x * CELL_SIZE, MARGIN y * CELL_SIZE, 4, 0, Math.PI * 2); ctx.fillStyle #000; ctx.fill(); }); }点击坐标换算要特别小心这里给出正确处理方式canvas.addEventListener(click, (event) { const rect canvas.getBoundingClientRect(); const scaleX canvas.width / rect.width; const scaleY canvas.height / rect.height; const x Math.round((event.clientX - rect.left - MARGIN) / CELL_SIZE); const y Math.round((event.clientY - rect.top - MARGIN) / CELL_SIZE); if (x 0 x BOARD_SIZE y 0 y BOARD_SIZE) { sendMessage({type: move, x, y, roomId}); } });逻辑说明Math.round把最近交叉点作为落子位置视觉上最自然。用getBoundingClientRect而不是直接event.offsetX是因为在高分屏或者页面缩放时Canvas 的实际尺寸和 CSS 尺寸不一致直接使用 offsetX 会导致点击偏移。参数说明CELL_SIZE为 40 像素时棋盘整体宽度为30*2 14*40 620像素这样的尺寸在桌面端和移动端横屏都有较好表现。MARGIN设为 30 是为了给边界留白同时让星位和天元有足够的绘制空间。两个参数在你的页面布局调整时可以按比例改动但必须同步修改坐标换算公式。4.2 连接管理与自动重连指数退避的具体写法对局中最怕的就是断线。断线后双方界面停止响应黑匣子一样没有任何反馈。这里给出一套可用的重连方案用指数退避算法避免断网恢复瞬间所有客户端同时重连打爆服务端let ws null; let reconnectAttempts 0; let heartbeatTimer null; function connectWebSocket() { ws new WebSocket(ws://${window.location.host}/game-websocket); ws.onopen () { reconnectAttempts 0; // 恢复对局如果之前对战到一半重新发送 join 并带上一局 roomId if (roomId) { sendMessage({type: join, playerName: myName, roomId: roomId}); } // 启动心跳每 15 秒发送一次 heartbeatTimer setInterval(() { if (ws.readyState WebSocket.OPEN) { ws.send(JSON.stringify({type: ping})); } }, 15000); }; ws.onclose () { clearInterval(heartbeatTimer); const delay Math.min(1000 * Math.pow(2, reconnectAttempts), 15000); reconnectAttempts; setTimeout(connectWebSocket, delay); }; ws.onmessage (event) { const msg JSON.parse(event.data); handleServerMessage(msg); }; } function sendMessage(obj) { if (ws ws.readyState WebSocket.OPEN) { ws.send(JSON.stringify(obj)); } else { console.warn(连接未就绪消息发送失败); } }逻辑说明心跳机制的目的是检测“假连接”——TCP 连接还开着但网络已经不可用。15 秒一次的 ping 频率对五子棋这种低流量应用完全够用。后端收到 ping 后返回 pong前端如果在两个心跳周期30 秒内没收到任何消息认为连接已不可靠主动调用ws.close()触发重连。参数说明重连延迟从 1 秒开始每次翻倍最大 15 秒。指数退避的目的不是单纯地“等久一点”而是防止大量客户端同时重连造成服务端雪崩。如果你嫌 15 秒太久可以调成 10 秒但不要去掉Math.pow(2, reconnectAttempts)这个退避逻辑——直接写死 3 秒重连在教室这种弱网环境下会把服务端打挂。4.3 消息分发与本地棋盘更新保证 UI 不被覆盖收到handleServerMessage后前端要处理的事件类型主要有四种。这里的关键设计是棋盘状态只能由服务端消息驱动更新本地点击只做发送不直接改棋子数组。点击后 UI 上出现一个“预落子”的半透明棋子等收到move_ok后才画成实心棋子。等不到确认就保持半透明避免双方看到不一致的棋盘。function handleServerMessage(msg) { switch (msg.type) { case match_success: roomId msg.roomId; myColor msg.color; // black | white showRivalName(msg.rivalName); if (myColor black) { showStatus(你是黑棋请落子); } else { showStatus(你是白棋等待对手落子); } break; case move_ok: drawPiece(msg.x, msg.y, msg.player); currentTurn (msg.player black) ? white : black; updateTurnIndicator(currentTurn); break; case game_over: drawPiece(msg.x, msg.y, msg.player); highlightWinLine(msg.winLine); showGameOverModal(msg.winner); break; case error: alert(操作失败: ${msg.code} - ${msg.msg}); break; default: console.warn(未知消息类型:, msg.type); } }有一处容易疏忽的点服务端的move_ok里没有带roomId因为一个 socket 连接只属于一个房间没有歧义。参数越少出错概率越低。前端的currentTurn变量只用于 UI 提示不用于逻辑判赢——判赢永远以服务端的game_over为准。5. 联调避坑记录断线、脏数据与“为什么我只能下黑棋”的诡异现场联调阶段是这类项目投入产出比最高的环节。以下是我和学弟在调试过程中真实踩过的四个坑每条都按“现象 → 原因 → 解决”的顺序写。这些都是血泪经验建议收好。5.1 断线重连后房主始终是黑棋但对手始终无法落子现象玩家 A 断线重连后棋盘显示正常轮到自己落子但点击棋盘没有任何反应。后台日志显示客户端发了move消息服务端返回了error: 不是你的回合。原因断线重连后前端重新发送join消息服务端把它当成一个新玩家处理又重新进行了一次匹配。此时玩家 A 被匹配到一个新房间而原本的房间还在等待它回归两个房间的服务端状态都显示“轮到你下棋”但前端棋盘还是旧房间的棋盘数据。解决在join消息中增加roomId字段如果携带了roomId且该房间状态为“等待玩家回归”则恢复该玩家的会话绑定而不是创建新房间。前端在重连时自动带上之前的roomId。这是多玩家在线对战项目里很经典的一个坑值得专门写进你的源码说明里。5.2 基于 monitor 的压测导致“两个玩家同时落子成功”现象用 Postman 的 WebSocket 连接功能建立了两个连接模拟双人对战。高频率交替发送move消息时偶尔出现同一回合两个棋子都成功的异常状态。原因GameRoom.tryMove方法里的同步锁只能锁住单个 JVM 实例内的并发访问但两个连接如果落在不同的服务实例本地调试时不会但部署到多个节点时就会锁就失效了。即使单机部署handleMove里先判断再更新currentTurn的操作不是原子的也可能产生时序问题。解决单机场景下将tryMove的synchronized方法改为synchronized代码块锁住roomId对应的对象。多机部署场景就得引入 Redis 分布式锁key 设计为room:lock:{roomId}加锁加超时时间比如 2 秒。这个项目里单机锁足够但你要在源码注释里写明白让别人知道多机部署时该往哪里加分布式锁。5.3 为什么移动端点击棋盘总是偏移两三个格子现象同一个 Canvas 代码在 PC 浏览器上点击精准在手机浏览器上棋子位置整体向下偏移。原因手机的 devicePixelRatio 是 2 或 3Canvas 的width属性按物理像素设置但 CSS 里的style.width是按 CSS 像素设置的。点击事件返回的clientX是 CSS 像素坐标直接用就偏了。虽然我在代码里做了scaleX canvas.width / rect.width但因为画棋盘时是按逻辑像素画的实际绘制像素是canvas.width换算回来后还要除以devicePixelRatio。解决正确的换算公式是x Math.round((event.clientX - rect.left - MARGIN) / CELL_SIZE)。关键是canvas.width不能直接设为rect.width * devicePixelRatio—— 如果设置了重新在drawBoard里画线时线的位置也要乘以 scale。这就是为什么很多开源项目的实现看起来一样但实际效果天差地别。这个坑在真机调试之前几乎是玄学一样的存在。5.4 对局中刷新页面左侧的黑匣子看不见也连不上现象对局中途按 F5 刷新页面WebSocket 连接断开服务端房间还在。刷新完成后前端自动重连但服务端已经清除了玩家会话玩家无法加入原房间只有一个卡死的界面。原因服务端在afterConnectionClosed时把玩家从房间中移除了房间状态变成WAITING等待新玩家但界面还是PLAYING状态。前端没有收到任何“你已离开对局”的通知因为此时连接已经断了消息发不出去。解决在“对局中刷新页面”这种场景下前端做一次状态持久化——把roomId、myColor存到sessionStorage。刷新后读到roomId就自动重连并主动带roomId恢复。服务端额外提供一个rejoin消息类型如果房间还在且等待认可直接恢复会话如果房间已结束返回room_expired前端提示用户重新匹配。这个“对局中途刷新回到战场”的恢复机制在课程设计答辩时是很好的加分项。6. 把项目从“能跑”推向“能演示”观战模式、压测技巧与复盘回放五子棋练手项目做到能双人对战距离“能演示、能答辩、能写进简历”还有三段路加一个说服力强的功能、做一次像样的联调验证、把核心机制说明白。6.1 观战模式只比对战模式多 20 行代码观战模式是性价比极高的进阶功能。它的本质是把房间内消息广播给第三方 session。我的实现方式是在GameRoom里维护一个ListWebSocketSession watchers收到move_ok等消息时对玩家 session 发一份对 watcher session 也发一份。观战者不能发move消息服务端在handleMove里做一次类型检查即可。观战者的join消息携带watch: true字段服务端不走匹配逻辑直接加入房间的观察者列表。观战者中途加入时需要先收到一帧sync_board全量棋盘快照。这个快照代码你和前面的sync消息复用同一个方法一步到位。6.2 用 Postman 给 WebSocket 做冒烟测试双向消息的验证方法很多人用浏览器开发者工具调试 WebSocket但那只能看消息收发没法模拟双人交互。我的习惯是用 Postman 的 WebSocket 客户端功能开两个连接连接 1 发join连接 2 发join观察两端收到的match_success是否一致。然后交替发move检查move_ok的player字段是否交替变化。这个测试流程 5 分钟能走完但能提前暴露大多数协议问题。测试时要特别注意消息顺序。WebSocket 基于 TCP消息不会乱序但服务端多线程处理时消息的到达顺序和处理顺序可能不一致。比如用户快速连点两次落子服务端线程 A 处理消息 1 时正好切换到线程 B 处理消息 2就会出现“第二颗子先落”的异常。在服务端给每个房间的handleMove加锁后这个问题就消失了。压测的意义不只是性能更多是暴露这种并发逻辑漏洞。6.3 复盘回放用序列号实现“悔棋”和“重播”的通用方案最后一个进阶技巧是复盘回放。早期版本里我直接在客户端把每一步move_ok存进数组需要回放时按序重绘。但后来发现这样无法支持观战者中途加入后的回放因为观战者没有之前的历史数据。于是把落子记录挪到了服务端每局游戏维护一个Listint[] moveHistory每次收到合法落子就history.add(new int[]{x, y, color})。观战者加入或者玩家断线重连时先同步一次全量历史再增量同步后续步骤。复盘回放还有一种常见需求想看对手最后是怎么赢的。我在game_over消息中加入了winLine字段是五连子的坐标数组[[3,3],[4,4],[5,5],[6,6],[7,7]]。前端收到后高亮这条线棋局结束立刻显示获胜路径观战者也能直接看到胜负关键处。这个细节在答辩演示时特别有表现力因为评委一眼就能看清棋局走向。最后说一个我自己的习惯每次做完一个练手项目我都会把协议文档、源码结构说明和部署步骤写进 README 的前三段。不是为了给别人看而是两个月后自己回头看能快速想起来当时为什么这么设计。这比代码注释更能帮你沉淀经验。这个五子棋项目做完你掌握的 WebSocket 生命周期管理、并发状态同步和服务端权威校验的思路能直接迁移到在线白板、协同编辑和实时监控面板等场景。希望帮到你。本文还有配套的精品资源点击获取