简介：Gin-Rummy-Card-Game是一份基于Java实现的杜松子酒接龙纸牌游戏源码，面向Java入门者、课程设计学生以及棋牌类游戏爱好者。项目完整覆盖了经典规则中的发牌、组牌、跑动和设置组合判定，并设计了可自动决策的机器人对手，便于学习回合制对战程序与基础AI策略。压缩包共163个文件，体积约1.44MB，主要包含15个Java源文件、18个class编译文件、108个gif演示图片、以及XML配置和jar依赖库等。其中Card、Deck、Hand、CardSet等类清晰展示了面向对象建模思路，gif文件可直观观察牌局界面与出牌交互过程。资源已有214人学习，适合用来研究纸牌游戏的数据结构设计、手牌匹配算法、机器人决策逻辑，以及Java图形界面开发。通过阅读源码和运行测试，读者能掌握完整的小型游戏项目从编码到调试的流程，并可作为后续扩展双人联机或AI难度的参考基础。
1. Gin-Rummy-Card-Game 在做什么：一张被低估的算法练手题
Gin-Rummy-Card-Game 是把双人纸牌游戏金拉米从现实规则搬进代码的一次完整练习。它不追求画面，核心是把 52 张牌的编码、回合状态机、牌型检测、死牌计分和对手 AI 装进一个能跑通、能测试、能复现的小项目里。对想做课程设计又不想烂大街的人，它比贪吃蛇有深度，比象棋引擎好收尾。
我接这类需求时最常被问的问题是“规则这么简单，代码能写多长”。答案是：规则段落确实短，但把拆牌、算死牌、出牌防守三个子问题写清楚，通常要一千行往上。这篇内容从数据建模讲起，到可跑的回合循环、AI 和回归测试收尾，代码都直接可复现，适合想一次做完、不留半成品的开发者。
2. 先把规则变成数据：牌、手牌与牌型的建模方式
2.1 用 0–51 的整数编码一张牌：调试友好和判等简单
初学者最容易犯的第一个错，是用字符串表示牌，比如"♠A"或"A♠"。字符串确实好读，但接下来所有逻辑都要跟字符串解析打交道：比大小要先切字符、判花色要先看后缀、排序要写自定义 key。更麻烦的是"7S"和"7♥"这种肉眼能区分、程序却要额外判断的字符串，出错率极高。
我一般直接用 0–51 的整数编码，规则只有两条：cid // 13是花色，cid % 13是点数。这样的好处是判等就是整数判等，排序就是整数排序，调试时再用一个纯函数转回可读牌面即可。
RANKS = "A23456789TJQK" SUITS = "SHDC" # S=黑桃, H=红心, D=方块, C=梅花 def card_str(cid: int) -> str: """把 0-51 的牌编码转成可读牌面，日志和调试时用。""" return RANKS[cid % 13] + SUITS[cid // 13] def deadwood_value(cid: int) -> int: """死牌分：A=1，2-9 照面值，10/J/Q/K 都是 10 分。""" rank = cid % 13 if rank == 0: return 1 if rank >= 10: return 10 return rank + 1参数说明：RANKS里把 10 记作T，是为了保证所有牌面都是两个字符，card_str("TS")就是 10 黑桃，日志对齐好看。deadwood_value是后面所有 AI 决策的地基，计算时只依赖cid % 13，跟花色无关，所以写成一个独立函数而不是散落在各处。
这里有一个容易被忽略的点：按cid排序是“花色优先、点数其次”，但判断顺子时需要“点数连续、花色相同”，所以排序 key 要写成( cid // 13, cid % 13 )而不是直接sorted(hand)。我在这个细节上吃过亏，后面避坑章会再展开。
2.2 手牌、牌堆与弃牌堆：回合状态机的最小字段
金拉米的完整状态其实只有四样东西：两个玩家的手牌、未翻开的牌堆、弃牌堆、当前轮到谁。把这四样装进一个 dataclass，整个游戏就能任意保存、加载、回放。这也是“可测试”的前提，因为每个测试用例都可以直接构造一个GameState实例。
from dataclasses import dataclass, field @dataclass class GameState: hands: list[list[int]] # 两个玩家的手牌，hands[0] 是当前回合玩家 stock: list[int] # 牌堆，从列表尾部摸牌 discard: list[int] # 弃牌堆，顶牌在列表尾部 turn: int # 0 或 1，轮到他行动 knocked: bool = False # 本回合是否已有人敲桌 scores: list[int] = field(default_factory=lambda: [0, 0])选stock和discard都用“列表尾部当顶”而不是头部，是因为pop()和append()都是 O(1)，摸牌、弃牌时不用pop(0)那种 O(n) 操作。knocked这个布尔值很多人会漏掉：它标记本回合是否已经结束，否则状态恢复时无法区分“还没人敲”和“已经敲完在计分”。
实战里建议把GameState当成纯数据类，所有改状态的逻辑都放到GinRummyGame的方法里，而不是让 AI 直接改hands。这样后续写 AI 的时候，AI 只负责“决策”，不负责“执行”，逻辑边界清楚，出 bug 也好定位。
2.3 拆牌与算死牌：点数分组和同花顺子两条路
金拉米的牌型只有两种：同点数的一组（三张或四张），同花色连续的三张以上。拆牌算法就是在这两种牌型里做组合搜索。先写两个检测函数，一个处理组、一个处理顺。
def find_sets(hand): """找三张或四张同点数，不考虑花色。""" by_rank = {} for c in hand: by_rank.setdefault(c % 13, []).append(c) return [tuple(cards) for cards in by_rank.values() if len(cards) >= 3] def find_runs(hand): """找同花色、点数连续的三张及以上。""" runs = [] for suit in range(4): ranks = sorted({c % 13 for c in hand if c // 13 == suit}) seq = [] for r in ranks: if seq and r == seq[-1] + 1: seq.append(r) else: if len(seq) >= 3: runs.append(tuple(suit * 13 + r for r in seq)) seq = [r] if len(seq) >= 3: runs.append(tuple(suit * 13 + r for r in seq)) return runsfind_sets的实现逻辑：按点数分组后，只要某组数量大于等于 3 就是一个合法牌型。find_runs则先按花色过滤，再对点数排序后做一次线性扫描，找出所有长度大于等于 3 的连续段。注意ranks用set去重，虽然标准牌组里同花色不会有重复点数，但防御性去重可以避免后续调试时喂进脏数据。
这两个函数只负责“找出所有可能的牌型”，不负责“如何组合”。因为同一张牌可能同时属于多个牌型，比如7S既能在5S 6S 7S这个顺子里，也能在7S 7H 7D这个组里。真正算死牌时要在这堆互相重叠的牌型里选一个“互不冲突且死牌分最小”的组合，这是下一章计分部分的核心，也是后面 AI 拆牌的同一个函数。
3. 用 Python 把 Gin Rummy 的一回合跑通：发牌、摸牌、出牌与敲桌判定
3.1 最小可跑的初始化与摸牌逻辑
有了状态类，游戏主循环就顺理成章。我先写一个GinRummyGame类，把发牌、洗牌、摸牌封装进去。这里最关键的一点是：所有随机性都走self.rng，而不是直接调random.shuffle模块级函数。只有这样，给了seed之后每一局都能精确复现，后面调试 AI 死循环时才能回放现场。
import random class GinRummyGame: def __init__(self, seed=None): self.rng = random.Random(seed) self.deck = list(range(52)) self.rng.shuffle(self.deck) self.hands = [self.deck[:10], self.deck[10:20]] self.stock = self.deck[20:] self.discard = [self.stock.pop()] # 翻开的第一张做弃牌堆底 self.scores = [0, 0] self.turn = 0 def draw(self, from_discard=False): """摸牌：from_discard=True 时从弃牌堆顶摸，否则从牌堆摸。""" if from_discard: card = self.discard.pop() else: card = self.stock.pop() self.hands[self.turn].append(card) return card发牌逻辑中self.deck[:10]给玩家 0，self.deck[10:20]给玩家 1，剩下的全是牌堆，再把牌堆顶的第一张翻到弃牌堆。draw方法返回摸到的牌，调用方可以拿它做决策。参数from_discard必须显式传，因为不同的摸牌来源对后续出牌约束完全不同，这在 3.2 讲。
这里的分层设计是：draw只负责改状态，不负责判断“能不能摸”。合法性校验由更上层的回合方法负责，比如摸牌前检查stock是否为空。把校验和状态变更拆开，是避免出现“非法操作改了数据”这类隐蔽 bug 的最直接手段。
3.2 合法动作校验：出牌、敲桌和弃牌堆的三个约束
金拉米一回合的标准动作序列是：摸一张牌，能敲桌就选择敲或继续，然后必须弃一张牌。这里有三条规则很容易漏，漏任何一条都会让 AI 打出的逻辑在规则上不合法。
def discard_card(self, card): """从手牌中移除一张并放到弃牌堆顶，随后切换到对家回合。""" self.hands[self.turn].remove(card) self.discard.append(card) self.turn = 1 - self.turn def can_knock(self, hand) -> bool: """手牌死牌分小于等于 10 就可以敲桌。""" _, dead = best_knock(list(hand)) return dead <= 10第一条约束：只能弃自己手里的牌，list.remove(card)在牌不在手牌时会抛ValueError，这其实是个好事，让非法操作尽早暴露。第二条约束：弃牌堆顶那张刚被摸走的牌，本回合不能再弃回去。很多变体规则里这是禁手，实现时需要在GameState里加一个last_drawn_from_discard字段，discard_card里判断“如果弃的这张等于刚摸的那张就拒绝”。
第三条约束：敲桌发生在弃牌之前，敲桌后本回合不再弃牌。所以回合循环的顺序必须是“摸牌 → 检查可敲 → 弃牌”，而不是“摸牌 → 弃牌 → 检查可敲”。我见过把顺序写反导致死牌分等于 0 却还弃一张牌出去的翻车案例，后面避坑章会细说。can_knock调用的best_knock是全局拆牌函数，它在 3.3 里给出完整实现。
3.3 一局结束时的计分：死牌差、Gin 与反超
敲桌之后，两家各自把手牌拆成牌型加死牌，按死牌分差算分。规则表看起来简单，实现时的分支顺序却是个大坑，尤其是“Gin（死牌为 0）”和“反超（对方死牌更少或平手）”两个分支不能搞反。
| 局面 | 判定条件 | 得分 |
|---|---|---|
| 普通敲桌 | 敲桌者死牌分 < 对家死牌分 | 敲桌者加两方死牌分差值 |
| Gin | 敲桌者死牌分 = 0 | 敲桌者加 25 再加对家全部死牌分 |
| 反超 | 对家死牌分 ≤ 敲桌者死牌分（敲桌者非 Gin） | 对家加 25 再加差值 |
计分前需要先算出“最小死牌组合”，这就用到了 2.3 里的find_sets和find_runs。十张手牌下牌型数量有限，用二进制掩码枚举所有互不重叠的牌型组合完全可行。
def best_knock(hand): """在所有互不重叠的牌型组合里，找死牌分最小的那个。""" hand = set(hand) melds = find_sets(hand) + find_runs(hand) best_deadwood = sum(deadwood_value(c) for c in hand) best_choice = [] for mask in range(1 << len(melds)): used, chosen, ok = set(), [], True for i, m in enumerate(melds): if (mask >> i) & 1: if used & set(m): ok = False break used |= set(m) chosen.append(m) if ok: dead = sum(deadwood_value(c) for c in hand if c not in used) if dead < best_deadwood: best_deadwood = dead best_choice = chosen return best_choice, best_deadwood逻辑说明：枚举的是“选哪几个牌型”的二进制掩码，mask的每一位对应melds里一个牌型；used & set(m)检查当前牌型和已选牌型是否有共用牌，有就剪掉这个分支。hand转成set是为了让c not in used的运算变成 O(1)。10 张牌最多产生十几个候选牌型，2^len也就几万次迭代，跑一局完全无感知。
有了best_knock，计分方法顺理成章：
def finish_round(self, knocker): """敲桌者敲桌后结算本局分数，返回当前总分。""" other = 1 - knocker _, dead_knocker = best_knock(self.hands[knocker]) _, dead_other = best_knock(self.hands[other]) if dead_knocker == 0: self.scores[knocker] += 25 + dead_other elif dead_other <= dead_knocker: self.scores[other] += 25 + (dead_knocker - dead_other) else: self.scores[knocker] += dead_other - dead_knocker return self.scores计分顺序上，dead_knocker == 0必须最先判断。如果先判断dead_other <= dead_knocker，那 Gin 且对家也 0 死牌的极端情况会被错误地算成对手反超，白白丢掉 25 分。反超规则存在的意义是惩罚鲁莽敲桌：你死牌 10、我死牌 5，你敲了桌反而送我 25 分加差值，这局就翻盘了。
4. 给单人模式一个会玩牌的对手：AI 拆牌与防守出牌
4.1 最小死牌拆法：10 张手牌上的组合搜索
单人模式能不能留住玩家，九成取决于 AI 会不会拆牌。3.3 的best_knock本质上就是一个完美的拆牌器：给任意 10 张牌，它能算出理论最小死牌分。AI 的摸牌、弃牌、敲桌决策全部可以建立在它之上，所以这章的 AI 其实就是把同一个函数用在三个不同的决策点上。
为什么不用贪心？很多人第一版会写“找到一个牌型就收下，剩下的算死牌”。这个做法在牌型不重叠时确实对，但一旦出现共用牌就翻车。比如手牌同时有5S 6S 7S和7S 7H 7D，贪心先收了顺子，7S被困在顺子里，剩下的7H 7D组不成三张，白白多两张死牌。而best_knock的枚举会把两种拆分都试一遍，选出死牌更小的那个。
时间复杂度上，10 张牌的候选牌型一般不超过 15 个，2^15也就是三万多次迭代，单次调用耗时可以忽略。这个“暴力枚举”之所以可行，正是因为金拉米手牌规模恰好卡在 10 这个数字上；如果是桥牌那种 13 张加复杂叫牌，就得换动态规划了。所以best_knock既是计分工具，也是 AI 的全部推理基础，值得单独写成一个纯函数并配单元测试。
4.2 出牌选择：去掉一张牌后重新算死牌
AI 每回合弃哪张牌，最简单也最可靠的做法是“模拟”：对每一张手牌，假设把它弃掉，对剩下的 9 张重新调用best_knock，看哪张牌被弃之后死牌分最低。这张牌就是当前最该出的牌，因为它保留了最好的牌型结构。
def choose_discard(hand, opp_rank_counts): best_card, best_score = None, 10**9 for c in hand: rest = [x for x in hand if x != c] _, dead = best_knock(rest) score = dead # 防守惩罚：这张牌的点数正是对家频繁收集的，喂出去风险高 score += 4 * opp_rank_counts.get(c % 13, 0) if score < best_score: best_card, best_score = c, score return best_card参数说明：opp_rank_counts是一个字典，key 是点数，value 是对家从弃牌堆摸走该点数的次数，由 4.3 的观察模块维护。dead是去掉这张牌后 9 张牌的最小死牌分，它越低说明这张牌越“孤立”，弃掉它不伤牌型。4 * opp_rank_counts是防守权重，对家越爱摸某个点数，AI 越不该把这个点数弃出去。
这套出牌策略有三个可调参数，也是 AI 强度的旋钮：
| 参数 | 作用 | 调大后效果 |
|---|---|---|
| 死牌分权重 | 保留牌型的优先级 | AI 更倾向保牌型，但可能忽略喂牌 |
| 防守惩罚系数 4 | 避免喂牌的程度 | AI 更保守，但可能为了防守弃掉好牌 |
| 敲桌阈值 10 | 死牌分多少算可敲 | 调成 7 会让 AI 更激进、更容易被反超 |
实际调参时建议先固定死牌权重，只调防守系数。系数从 0 开始慢慢加，观察 AI 对家能不能在你不喂牌的情况下自己凑出牌型。系数大于 8 之后 AI 会开始弃掉高价值单牌去防一个并不存在的牌型，反而变弱了。
4.3 防守信号：记住对家从弃牌堆摸了什么
弃牌堆暴露的信息比手牌多得多。对家每次从弃牌堆摸走一张牌，就等于公开告诉你“这张牌或它附近的牌是我需要的”。把这些观察累积起来，就是最廉价的防守情报。
class OpponentProfile: def __init__(self): self.rank_counts = {} # 点数 -> 被摸走次数 self.suit_counts = {} # 花色 -> 被摸走次数 def observe(self, card, from_discard): if not from_discard: return rank, suit = card % 13, card // 13 self.rank_counts[rank] = self.rank_counts.get(rank, 0) + 1 self.suit_counts[suit] = self.suit_counts.get(suit, 0) + 1 def danger(self, card) -> int: """返回这张牌喂给对家的风险分，供 choose_discard 使用。""" risk = self.rank_counts.get(card % 13, 0) * 4 if self.suit_counts.get(card // 13, 0) >= 2: risk += 3 return riskobserve只记录从弃牌堆摸的牌，因为从牌堆摸的牌没有任何倾向性。danger的判定逻辑是：点数命中一次加 4 分，说明对家可能在凑同点数的一组；同一花色被摸过两次以上追加 3 分，说明对家可能在凑同花顺子。这个“花色两刀”的启发式很糙，但实现成本极低，实测下来已经能挡住 AI 连续给对家喂同一花色顺子的问题。
防守信号的边界要清楚：它只能防“明牌”，防不了对家手里捏着一手牌型等着敲桌。真正强力的防守还得靠观察对家弃牌的频率和时机，那是另一层更复杂的策略，作为进阶方向放在最后一章提。
5. 从重复计分到 AI 死循环：5 条规则落地的避坑清单
5.1 顺子检查把不同花色的牌接在一起
现象：手牌里有5S 6S 7H，find_runs返回了一个包含这三张的“顺子”，死牌分瞬间被算成 0，AI 以为自己 Gin 了。
原因：实现时只按点数排序做连续判断，完全没锁花色。5, 6, 7点数连续，但7H花色不同，从规则上根本不能成顺。
解决：find_runs必须先按花色分组，在每一组内部再排点数、找连续段。回归测试里固定放一组跨花色的牌，断言它不会产出任何顺子。另外排序 key 用(suit, rank)，不要直接对cid排序。
5.2 Gin 被算成普通敲桌，少了 25 分
现象：AI 死牌分 0 敲桌，计分结果却只有死牌差，Gin 的 25 分加成消失了。
原因：finish_round里先判断了dead_other <= dead_knocker的反超分支。敲桌者死牌 0、对家死牌也 0 时，这个条件成立，程序错误地走了反超分支，把 25 分判给了对家。
解决：把if dead_knocker == 0放在最前面，Gin 分支优先返回。这类分支顺序 bug 靠肉眼很难发现，最有效的办法是在测试里构造“敲桌者 Gin、对家死牌 0”的对称局面，直接断言分数。
5.3 A 的环回：QKA 能接，KA2 不能接
现象：有人把K A 2拼成了顺子，还有人把Q K A判为非法。
原因：A 在编码里是 0，既不是 1 也不是 14。两个实现极端：一个把 A 当成万能牌去首尾相连，另一个在检查连续时没处理好0作为最小值的边界。
解决：规则上明确 A 只能做低点，KA2不算顺子，QKA也不合法。实现时顺子检测只做“后一张点数等于前一张加 1”的升序判断，不做任何环回处理，然后加一个包含QA2的测试锁死行为。
5.4 AI 反复摸同一张弃牌，回合数不收敛
现象：AI 从弃牌堆摸走7S，算完发现它不属于任何牌型，又把它弃回弃牌堆；下一回合又摸回来，游戏永远结束不了。
原因：没有记录“这张牌是从弃牌堆摸来的”，也没有实现“刚摸的弃牌本回合禁止弃回”这条规则。AI 打出的每个动作单独看都合法，连起来就成了死循环。
解决：在GameState里加last_drawn_from_discard字段，discard_card校验时拒绝弃掉这张牌。更稳妥的做法是把这条规则写进 Ai 决策的约束层，而不是靠 AI 自觉。
5.5 加了随机种子，崩溃现场还是复现不了
现象：某次 AI 死循环的现场，记下了seed=42，重跑却一切正常。
原因：初始化时random.shuffle(self.deck)用的是模块级全局随机源，而 AI 内部又用了self.rng，两个随机源互不同步，seed只能复现洗牌，复现不了后续 AI 的随机决策。
解决：所有随机调用统一走self.rng，AI 决策里也绝不调用random模块的全局函数。再把每回合的关键动作按(seed, 回合号)写进日志，崩溃时直接按这个 key 回放。加了种子还复现不了，八成是随机源不统一，这条血泪经验值得刻在项目 README 里。
6. 用回归测试锁住规则：从构造 Gin 手牌到洗牌公平性
最后一公里是验证。金拉米规则细碎，人工试玩永远试不全边界，我一般会写三类回归测试：计分测试、拆牌测试、随机公平性测试。计分测试直接构造一手必 Gin 的手牌，用card_str把可读牌面写进断言里，让测试本身可读可 review。
def test_gin_scoring(): g = GinRummyGame(seed=7) # 两段顺子加一个四张组：2S3S4S, 2H3H4H, 7S7H7D7C g.hands[0] = [1, 2, 3, 14, 15, 16, 6, 19, 32, 45] assert card_str(1) == "2S" and card_str(45) == "7C" # 对家是一手无任何牌型的散牌，死牌分固定为 70 g.hands[1] = [3, 7, 11, 15, 21, 25, 30, 34, 41, 48] g.finish_round(knocker=0) assert g.scores[0] == 25 + 70 # Gin 加对家全部死牌分拆牌测试专挑共用牌的歧义局面，比如5S6S7S和7S7H7D7C都用到7S，正确拆分必须放弃其中一组，断言最后算出的死牌分是 10 而不是 0。这类测试是防止后续重构把best_knock改坏的最有效保险。
def test_overlap_meld_choice(): # 5S6S7S + 7H7D7C + 9HTHJH + KC：正确拆法死牌应为 KC 的 10 分 hand = [4, 5, 6, 19, 32, 45, 21, 22, 23, 25] _, dead = best_knock(hand) assert dead == 10随机公平性测试用统计说话。跑 5000 局，统计玩家 0 首牌里每张牌出现的次数，期望值是5000 * 10 / 52 ≈ 962，因为每次发牌相互独立，波动幅度理论上限在 120 以内，断言max(counts) - min(counts) < 120就能抓住“两张牌永远挨在一起”这类洗牌 bug。
这三个测试跑完，规则层面的信心就立住了。剩下值得投入的方向是把 AI 从“会拆牌”升级到“会看人”：记录对家弃牌的犹豫次数、敲桌时机、平均死牌分，用来判断对家是保守型还是激进型，然后动态调整敲桌阈值。我自己的习惯是每改一个规则，先给finish_round写一个对应测试再动代码，这个顺序帮我挡住了至少三次计分回归。希望帮到你。
本文还有配套的精品资源，点击获取
