从状态机到底池：Java 实现 Slack 德州扑克 Bot 源码拆解

简介：开源项目slack-poker-bot以Node.js构建，将Slack聊天平台变为可实时对弈的德州扑克客户端，支持2至10名玩家在任意频道或私人群组中发起牌局。面向具备JavaScript基础的中高级开发者、机器人应用设计者以及对棋牌算法感兴趣的编程爱好者，既能用于学习Slack Bot集成与事件驱动架构，也是剖析扑克牌型判定和博弈逻辑的参考样本。压缩包共84个文件、约1.71MB，主要由24个js脚本构成核心业务逻辑，52张png图片负责牌面视觉资源，其余为json、md配置说明及测试文件，其中js脚本覆盖牌桌管理、手牌评估、底池清算等独立功能模块，整体组织清晰，便于按模块查阅。已有464人浏览学习，具备实际参考意义。项目完整覆盖发牌、底牌私密发送、玩家行动轮询、胜者判定与底池清算全流程，并内置不同风格的AI机器人（弱智能与激进型）及配套测试用例，能够帮助读者快速理解德州扑克规则在代码中的落地方式，为二次开发或相关课程设计提供可直接复用的基础。

1. 把 Slack 当牌桌：java-slack-poker-bot 源码里藏着的不只是发牌器

这份 java-slack-poker-bot 源码，拆开之后最大的感受是：它根本不是一个“发牌小工具”，而是一套能够把 Slack 当牌桌用的完整后端骨架。你在频道里输入/poker-start，Bot 会拉起六人局，盲注、轮转、加注、公共牌翻到第五张，最后比牌分锅，整个过程都跑在 Slack 的消息回调里。它适合三类人：拿 Java 做课设但不想写普通 CRUD 的人；团队内部想在工作区组一桌、但不想单独部署 Web 游戏的人；以及想理解“Bot 型棋牌后端”和常规棋牌后端差异的工程师。读完这份源码，你会对状态机流转、回调时序和底池拆分有非常具体的认知，而不是停留在“德州扑克就是比牌大”的层面。

2. 牌局先建模成状态机：回合、盲注与底池在 Java 里的流转方式

2.1 为什么牌局阶段要用枚举而不是布尔开关

拿到任何棋牌类源码，我第一件事就是找 GameState 或 Phase。这份源码里用的是枚举，而不是一堆isPreflop、isFlop布尔变量。原因很简单：德州扑克的阶段是严格单向推进的，从等待盲注到翻前、翻后、转牌、河牌、摊牌，中间不允许跳跃，也不允许回头。如果用布尔变量，程序很容易出现“既是翻前又是翻后”的非法状态，而这些状态在并发回调里特别难查。

常见做法是定义一个GamePhase枚举，并且把“合法转移”收敛到一个方法里：

public enum GamePhase { WAITING_BLINDS, PREFLOP, FLOP, TURN, RIVER, SHOWDOWN; public GamePhase next() { return switch (this) { case WAITING_BLINDS -> PREFLOP; case PREFLOP -> FLOP; case FLOP -> TURN; case TURN -> RIVER; case RIVER -> SHOWDOWN; case SHOWDOWN -> throw new IllegalStateException("对局已结束，不能继续推进"); }; } }

switch 表达式的意思是：每个阶段都有且只有一个后继阶段。你不需要记得在任何地方判断“当前能不能发牌”，只要调用phase.next()，合法就前进，非法就直接抛异常。这个设计把状态转移的逻辑收拢到一处，后面加新阶段也只需要改这里。

参数上要注意一点：WAITING_BLINDS不是真实的发牌阶段，它只是“等待玩家入座并支付盲注”的中间态。很多新手会把盲注当成一个动作，但实际上盲注是强制筹码，由 Dealer 按钮位左边的两名玩家出，进入 PREFLOP 之前必须先收集完。源码里如果盲注没齐就推进到下一阶段，基本都会在这里出问题。

