简介微信小程序后端开发是近年高频需求涉及用户鉴权、实时通信与状态一致性等核心问题。棋牌类小程序对实时交互要求极高常用架构以 Spring Boot 作为业务主框架Netty 构建 WebSocket 长连接网关Redis 缓存热数据MySQL 持久化冷数据。其原理是通过状态机管理牌局流转结合消息队列处理并发操作从而保证出牌、碰杠等动作的毫秒级响应与严格顺序。这一技术栈的价值在于兼顾开发效率与稳定性适用于地域性棋牌游戏、在线桌游等场景。本文以福州永泰麻将后端为例复盘从规则引擎、数据建模到部署压测的完整落地路径帮助开发者理解地方棋牌项目从 0 到 1 的工程要点。2. 拆解项目核心目标与业务画像做福州永泰麻将微信小程序后端首先得把永泰麻将这四个字吃透。很多开发者一看麻将小程序就觉得是通用棋牌游戏直接套用四川麻将或广东麻将的规则结果上线后被本地玩家骂得狗血淋头。麻将游戏的地域性极强永泰麻将和福州其他区县的玩法都有差异更不用说跟外省比了。做后端之前项目核心目标不是做一个能跑的麻将服务端而是做一个能精确复现永泰本地牌桌规则的结算引擎外加一整套支撑微信小程序前端稳定运行的实时通信服务。永泰麻将的特色主要体现在几个方面牌张构成上以福州地区常见的带金玩法为基础金可以当任意牌使用但在不同胡牌牌型里金的算番方式有特殊规定杠牌之后从牌墙尾部补牌并且有金杠暗杠放杠等不同计分口径胡牌牌型里包含平胡、碰碰胡、清一色、混一色、金雀、抢金、三金倒等本地玩家熟悉的番型。后端如果只做到能胡牌的程度那完全不够必须把每番怎么算、谁付谁收、封顶多少这些细节全部规则化、代码化。从技术视角看这个项目的核心目标可以拆成四块。第一块是用户体系需要对接微信登录搞定 openid 的获取与绑定让玩家能通过微信小程序一键进房。第二块是房间系统提供创建房间、分享邀请、玩家加入、房主解散等功能相当于传统棋牌室的开台。第三块是牌局引擎包含发牌、摸牌、出牌、碰杠胡、听牌检测、番数计算等完整的牌局状态机。第四块是实时通信层负责把牌桌状态变化推送给房间内所有玩家并处理断线重连、超时托管等异常场景。这套项目最适合两类读者参考一是准备入行棋牌类微信小程序开发的后端工程师二是接外包项目需要快速搭建地方棋牌后端的团队。前者可以重点看牌局状态机和通信层的设计思路后者可以重点看用户鉴权、房间生命周期和计费模块的落地方式。4. 技术选型为什么是这套组合棋牌后端的技术选型非常考验架构师的判断力。你不能一上来就上微服务、消息队列、分库分表因为一个本地棋牌小程序的同时在线人数通常就几百到几千复杂度根本到不了那一步。但也不能只写一个单体服务就完事因为牌局的强实时性和状态一致性要求很高稍有不慎就会出牌发重了两个人同时胡牌这类事故。我最终选定的技术栈是核心业务用 Java Spring Boot 3.x 构建实时通信用 Netty 做 WebSocket 长连接服务数据存储用 MySQL 8.0 加 Redis 7.x部署用 Docker Compose 一把拉起。下面逐个说清楚为什么这么选。先看核心框架。Spring Boot 是目前国内后端招聘和外包接单的主流选择社区资料多、招人容易而且 RuoYi 这类快速开发框架能够直接把后台管理端的骨架搭好省掉搭建权限管理、日志审计这些重复劳动的时间。对于棋牌项目来说Spring Boot 的定时任务能力可以处理牌桌超时解散拦截器机制可以统一处理登录态校验Starters 生态里的 validation、mybatis-plus 集成也都是现成的开发效率非常高。再说实时通信。麻将和其他类型的游戏有个显著区别一局牌的交互频率并不高每个人摸牌、出牌、碰杠的操作间隔通常在几秒到十几秒之间但它要求消息推送延迟足够低、顺序足够严格。一开始我考虑过用微信小程序自带的 WebSocket 接口直接连 Spring Boot 内置的 WebSocket 支持但实测下来并发连接数一上去Spring 自带的 WebSocket 在心跳维护和消息推送吞吐量上会有一点吃力。后来换成 Netty 做独立的 WebSocket 网关服务主业务 API 走传统的 HTTP 调用牌桌内的实时消息走 Netty 网关推送两个服务之间通过 Redis 做数据同步和指令转发整个架构就清晰了很多。而且 Netty 底层的 EventLoop 模型天然适合处理大量长连接空闲检测、心跳超时、自动重连这些功能都能用现成的 handler 实现。存储层的选型相对传统。MySQL 负责存用户账号、房间记录、对局记录、结算流水这些结构化数据。Redis 承担两类任务一类是热点缓存比如玩家当前所在房间号、座位编号、出牌倒计时剩余秒数这些数据每次请求都要读直接放 Redis 能少打很多次 MySQL另一类是基于 Redis 的分布式锁确保在极端并发下两个玩家同时操作同一张牌的操作不会产生数据竞争。这里要特别提一下牌局类项目最忌讳把每一手牌的状态都同步落库因为麻将洗牌、发牌、打牌的过程状态变化极快频繁写库会把 MySQL 的压力打满。我的方案是对局中的实时状态全部放在 Redis 里用 JSON 序列化保存整桌牌局信息每局结束之后再写一条完整对局记录到 MySQL最后把 Redis 里的缓存清理掉。这套方案在几百人同时在线的场景下非常稳。选型上还有一点容易被忽略就是抓包工具和联调工具的准备。做棋牌类小程序后端免不了要和前端的请求做各种联调。小程序端的请求默认会走微信的 HTTPS 证书校验和域名白名单排查问题的时候没法直接用浏览器 F12 看网络面板这时候最好在本地准备好 Reqable 或 Charles 这类抓包工具配合小程序的不校验合法域名调试开关把 HTTP 请求和 WebSocket 帧都抓下来问题定位效率能翻好几倍。这个点后面在问题排查部分会详细展开讲。5. 数据模型设计牌局状态与玩家账号的存储边界后端开发中数据模型设计的质量直接决定了后期维护成本。永泰麻将项目里主要涉及到四类核心数据用户数据、房间数据、牌局状态数据、结算流水数据。这四类数据的特征差异非常大必须分开设计表结构避免互相干扰。先说用户数据。微信小程序端的登录流程是前端调用 wx.login() 拿到临时 code传给后端后端拿着 code 调用微信的 code2Session 接口换取 openid 和 session_key。注意这个 openid 是用户在当前小程序下的唯一标识绝对不能当作用户 ID 直接暴露给前端因为它是账号体系里的敏感凭证。我的做法是后端拿到 openid 后先查 MySQL 的 user 表如果不存在就新建一条用户记录生成一个自增的 user_id 作为业务主键然后生成一个自定义的 tokenUUID 或者 JWT把这个 token 返回给小程序端后续所有 HTTP 请求都带上这个 token。user 表的结构大概是这样的id、openid唯一索引、nickname、avatar_url、gold_coin房卡余额、create_time、update_time。这里 nickname 和 avatar_url 是冗余存储微信的资料信息避免每次都要调微信接口获取。接着说房间数据。创建房间的逻辑可以直接对标线下棋牌室的开台。玩家创建房间时会指定玩法规则比如番数上限局数是否允许吃牌金的使用方式等。后端需要把这些规则参数序列化后存到 room 表里以便对局中随时读取。room 表的核心字段id、room_no六位数字房间号玩家凭这个号进房、owner_user_id、status等待中/对局中/已结束、max_players通常固定 4、current_players、rulesJSON 类型存玩法配置、create_time。房间号要保证短且唯一我的方案是用 Redis 的 INCR 命令生成自增序列再转成六位数字并加入校验位避免玩家输错房间号误入其他人的牌局。牌局状态数据是整个项目里最复杂的一张表也可以说不算表因为对局过程中的状态我基本不落 MySQL。我会在 Redis 里用一个 key 存储整桌的实时状态value 是一个包含以下信息的 JSON当前局号、牌墙剩余数量、每家手牌数组、当前出牌玩家位置、牌池中的牌、碰杠胡的操作队列、本局番数配置、开始时间。把这些状态全放 Redis 的好处是读写极快而且可以用 Redis 的 EXPIRE 命令给每一局设置超时时间防止某个玩家掉线后整个房间永久卡死。但风险也是存在的Redis 数据在极端情况下会丢失所以每局结束的瞬间我会立刻把整局回放数据写入 MySQL 的 game_record 表作为最终的结算凭证。game_record 表的核心字段id、room_id、round_no第几局、players_snapshotJSON记录四个玩家的 id 和座位、final_handsJSON终局手牌、actions_logJSON完整操作序列、settlement_detailJSON每家输赢明细、create_time。这张表的价值在于一旦玩家对结算结果有争议前端可以回放 actions_log 里的每一步操作后端也能根据 settlement_detail 重算一遍番数核对。结算流水数据是跟钱相关的部分必须做到可追溯。永泰麻将这类房卡制麻将小程序不直接涉及人民币交易玩家消耗的是房卡这种虚拟道具所以结算流水主要记录的是房卡的消耗和房间的创建情况。我设计了 card_consumption_log 表id、user_id、room_id、amount消耗数量、action_type创建房间消耗、充值到账、赠送、create_time。这个表的数据要和用户余额的变化严格联动扣费操作和创建房间操作必须放在同一个事务里保证不会出现房卡扣了但房间没创建或房间创建了但房卡没扣的脏数据。设计这部分时最容易犯的错是把所有状态都塞进一张大表导致对局中频繁读写。一个简单原则热数据牌局实时状态进缓存冷数据用户信息、对局记录、流水进数据库两者通过定时任务和事件回调保持同步。最开始我没有严格按这个原则来导致多人同时对局时 MySQL CPU 经常飙到 80%把热数据挪到 Redis 之后 CPU 直接降到了 10% 以下。6. 牌局流程实现永泰麻将规则引擎的落地细节规则引擎是整个项目的灵魂。没有哪个开源项目能直接给你一套永泰麻将的规则配置所有东西都得自己写。先梳理一下一局牌从开始到结束的核心流程洗牌、发牌、定庄、出牌、摸牌、碰/杠/胡判定、金处理、流局、结算。后端必须把这个流程抽象成一个状态机而且在每个状态转换的边界上做好并发控制。先讲洗牌和发牌。洗牌不能简单地用随机函数打乱数组那样会有概率上不够均匀的问题。我用的方案是 Fisher-Yates 洗牌算法生成一个足够随机的牌序。永泰麻将用 136 张牌万、条、筒各 36 张东南西北中发白各 4 张不考虑花牌。发牌阶段每人 13 张庄家 14 张发完牌后剩下的牌就是牌墙。发牌结果要记录到 Redis 的局状态里同时要准备一个 actions_log 数组从第一张牌开始记录所有动作方便后期对账。出牌和摸牌的流程设计本质上是一个消息驱动的环形状态机。我用一个 turn 变量记录当前轮到谁玩家每次出牌请求都会带一个自增的 seq 序号后端收到请求后校验 seq 是否合法防止旧消息覆盖新状态。出牌之后要广播给其他三家同时检查是否有其他玩家可以碰、杠或胡。这里的检查必须是有优先级的胡 碰/杠 摸牌也就是说如果有多家同时响应某张牌优先结算胡牌其次是碰杠然后才轮到下家摸牌。这个优先级我用一个 wait_responses 的消息队列来实现出牌消息推送给其余三家后后端进入一个短暂的等待窗口比如 2 秒收集各家的操作意图等窗口结束再统一处理最高优先级的操作。等待窗口的时长控制很关键太短玩家来不及点碰杠太长影响节奏实测 2 秒比较合适。再讲金和番数计算。永泰麻将的金在代码里可以抽象成一个特殊标记比如用牌值 100 到 103 表示东南西北四张金。起手牌发完后需要翻一张牌确定金这张翻出的牌加上同花色的下一张都是金。金在胡牌时可以当作任意牌使用但在某些特殊牌型里金本身也可以参与计番。代码实现上我在胡牌判断函数里增加了一个万能牌替换的逻辑遍历所有手牌组合尝试把金替换成任意一张缺失的牌看能否凑出合法牌型。这个逻辑用递归实现性能上要小心因为组合数会爆炸我做了两层优化一是提前剪枝只对当前牌型离胡牌只差一张牌的情况做替换尝试二是使用位运算加速牌型判断把每张牌编码成 4 位整数用 bitmask 表示手牌集合判断速度比数组遍历快一个量级。最后是定庄和流局机制。第一局可以随机定庄之后如果上局有人胡牌胡牌者连庄如果流局则庄家下移。流局条件是牌墙剩余牌数小于某个阈值比如剩 8 张以内视为牌墙摸完。流局后不结算得分只记录流局次数连续流局多局后会触发翻倍机制这是永泰本地玩法里的常见设定。后端代码里需要把流局判断放在每次摸牌动作之后如果触发流局直接广播本局流局消息并进入下一局的初始化流程。规则引擎部分最容易出的 bug 是边界情况没考虑到。比如玩家碰完牌后手牌只剩一张了下一轮摸牌后要不要自动进入听牌等待金被杠掉之后能不能重新翻金实际写代码时建议把规则逻辑单独做成一个 RuleEngine 类尽量让所有判断函数都是纯函数输入当前状态输出允许的操作列表这样单元测试写起来非常方便后期改规则也只需要动这一个类。7. 实时通信设计从轮询到 WebSocket 长连接棋牌项目对实时性的要求跟聊天软件不同聊天允许消息延迟一两秒但麻将出牌后如果碰杠响应慢了玩家体验会非常差。这里有两个方案可以做一是小程序端轮询 HTTP 接口获取状态变化二是通过 WebSocket 建立服务端推送通道。轮询的优点是实现简单、天然兼容 HTTP但缺点是服务器压力大、消息延迟不稳定、而且小程序端如果频繁发请求很容易触发微信的接口频率限制。我最终选择了 WebSocket 长连接方案并实现了完整的断线重连机制。微信小程序端的 WebSocket 使用方式和浏览器端几乎一致区别在于小程序的 wx.connectSocket 接口需要在 onSocketMessage 回调里自己处理消息分发而且小程序在切后台后 WebSocket 会被系统挂起回到前台必须重新连接。这个特性决定了后端的连接管理不能只认一个 WebSocket 连接必须做到一个用户对应一个逻辑会话连接断了自动恢复上下文。Netty 网关服务的核心组件可以这样理解每个玩家连接上来后Netty 会为这个连接创建一个 ChannelChannel 的 pipeline 里挂一串 handler其中负责协议解析的 handler 把二进制帧或 JSON 文本解析成统一的 Message 对象。我在消息对象里定义了 type比如 JOIN_ROOM、PLAY_CARD、PONG 等、room_id、player_id、seq、payload 等字段。网关收到消息后会根据 type 决定是直接处理还是转发给业务服务比如 PONG 心跳包直接在网关层处理PLAY_CARD 这类业务消息则会写入 Redis 的指令队列由 Spring Boot 业务服务异步消费。房间内的消息广播用的是 Netty 的 ChannelGroup 机制。每个房间对应一个 ChannelGroup玩家加入房间后把他的 Channel 添加到这个组里。当要广播某个消息时调用 ChannelGroup.writeAndFlush() 就能推送给房间内所有在线玩家。这里要特别注意线程模型Netty 的 IO 线程不能直接处理耗时业务逻辑否则会阻塞其他连接的消息收发。我的做法是Netty 的 handler 只负责序列化和转发真正的牌局逻辑通过 Redis 队列抛给后台线程池执行执行完的结果再通过一个 response channel 推回给 Netty 层Netty 层再广播给玩家。断线重连这块踩了不少坑。玩家客户端从 Wi-Fi 切到 4G或者小程序进入后台再回来WebSocket 连接都会断开。如果断开后不做任何处理玩家就会掉出牌桌甚至可能导致房间因为人数不足而解散。我的方案是网关在检测到连接断开时不立即删除用户的会话绑定而是启动一个 30 秒的重连等待窗口。在这个窗口内如果有新的连接带着同一个 player_id 和 token 进来就直接复用之前的会话上下文把新的 Channel 替换到房间的 ChannelGroup 里同时向其他三家广播某某玩家重新连接成功。如果 30 秒内没重连再执行掉线处理把玩家标记为托管状态由服务器自动出牌保证牌局能继续推进。心跳机制也是必须做的。小程序端每隔 15 秒发送一次 pingNetty 收到后回一个 pong如果连续 3 次没收到 ping就判定连接已死触发断线流程。这里要说明的是不能用 TCP 自身的 keepalive因为小程序在移动网络下超时时间难以控制App 层的应用心跳反而更可靠。8. 前端接口对接与数据交互规范后端开发过程中每天都要和小程序前端打交道。很多后端开发的痛点是接口明明写好了前端却告诉我数据是空的或者前端拿到数据了但渲染不出来。这背后多半是数据交互规范没定清楚。这个项目里我沉淀了一套自己的接口约定能明显减少前后端联调时的扯皮。先约定统一的响应结构。所有 HTTP 接口的返回值必须是固定的 JSON 格式包括 code、message、data 三个字段。code 为 0 表示成功非 0 表示各种业务错误码比如 1001 表示登录态过期、1002 表示房间不存在。前端可以根据这个 code 做统一拦截不用每个接口单独判断。这个约定看似老生常谈但实际项目中很多团队不重视导致前端每个接口都要写一套错误处理逻辑。接口的命名和请求方式也要统一。我建议所有查询类接口用 GET所有修改类操作用 POST请求参数统一用 JSON body 而不是 form 表单。对于带状态的接口比如出牌、碰杠必须在请求参数里带上当前客户端的 seq 序号这个 seq 同时用于后端做并发校验和消息去重。永泰麻将里很容易出现的情况是玩家网络延迟点了一次碰界面还没刷新又下意识点了一次碰前端如果不做按钮防抖就会向后端发送两个相同的碰请求。后端除了靠 seq 去重我还会在业务层增加一个操作时效校验只有当前等待响应窗口内的操作才合法窗口外的操作直接丢弃并返回操作已失效。关于数据格式时间字段统一用时间戳或者 ISO8601 字符串不建议用2024-01-01 12:00:00这种文本格式因为前端在不同系统上解析格式容易出问题。金额相关的字段统一用整数分单位存储不要用浮点数这是金融和游戏项目的老生常谈浮点数在计算房价时会出精度问题比如 0.1 加 0.2 不等于 0.3用整数分就不会有这个问题。还要考虑微信小程序特有的限制。小程序请求的 URL 必须在微信公众平台后台配置合法域名开发阶段可以在开发者工具里勾选不校验合法域名。如果后端要对接 HTTPS 证书记得配置好 SSL 证书不能用自签名证书否则小程序端会直接报错。小程序对 HTTP 状态码的处理也有坑微信的 wx.request 在收到 4xx 或 5xx 状态码时不会走 success 回调而是走 fail 回调前端如果只处理 success就会误以为网络错误。所以后端最好不要依赖 HTTP 状态码来表达业务错误一律通过 HTTP 200 code 字段来区分业务状态。9. 常见问题排查与线上排错技巧这个项目做完我总结了一批很典型的坑每一位做棋牌后端的朋友大概率都会遇到。按出现的频率和排查难度排个序分享几个最有价值的。第一个坑是前端显示白屏或者数据加载失败。排查步骤可以这样走先看小程序的调试器 Network 面板有没有发出请求如果没发请求多半是合法域名没配置或者没勾选不校验合法域名如果请求发出去了但 response 为空用抓包工具看返回的具体内容多半是后端返回了非正常 JSON 导致解析失败如果返回了正常 JSON 但页面还是白屏可能是前端渲染逻辑的问题。有一个容易被忽略的点微信开发者工具和真机的表现经常不一致拿 uniapp 或原生小程序开发时经常遇到工具上正常、真机白屏的情况很多是 ES6 语法或者 CSS 兼容问题这种只能靠真机调试逐步定位。第二个坑是跨域问题。小程序端其实不存在浏览器那种 CORS 跨域限制所以不需要在后端配跨域过滤器。但如果你在联调阶段用 H5 页面或者本地开发工具去调后端接口就会遇到跨域。我的做法是Spring Boot 里配置一个全局 CORS 过滤器只在 dev 环境启用生产环境关闭。这样既不影响线上安全性也能提升本地联调效率。第三个坑是并发下房间人数超卖。多个玩家同时通过房间号加入同一个房间如果不加控制可能出现第 5 个人也成功进入房间。Redis 的原子操作可以解决这个问题用 Lua 脚本判断当前房间人数小于上限时原子地执行人数加一并把玩家加入房间成员列表。这个操作必须是原子的不能先查后写否则就会超卖。第四个坑是关于抓包的。小程序端默认走 HTTPS直接在 Charles 或 Fiddler 里抓包只能看到加密流量。想要解密就得在手机上安装抓包工具的证书并且开启相应权限。现在 Reqable 这个工具对小程序抓包支持得不错还支持直接抓 WebSocket 帧对于排查牌局消息推送问题非常有用。如果要抓小程序发起的请求务必先把小程序的不校验合法域名开关打开并确保手机和电脑在同一局域网。实际操作中还有一个方法就是利用小程序端的真实环境用小程序的真机调试功能配合后端的日志框架做排查这比纯抓包效率更高因为后端日志里能带上完整的业务上下文。第五个坑是正在查询有效的后端这类提示。我在项目里遇到过小程序端提示找不到后端服务但实际上后端服务和数据库都正常。排查后发现是 Redis 连接池满了导致业务服务无法从 Redis 读取房间状态从而拒绝响应。这里的关键经验是棋牌服务对 Redis 的依赖极高Redis 一旦抖动所有牌局操作都会异常。所以生产环境一定要给 Redis 配置哨兵或集群模式并在业务代码里加缓存降级逻辑比如 Redis 不可用时直接读 MySQL 的最近状态快照。最后一条排错经验棋牌类项目一定要把日志打好。我在每次出牌、碰杠、胡牌、结算的入口和出口都打印了结构化日志包含玩家 ID、房间 ID、操作类型、操作前状态、操作后状态。对账的时候把 actions_log 拉出来逐条重放很多看起来不可能发生的 bug 都能当场定位。日志的代价只是一点点磁盘空间但排查问题的效率提升是几倍的。10. 部署上线与压测心得开发完成后部署和压测是决定项目能否稳定运行的最后一公里。棋牌项目对可用性的要求是玩到一半不能崩所以上线前的稳定性和容灾预案必须做到位。部署上我推荐用 Docker Compose 管理整套服务。项目里包含 nginx、后端 API 服务、WebSocket 网关、MySQL、Redis 五个容器docker-compose.yml 里把每个服务的镜像、端口映射、数据卷、环境变量都定义好一台 4 核 8G 的云服务器就能跑得非常稳。nginx 负责对外提供 HTTPS 入口把 /api/ 前缀的请求反代给 Spring Boot把 /ws/ 前缀的升级请求反代给 Netty。这里需要特别叮嘱的是nginx 到 Netty 的 WebSocket 代理要配置适当的超时时间比如 proxy_read_timeout 和 proxy_send_timeout 至少设置 60 秒否则容易把长连接断开。数据库的初始化脚本要纳入版本管理不能靠手动去数据库执行。我建议每次发布前先跑 git diff 看 SQL 变更然后在数据库上执行迁移脚本。如果项目里用到 MyBatis-Plus可以让程序启动时自动执行 schema.sql 和 data.sql但生产环境还是建议手动控制数据库变更避免程序启动时误操作。压测部分我用了 Apache JMeter 做 HTTP 接口压测用自己写的 WebSocket 客户端脚本模拟多玩家并发出牌。关键要压出三个数据登录接口的 QPS 上限、创建房间接口的并发上限、WebSocket 网关在 500 个连接同时收发消息时的延迟分布。压测结果出来后重点关注 95% 和 99% 延迟平均值好看没有意义极端情况下的延迟才是用户真正的体感。另外牌局里的操作延迟应该控制在 100ms 以内超过 300ms 就会出现明显的卡顿感。实测中4 核 8G 的服务器扛 500 人同时在线约 125 桌CPU 使用率在 60% 左右还有一定的余量。压测中发现的典型问题是一开始 WebSocket 网关线程模型配置不当线程数设得太大导致频繁的线程上下文切换性能反而下降了。后来把 bossGroup 线程数设为 1、workerGroup 线程数设为 CPU 核数的两倍并把业务处理线程池单独隔离出去性能才稳定下来。压测一定不要只测单接口要模拟完整的业务流程才能发现真实的瓶颈。11. 从 0 到 1 打包交付这个 zip 包的完整复盘回过头来看福州永泰麻将微信小程序后端.zip这个压缩包它其实代表了一类很典型的外包交付物一个地方棋牌微信小程序的完整后端服务。在没有给到具体代码的情况下写这篇复盘是想把这些不走一遍就学不到的经验记录下来而不是把代码贴一遍就完事。这类项目的难点从来不在于能用什么框架或者调什么接口而在于怎么把真实业务规则翻译成可靠的技术方案。永泰麻将的规则、微信小程序的登录交互、WebSocket 长连接管理、MySQL 和 Redis 的配合、前端联调的数据规范每一个模块单独拿出来都不算复杂但它们组合在一起时各种边界问题和并发问题就开始冒头了。我个人的体会是棋牌后端没有银弹没有哪个框架能帮你自动完成牌局规则和结算逻辑这些都是要靠自己一行一行代码写出来、一点一点测试测出来的。如果你正准备接手一个类似的棋牌项目有几件事一定要做在前面。第一把玩法规则文档拿给客户或产品确认白纸黑字签字不然后期改规则会让你改到怀疑人生。第二一定要留出足够的时间做对局回放和对账工具这是你排查问题、仲裁争议的重要武器。第三提前约定好前端的数据协议和数据格式联调时才不会每天因为字段名和数据类型扯皮。第四不要忽略模拟高并发场景下的长时间稳定性测试很多 bug 是运行很久之后才出现的比如内存泄漏、连接泄漏、定时任务积累等。这个项目做完之后我还做了一系列扩展把 Netty 网关和 Spring Boot 业务服务拆开独立部署支持水平扩容把对局回放的 actions_log 数据接入到简单的数据分析看板可以统计每张牌的胜率、玩家习惯等。如果你做的棋牌项目想走向更大赛道这些方向都可以继续深挖。但先把基础版本稳定跑起来永远是第一步。本文还有配套的精品资源点击获取