2.2 先读这五个类：快速定位项目主干

刚开始看这份源码的时候不要从头读到尾，我建议按下面五个类来抓主干。它们基本覆盖了一条完整牌局的生命周期。

Card和Deck是最容易读懂的。GameState常常是一个不可变对象，或者至少把字段设计成只能通过GameEngine修改。这样做的价值有两个：第一，回调线程拿到的状态不会在读取过程中被另一个线程改掉；第二，调试的时候可以方便地把整个状态对象打出来看。我拆这份源码时习惯在GameEngine.applyAction()入口打一行日志，格式类似阶段=FLOP 玩家=alice 动作=RAISE 下注=200 底池=1500，排查问题会非常高效。

GameState里通常还会有smallBlind与bigBlind两个字段。这两个值既是盲注大小，也决定了轮转顺序。翻前从大盲位左侧玩家开始行动，翻后从庄家左侧未弃牌玩家开始。如果你发现 Bot 的行动顺序不对，九成问题出在这里而不是在行动分发逻辑里。

2.3 玩家行动与底池：所有下注动作收敛到一个入口

行动模型上，德州扑克的合法动作只有 FOLD、CHECK、CALL、RAISE、ALL_IN 五种。源码里最好不要让每个方法直接去改底池数值，而是设计一个统一的PlayerAction入口，由Pot类负责扣筹码和加彩池。我见过很多改版把raise逻辑散落到 Slack 回调里，最后统计时发现筹码数量对不上，非常难查。

public record PlayerAction(String playerId, ActionType type, int amount) {} public class Pot { private final int[] sidePots = new int[4]; private int mainPot; public void commit(int playerId, int chips) { if (chips <= 0) { throw new IllegalArgumentException("下注金额必须大于 0"); } mainPot += chips; } public void splitForAllIn() { // 以本轮最小 all-in 筹码为界，把超出部分划分到 sidePot sidePots[0] = computeSidePot(0); } }

record类型是 Java 17 以后的常见写法，四个字段分别是玩家 ID、动作类型和下注额。把所有动作都走commit方法之后，底池就只有一个入口，后续做日志、回放、统计都会轻松很多。

这里必须提一个容易翻车的地方：边池。德州扑克里如果有人 all-in 而其他人继续下注，超出 all-in 金额的那部分筹码要放进边池，等所有牌发完后，主池和边池分别比较对应玩家的手牌。源码里如果只维护一个mainPot，那 all-in 场景下筹码分配必错。后面我会专门讲这个坑。

3. 从 Slack 指令到 Bot 行动：回调、权限与 3 秒应答边界

3.1 Slack App 侧要开哪些权限

要让这个 Bot 跑起来，先要去 Slack 创建应用，这一步虽然不写代码，但配置错了后面全白搭。基本流程是：打开 api.slack.com/apps，新建一个 App，然后到 “Slash Commands” 页面添加/poker-start、/poker-join、/poker-action这几个指令。每一条指令的 Request URL 都要指向你的 Bot 后端。

再到 “Event Subscriptions” 开启事件订阅，填写回调地址。Bot 要能回复消息、发送牌面、更新消息，还需要在 “OAuth & Permissions” 里配置 Bot Token Scopes。常用的权限有chat:write（发送消息）、commands（处理斜杠指令）、channels:history（读取频道历史，有时用于恢复断线牌局）。如果要在私聊里玩，还要加im:history和im:write。

配置完成后，把应用安装到工作区，复制 Bot User OAuth Token。这个 Token 是你在 Java 项目里调用 Slack Web API 的凭证，一般通过环境变量注入，不建议硬编码进源码。部署的时候还要注意：Slack 要求回调地址是公网可达的 HTTPS 地址，本地调试可以用内网穿透工具把本机端口暴露出去。我第一次调试时没注意“HTTPS 必须有效证书”这个限制，用了一个自签名证书，结果 Slack 回调一直失败。

3.2 回调服务器怎么区分事件和命令

Slack 有两种入站请求，格式完全不同：Event Subscription 发的是 JSON，Slash Command 和按钮交互发的是application/x-www-form-urlencoded，真正的数据放在payload=字段里。很多人在本地快速写了路由，只解析了 JSON，结果一按按钮就看到 Slack 弹出 “Something went wrong”。

protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException { String rawBody = new String(req.getInputStream().readAllBytes(), StandardCharsets.UTF_8); // 按钮交互和 Slash Command 走表单编码，payload 字段内是 JSON String jsonBody = rawBody.startsWith("payload=") ? URLDecoder.decode(rawBody.substring(8), StandardCharsets.UTF_8) : rawBody; JsonNode json = new ObjectMapper().readTree(jsonBody); // 第一次配置 Event Subscription 时，Slack 会发送 challenge 做校验 if (json.has("challenge")) { resp.setContentType("text/plain"); resp.getWriter().write(json.get("challenge").asText()); return; } // Slash Command 请求必然包含 command 字段 if (json.has("command") && "/poker-start".equals(json.get("command").asText())) { String channelId = json.get("channel_id").asText(); executor.submit(() -> gameManager.startTable(channelId)); resp.setContentType("application/json"); resp.getWriter().write("{\"response_type\":\"in_channel\",\"text\":\"牌桌已创建，发送 /poker-join 入座\"}"); return; } resp.setStatus(404); }

这段代码有四个关键点。第一，rawBody.startsWith("payload=")判断的是表单编码请求；第二，URLDecoder.decode要把 URL 编码后的 JSON 还原出来；第三，challenge校验的响应必须是纯文本，不能带引号也不能包一层 JSON，我见过有人返回"challenge":"xxx"导致校验失败的；第四，Slack 要求 Slash Command 在 3 秒内返回 HTTP 响应，所以实际耗时的动作（建桌、洗牌、发牌）必须丢到线程池异步执行，主线程只返回一条提示消息。

response_type参数也值得说明。in_channel表示消息对频道内所有人可见，ephemeral表示只有触发指令的人能看到。起手阶段建议用ephemeral返回“你已入座”，等牌局正式开始再发公开消息，否则频道会被刷屏。

3.3 本地跑通需要哪些环境变量和日志

这份 Java 源码在本地跑，一般需要三个环境变量：SLACK_BOT_TOKEN用于调用 Web API 发消息，SLACK_SIGNING_SECRET用于校验请求签名，SERVER_PORT指定本地监听端口。如果你用的是 Spring Boot，这些通常直接放application.yml里；如果是普通 Servlet 项目，就要在启动脚本里 export。

签名校验很容易被跳过，但我不建议跳。Slack 的签名头部包含时间戳和 HMAC-SHA256，校验失败直接拒绝请求。否则任何人都能往你的回调地址 POST 假指令，Bot 会被打出一堆奇怪的牌局状态。源码里如果已经有SlackRequestVerifier之类的类，打开它确认是否真的启用了。调试期可以临时关闭，但上线务必打开。

日志方面，除了常规的请求日志，一定要把 Slack 返回的 HTTP 状态码打到日志里。我之前遇到过一个诡异问题：Bot 能发消息，但一处理按钮交互就卡住，查了半天才发现是权限 scope 没配全，Slack API 返回了 403。这类问题看回调日志比猜代码快得多。

4. 手牌评估器深读：从 7 张牌变成可比较数字的完整路径

4.1 牌编码与排序：先做花色频率再做点数频率

手牌评估是德州扑克源码里最容易被低估的部分。很多人以为写一个isRoyalFlush()就行，实际上评估器要拿 7 张牌（2 张手牌 + 5 张公共牌）选 5 张组合，还要在牌型相同时比踢脚。最稳妥的实现不是列举 21 种组合，而是把 7 张牌的点数频率统计出来，再按牌型优先级判断。

先看牌面怎么编码。这份源码里的做法是用枚举表示点数和花色，点数的范围是 2 到 14，其中 14 代表 A。花色用 0 到 3 表示，也可以直接用字符。数据库或者序列化时，整点数比字符串快得多，所以不少源码用value % 13表示点数、value / 13表示花色。

private static int evaluate7(Set<Card> seven) { int[] rankCounts = new int[15]; int[] suitCounts = new int[4]; for (Card c : seven) { rankCounts[c.rank()]++; suitCounts[c.suit()]++; } boolean flush = false; for (int count : suitCounts) { if (count >= 5) { flush = true; break; } } boolean straight = hasStraight(rankCounts); int pairCount = 0, threeCount = 0, fourCount = 0; for (int i = 2; i < rankCounts.length; i++) { if (rankCounts[i] == 4) fourCount++; else if (rankCounts[i] == 3) threeCount++; else if (rankCounts[i] == 2) pairCount++; } return buildScore(flush, straight, fourCount, threeCount, pairCount, rankCounts); }

这段代码的逻辑是：先统计四种花色各自的数量，判断有没有同花；再统计每个点数的出现次数，判断对子、三条、四条。buildScore会把这些信息编码成一个可比较的大整数，方便做排序。

buildScore的具体实现一般是按“牌型权重 × 关键点数”来算。比如同花顺的权重是 8，四条权重是 7，葫芦 6，同花 5，顺子 4，三条 3，两对 2，一对 1，高牌 0。权重相同的时候，再比较关键牌的点数。这套逻辑的边界条件很多，后面讲测试时再细说。

4.2 同花、顺子与葫芦：判定顺序决定了会不会误判

判定顺序上有个常见的坑：同花顺必须同时满足同花和顺子，所以在代码里应该先判断flush和straight，再组合成straightFlush。如果先判断顺子并提前返回，后面同花顺就没机会被识别了。

顺子的判定要看 A 的特殊性。A 可以当作 14，也可以当作 1，组成 A-2-3-4-5 这条最小的顺子。所以标准做法是判断rankCounts时同时检查 14、2、3、4、5 这五个位置是否有牌。如果直接写成“从 2 到 14 找连续五个”，会漏掉最小的顺子。

private static boolean hasStraight(int[] rankCounts) { for (int high = 14; high >= 5; high--) { boolean found = true; for (int j = 0; j < 5; j++) { if (rankCounts[high - j] == 0) { found = false; break; } } if (found) { return true; } } return rankCounts[14] > 0 && rankCounts[2] > 0 && rankCounts[3] > 0 && rankCounts[4] > 0 && rankCounts[5] > 0; }

return分支里额外判断了 A-2-3-4-5。这段逻辑是评估器的核心之一，建议单独写测试，把所有可能的顺子边界（5-6-7-8-9、10-J-Q-K-A、A-2-3-4-5）都跑一遍。只要顺子识别不对，后面的同花顺和皇家同花顺全跟着错。

葫芦的判定也有细节：它需要有一个三条加一个对子。有些新手会把三条单独返回，导致葫芦被降级成三条。在buildScore里，要先判断threeCount >= 1 && pairCount >= 1，再判断纯三条。同理，两对和一对的顺序也要注意，否则低牌型会覆盖高牌型。

4.3 踢脚比较：为什么同等级牌型不能只比“对子大小”

德州扑克里最容易被忽略的是踢脚。当双方都是 A 对子时，剩下的三张牌按从大到小逐张比较，决定谁赢。所以评估器返回的分数不能只包含牌型等级，还要包含按序排列的关键牌点数。源码里常见做法是：先按点数出现次数排序，次数相同再按点数大小排序，然后把这个序列拼进分数。

private static int[] kickerOrder(int[] rankCounts) { return IntStream.rangeClosed(2, 14) .boxed() .sorted(Comparator .comparingInt((Integer r) -> rankCounts[r]).reversed() .thenComparing(Comparator.reverseOrder())) .mapToInt(Integer::intValue) .toArray(); }

这里第一层排序按出现次数降序，次数多的大牌排前面；第二层排序按点数降序。比如双方都是两对，先比高对，再比低对，最后比单张，正好符合德州扑克规则。

有一点要注意：rankCounts[1]通常是 0，因为 A 被映射到了 14，所以IntStream.rangeClosed(2, 14)直接跳过下标 1。这个细节如果没做对，A 会被错误地排除在踢脚比较之外。

4.4 用测试用例堵住评估器边界

评估器是所有逻辑里最值得写测试的部分。我一般会把下面几组用例固定下来：皇家同花顺（10-J-Q-K-A 同花）、最小的 A-2-3-4-5 顺子、同花顺与普通顺子的边界、葫芦与三条的差异、两对与一对的差异、以及完全相同的公共牌面下踢脚 A 压过 K。每一组都用一个断言去检查evaluate7的结果。

@Test void straightFlushBeatsFullHouse() { Hand straightFlush = readHand("h6 h7 h8 h9 h10"); Hand fullHouse = readHand("d9 d9 d9 s5 s5"); assertTrue(evaluate(straightFlush, new Card[0]) > evaluate(fullHouse, new Card[0])); }

测试的价值在于：一旦你改了编码方式或者优化了排序算法，立刻能知道哪条规则被破坏。德州扑克的评估器逻辑是纯函数，输入 7 张牌输出一个数值，没有外部依赖，是整套源码里最容易做到高覆盖测试的部分。我拆 Java 棋牌源码时，如果发现评估器没有配套测试，会下意识觉得项目的成熟度存疑。

5. 运行与部署避坑：五个值得把日志打出来的翻车案例

5.1 Slack Events API 校验总是失败，报 URL verification failed

现象：在 Slack 后台配置回调地址后，点击保存一直提示无法验证 URL。

原因：Slack 发送的 challenge 请求到达服务器时，如果你返回的不是一个纯文本 challenge，而是 JSOB 序列化后的对象，或者返回内容带引号，Slack 都会校验失败。还有一种是路由写错了，/slack/events路径没有对应处理器，返回了 404。

解决：在doPost里最先判断json.has("challenge")，然后直接resp.getWriter().write(json.get("challenge").asText())，不设置application/json，就用text/plain。同时确认注册 URL 和本地路由完全一致。我第一次调试时 URL 写成了/slack/events/，带着尾部斜杠，本地路由只注册了/slack/events，查了很久才发现是路径不匹配。

5.2 点击按钮后 Bot 完全没有反应

现象：玩家点击“加注”或“弃牌”按钮，Bot 没有回复，后台也没有任何日志输出。

原因：Slack 的按钮交互请求是表单格式，body 是payload=...，而不是裸 JSON。如果你只解析 JSON，readTree会抛异常，HTTP 状态码变成 500，Slack 端就会显示错误提示。另外，如果你的 handler 没有在 3 秒内返回 200，Slack 会认为请求失败并重试或放弃。

解决：进路由之后，先判断Content-Type或rawBody.startsWith("payload=")，用URLDecoder.decode取出 JSON。然后立刻返回200，把实际的下注计算丢给线程池。记住 Slash Command 的响应是同步的，异步处理是必须的，不是优化选项。

5.3 连续两局发牌顺序完全相同

现象：开第二局时，发现前五张公共牌和上一局一模一样，或者手牌排列顺序没有变化。

原因：源码里的Deck实例在牌局结束后没有销毁，而是被复用。Collections.shuffle()默认使用Random，如果两个Deck实例在同一毫秒内初始化，随机种子会相同，洗牌结果自然一样。这在高频创建牌桌时容易触发。

解决：每一个GameState都新建一个Deck，不要做成单例。如果项目只是为了本地演示，可以直接用new SecureRandom()传给shuffle，或者至少显式传入一个种子。从线上稳定性角度看，Random在高并发下还会产生可预测性问题，棋牌类项目如果涉及真钱，必须换成加密安全的随机源。

5.4 玩家 all-in 后底池分配错误

现象：三人局，A 全下 200，B 和 C 各自下注 500，最后摊牌时 B 赢了，但底池分给 C 的筹码数量不对。

原因：源码里所有筹码都放进了同一个mainPot，没有在 all-in 发生时切分边池。德州扑克规则中，超过 all-in 金额的部分要单独形成边池，只有参与了该边池的玩家才有资格赢走它。如果只算总底池，all-in 玩家会分到本不该属于他的筹码。

解决：在PlayerAction处理ALL_IN时，找到当前最小有效筹码量，把超出部分划到sidePots[1]，原主池保留到 all-in 玩家的下注总和。对方不仅需要Pot支持splitForAllIn()，还需要在摊牌阶段分别对主池和各个边池做比较。

5.5 Maven 编译报 “警告: 源发行版 17 需要目标发行版 17”

现象：在本地执行mvn package，编译过程中出现 JDK 版本相关警告，甚至直接编译失败。

原因：pom.xml里的maven.compiler.source和maven.compiler.target被设置成了 17，但本机没有安装 JDK 17，或者当前使用的 JDK 是 11。Slack Java SDK 在某些版本下要求 Java 11 或者 17，这个版本差异会把编译直接挡在门外。

解决：先java -version确认当前 JDK 大版本，再检查pom.xml里的maven-compiler-plugin配置。如果是 JDK 11 环境，把 source/target 改成 11，并且确认依赖库版本兼容；如果必须用 17，就安装对应 JDK 并设置JAVA_HOME。这个坑本身不复杂，但报错信息很容易让人去查代码而不是查环境。

6. 四个改动让机器人更耐玩：超时托管、并发对局与牌史统计

6.1 超时自动弃牌，避免牌局卡死

真实牌局里玩家可能打完指令就不看了，不处理超时的话牌局会永远卡在一个阶段。常见做法是在每个GameState里挂一个ScheduledExecutorService的延迟任务，超过 60 秒没有动作就自动执行 FOLD。注意要在每次合法动作后取消旧任务并重新调度，否则会出现“玩家刚加注完就被超时弃牌”的乌龙。

public void scheduleTimeout(GameState state) { timeoutFuture = scheduler.schedule(() -> { if (state.phase() != GamePhase.SHOWDOWN) { gameEngine.applyAction(state, PlayerAction.fold(currentPlayer(state))); } }, 60, TimeUnit.SECONDS); }

6.2 多桌并发：用channelId做隔离

Slack 上不同频道可以同时开牌局，如果GameEngine只有一个全局状态，两个频道会互相干扰。标准做法是用ConcurrentHashMap<String, GameState>，以频道 ID 作为 key 隔离每桌。这样每个频道的牌局互不可见，也不会出现 A 频道玩家的动作影响到 B 频道。

6.3 牌史统计：把每手牌落成 JSON 日志

调试和复盘的时候，二进制日志很难翻。我习惯在每局结束时，把玩家手牌、公共牌、下注序列、底池分配结果拼成一个 JSON 字符串写进日志文件。这个改动对玩法本身没有影响，但对查边池 bug 和胜率计算帮助巨大。

6.4 评估器回归测试：每次改动都跑一遍

评估器是纯函数，非常适合做回归测试。把上一章的测试用例全部放进src/test/java，每次改完洗牌或编码逻辑就mvn test。只要测试全绿，就说明基础牌型判断没有坏。

这份源码拆到最后，留给我最深的一个习惯是：凡是棋牌类项目，先把状态机、边池、随机源三件事理清楚，再谈功能扩展。从那以后我拿到任何 Java 版棋牌源码，都会先翻它的GamePhase和Pot，确认它们没有把状态散落在各个回调里，再决定要不要继续读下去。希望这些拆解和踩坑记录能帮到你。

本文还有配套的精品资源，点击获取