1. 为什么选择用Java手写一个FreeCell1.1 从纸牌游戏到编程练手项目的距离FreeCell自由细胞这个纸牌游戏很多人第一次接触是在老版本的Windows系统里。规则看起来简单八列牌、四个自由格、四个回收位把所有牌按花色从A到K收回去就赢了。但真正上手写一遍才会发现这个游戏的逻辑密度远比扫雷、贪吃蛇高出一个量级。它涉及状态管理、规则校验、撤销栈、自动移动判定、可解性分析等多个编程核心问题是一个非常适合用来打磨编程基本功的项目。我选择Java来实现这个项目原因很直接。Java的面向对象特性天然适合对“牌”“列”“自由格”“回收位”这些实体建模Swing组件虽然老旧但用来做桌面小游戏绰绰有余不需要引入任何第三方依赖就能跑起来再加上Java的集合框架ArrayList、Stack、HashMap在处理牌堆操作时非常顺手。整个项目从零到可玩代码量控制在两千行以内对有一定Java基础、想找一个完整项目练手的人来说门槛刚好。这个项目适合谁如果你已经学过Java基础语法能写类、懂继承和多态但还没独立完成过一个有完整交互逻辑的项目那FreeCell就是一个很好的切入点。它不像电商系统那样需要数据库和网络通信也不像编译器那样理论门槛高不可攀它就是一个纯粹的、自包含的逻辑系统所有复杂度都集中在规则和状态上。1.2 这个项目到底解决了什么问题表面上看写一个FreeCell就是实现一个游戏。但从编程训练的角度它解决的是几个非常实际的问题。第一复杂状态的管理。一局FreeCell的状态包括八列牌堆每列数量不等、四个自由格最多各一张牌、四个回收位按花色递增、以及撤销历史。这些状态之间相互关联任何一次移动都会同时改变多个位置的数据。怎么设计数据结构让状态变更清晰可控是这个项目的第一个核心挑战。第二规则引擎的构建。FreeCell的移动规则并不复杂但边界条件很多。比如自由格满了还能不能移牌回收位能不能往回拿牌一次能移动多张牌的条件是什么这些规则如果写成散落各处的if-else代码会迅速失控。必须把规则抽象成独立的校验方法才能保证逻辑清晰。第三用户体验的细节。自动收牌什么时候触发双击一张牌应该做什么撤销操作怎么实现这些看似琐碎的交互细节恰恰是一个项目从“能跑”到“好用”的关键。2. 核心数据结构与建模思路2.1 牌的表示为什么用两个枚举而不是整数很多初学者会用1到52的整数来表示一张牌然后通过取模和除法来推算花色和点数。这种做法在C语言里很常见但在Java里我更推荐用两个枚举类型来建模。public enum Suit { SPADE, HEART, CLUB, DIAMOND } public enum Rank { ACE, TWO, THREE, FOUR, FIVE, SIX, SEVEN, EIGHT, NINE, TEN, JACK, QUEEN, KING }然后用一个Card类把两者组合起来public class Card { private final Suit suit; private final Rank rank; private boolean faceUp; public Card(Suit suit, Rank rank) { this.suit suit; this.rank rank; this.faceUp false; } public boolean isRed() { return suit Suit.HEART || suit Suit.DIAMOND; } // getter 和 setter 省略 }这样做的优势在于类型安全。你不可能不小心把花色赋值成点数编译器会帮你拦住。而且代码可读性极高card.getSuit() Suit.SPADE比card % 4 0直观太多。代价是内存占用略高但对于一个纸牌游戏来说52个对象的开销完全可以忽略。faceUp这个字段在FreeCell里其实用得不多因为FreeCell不像接龙那样有翻牌机制所有牌从一开始就是明牌。但保留这个字段可以为后续扩展比如加入其他纸牌玩法留出空间。2.2 游戏状态的容器选择ArrayList还是LinkedList八列牌堆每列需要支持的操作是从顶部取牌、往顶部放牌、查看顶部牌、查看全部牌。这些操作本质上都是栈操作后进先出。Java的Stack类是一个选择但我更倾向于用ArrayListCard来模拟栈。原因有三点。第一Stack类继承自Vector所有方法都是同步的单线程游戏里这是不必要的开销。第二ArrayList的add()和remove(size()-1)操作在尾部效率很高完全满足需求。第三ArrayList提供了更丰富的API比如subList()、get(index)在实现“一次移动多张牌”的功能时更方便。public class GameState { private ListListCard columns; // 八列牌堆 private ListCard freeCells; // 四个自由格 private MapSuit, ListCard foundations; // 四个回收位 private DequeMove moveHistory; // 撤销栈 }自由格用ListCard表示初始时填充四个null这样索引位置固定方便定位。回收位用MapSuit, ListCard每个花色对应一个列表列表的size就是当前该花色已回收的牌数天然支持“下一张应该收哪张”的判断。2.3 撤销功能的实现命令模式的实际应用撤销是FreeCell里不可或缺的功能没有撤销的FreeCell几乎没法玩。实现撤销最优雅的方式是命令模式每一次移动都封装成一个对象记录移动的源位置、目标位置、移动了哪些牌撤销时反向执行即可。public class Move { private final Location from; private final Location to; private final ListCard cards; private final boolean wasFaceUp; // 预留字段 // 构造函数、getter省略 }Location可以是一个简单的类用类型COLUMN、FREE_CELL、FOUNDATION和索引来标识位置。撤销时从moveHistory弹出最后一个Move把牌从to移回from同时恢复相关状态。这里有一个容易踩的坑自动收牌也需要记录到撤销栈里。如果自动收牌不记录玩家撤销时就会出现状态不一致。我的做法是把自动收牌也封装成Move对象连续压入栈中这样撤销时会一步步回退体验很自然。3. 规则引擎的拆解与实现3.1 移动合法性校验把规则写成独立方法FreeCell的移动规则可以归纳为几条从列到列只能移动列顶部的牌且目标列的顶部牌必须比移动牌大1且颜色相反。从列到自由格自由格必须为空。从自由格到列目标列的顶部牌必须比移动牌大1且颜色相反。从列或自由格到回收位回收位必须接受这张牌同花色且比当前顶部牌大1A可以直接放。一次移动多张牌需要满足“连续递减且颜色交替”的序列且目标列顶部牌比序列第一张牌大1且颜色相反同时自由格和空列的数量要足够作为中转。把这些规则写成独立的方法每个方法只负责一个判断public boolean canMoveToColumn(Card card, int columnIndex) { ListCard column columns.get(columnIndex); if (column.isEmpty()) return true; Card top column.get(column.size() - 1); return top.getRank().ordinal() card.getRank().ordinal() 1 top.isRed() ! card.isRed(); } public boolean canMoveToFreeCell(int cellIndex) { return freeCells.get(cellIndex) null; } public boolean canMoveToFoundation(Card card) { ListCard foundation foundations.get(card.getSuit()); if (foundation.isEmpty()) { return card.getRank() Rank.ACE; } Card top foundation.get(foundation.size() - 1); return card.getRank().ordinal() top.getRank().ordinal() 1; }这种写法的好处是每个规则都可以单独测试。你可以写单元测试来验证边界条件比如“空列可以接受任何牌”“回收位只能接受A作为第一张”等等。3.2 多张牌移动的计算逻辑一次移动多张牌是FreeCell里最复杂的规则。假设你要从某一列移动一个长度为N的序列到另一列需要满足两个条件第一这个序列本身必须是合法的连续递减且颜色交替。这个判断很简单从序列第一张开始依次检查相邻两张牌是否满足“前一张比后一张大1且颜色相反”。第二目标列必须能接受序列的第一张牌即目标列顶部牌比第一张牌大1且颜色相反或者目标列为空。第三中转空间要足够。这是最容易被忽略的条件。移动N张牌时你需要足够的空自由格和空列来临时存放这些牌。计算公式是可移动的最大牌数 (空自由格数 1) × 2^(空列数)这个公式的推导逻辑是每个空列可以把可移动数量翻倍因为空列可以临时存放一叠牌每个空自由格可以额外增加一个单位的容量。举个例子如果有2个空自由格和1个空列那么可移动的最大牌数是(21)×2^16张。在实际代码中我通常会在移动前计算当前可移动的最大牌数如果玩家尝试移动的序列长度超过这个值就拒绝操作并给出提示。public int getMaxMovableCards() { int emptyFreeCells 0; for (Card card : freeCells) { if (card null) emptyFreeCells; } int emptyColumns 0; for (ListCard column : columns) { if (column.isEmpty()) emptyColumns; } return (emptyFreeCells 1) * (int) Math.pow(2, emptyColumns); }注意这里计算空列时如果移动的源列本身是空列需要排除掉否则会多算一个空列。这个细节在实际编码时很容易出错。3.3 自动收牌的触发时机与安全判定自动收牌是指当某张牌可以安全地放到回收位时系统自动帮你放上去。这个功能看似简单但“安全”的判定需要谨慎。什么叫安全一张牌可以放到回收位不代表放上去是安全的。比如一张红桃2可以放到回收位如果红桃A已经在回收位但如果黑桃A还没被收走你把红桃2收上去可能会导致后续无牌可动。我的做法是只自动收A和2。A是必须收的因为A不影响任何列的移动逻辑。2在大多数情况下也是安全的因为2只能接在A后面而A已经在回收位了。对于3及以上的牌不自动收让玩家自己决定。自动收牌的触发时机是每次玩家完成一次移动后检查四个回收位和所有列的顶部牌看是否有A或2可以收。如果有就自动收上去并记录到撤销栈。private void autoCollect() { boolean collected; do { collected false; // 检查自由格 for (int i 0; i freeCells.size(); i) { Card card freeCells.get(i); if (card ! null shouldAutoCollect(card)) { moveToFoundation(card, i, LocationType.FREE_CELL); collected true; } } // 检查列顶部 for (int i 0; i columns.size(); i) { ListCard column columns.get(i); if (!column.isEmpty()) { Card top column.get(column.size() - 1); if (shouldAutoCollect(top)) { moveToFoundation(top, i, LocationType.COLUMN); collected true; } } } } while (collected); } private boolean shouldAutoCollect(Card card) { return card.getRank() Rank.ACE || card.getRank() Rank.TWO; }用do-while循环是因为一次自动收牌可能引发连锁反应比如收了一张A之后原本不能收的2变成了可收的。4. 界面交互与用户体验打磨4.1 Swing布局用JLayeredPane实现牌的重叠效果FreeCell的界面需要把牌叠在一起显示每张牌只露出顶部一部分。Swing的JLayeredPane可以完美实现这个效果。每一列用一个JLayeredPane每张牌是一个JLabel或自定义的JPanel通过设置不同的Y坐标来实现重叠。public class ColumnPanel extends JLayeredPane { private static final int CARD_OFFSET 25; // 每张牌露出的高度 private static final int CARD_HEIGHT 100; public void addCard(Card card, int index) { CardPanel cardPanel new CardPanel(card); cardPanel.setBounds(0, index * CARD_OFFSET, 80, CARD_HEIGHT); add(cardPanel, JLayeredPane.DEFAULT_LAYER, index); revalidate(); repaint(); } }这里的关键是CARD_OFFSET的设置。如果设得太小牌叠在一起看不清点数设得太大一列牌多了会超出屏幕。经过多次调整25像素是一个比较合适的值一列最多能显示8到10张牌而不溢出。牌的绘制可以用Graphics2D来画也可以用图片。我倾向于用代码绘制因为不需要额外的资源文件而且可以随时调整颜色和字体。红色花色用Color.RED黑色用Color.BLACK背景用白色圆角矩形边框用灰色。4.2 鼠标事件处理点击、拖拽与双击FreeCell的交互方式有多种单击选中、再次单击目标位置移动、双击自动移动到回收位、拖拽移动。我建议至少实现单击和双击两种。单击的逻辑是第一次点击选中一张牌或一个序列第二次点击目标位置时尝试移动。如果移动不合法取消选中状态。private Card selectedCard; private Location selectedLocation; public void handleClick(Location location, Card card) { if (selectedCard null) { // 第一次点击尝试选中 if (canSelect(location, card)) { selectedCard card; selectedLocation location; highlightSelection(); } } else { // 第二次点击尝试移动 if (canMove(selectedLocation, location, selectedCard)) { performMove(selectedLocation, location); clearSelection(); } else { clearSelection(); } } }双击的逻辑是如果双击的牌可以放到回收位就直接放上去。这个操作很符合直觉玩家会频繁使用。public void handleDoubleClick(Location location, Card card) { if (canMoveToFoundation(card)) { moveToFoundation(card, location); } }注意双击事件在Swing里会先触发一次单击事件所以需要在单击处理里加一个延迟判断或者用一个标志位来区分。我的做法是记录上次点击的时间戳如果两次点击间隔小于300毫秒就当作双击处理忽略单击逻辑。4.3 视觉反馈选中高亮与非法移动提示选中一张牌时需要给玩家明确的视觉反馈。我的做法是给选中的牌加一个黄色边框或者改变背景色。如果选中的是一个序列序列中所有牌都要高亮。非法移动时不要只是默默拒绝要给玩家提示。最简单的做法是让选中的牌闪烁一下红色或者弹出一个短暂的提示文字。我倾向于用状态栏显示提示信息比如“无法移动到该位置目标列顶部牌不匹配”。private void showMessage(String message) { statusLabel.setText(message); Timer timer new Timer(2000, e - statusLabel.setText()); timer.setRepeats(false); timer.start(); }这种非侵入式的提示不会打断玩家的操作节奏比弹出对话框体验好得多。5. 常见问题与排查实录5.1 牌堆索引越界与空列判断在实现移动逻辑时最容易出现的bug是索引越界。比如从空列取牌时column.get(column.size() - 1)会抛出IndexOutOfBoundsException。解决办法是在每次取牌前先判断列是否为空。另一个容易出错的地方是空列的判断。在计算可移动牌数时如果源列本身是空列需要把它排除在“空列数”之外。我踩过这个坑有一次测试时发现明明只能移动4张牌系统却允许移动8张排查了半天才发现是空列计算重复了。public int getEmptyColumnCountExcluding(int excludeIndex) { int count 0; for (int i 0; i columns.size(); i) { if (i ! excludeIndex columns.get(i).isEmpty()) { count; } } return count; }5.2 撤销后状态不一致的排查撤销功能最容易出的问题是状态不一致。比如撤销了一次移动后牌回到了原来的位置但自动收牌的记录没有正确回退导致回收位的牌数和实际不符。排查这类问题的技巧是在每次移动和撤销后打印完整的游戏状态每列有哪些牌、自由格有哪些牌、回收位有哪些牌然后对比操作前后的状态是否一致。我通常会写一个dumpState()方法在调试模式下调用。public void dumpState() { System.out.println( Game State ); for (int i 0; i columns.size(); i) { System.out.println(Column i : columns.get(i)); } System.out.println(Free Cells: freeCells); for (Map.EntrySuit, ListCard entry : foundations.entrySet()) { System.out.println(Foundation entry.getKey() : entry.getValue()); } }另一个技巧是给每个Move对象加一个唯一ID在撤销时打印ID这样可以追踪每一次操作的顺序。5.3 自动收牌导致的死局问题自动收牌虽然方便但有时候会把玩家逼入死局。比如自动收了一张2之后原本可以用来临时存放牌的列空出来了但玩家可能正需要那张2在列上作为中转。我的解决方案是只自动收A2及以上的牌不自动收。A是绝对安全的因为A在回收位不影响任何列的移动逻辑。2虽然大多数时候安全但在极少数情况下可能会造成问题。让玩家手动收2虽然多了一步操作但避免了死局的风险。如果你坚持要自动收2可以加一个设置选项让玩家自己决定是否开启。我在代码里预留了一个autoCollectRank变量默认值是Rank.ACE玩家可以在设置里改成Rank.TWO。5.4 常见问题速查表问题现象可能原因排查方法解决方案点击牌没反应事件监听器未绑定检查addMouseListener是否调用给每个牌面板绑定监听器移动后界面不更新未调用repaint()在移动逻辑后加日志每次状态变更后调用revalidate()和repaint()撤销后牌的位置不对撤销栈记录不完整打印每次移动的源和目标确保自动收牌也记录到撤销栈多张牌移动被拒绝可移动数量计算错误打印空列和空自由格数量排除源列本身重新计算双击触发两次单击事件冲突记录点击时间戳用300毫秒阈值区分单击和双击回收位接受错误牌校验逻辑遗漏单元测试边界条件补充canMoveToFoundation的A判断6. 项目扩展与进阶方向6.1 加入可解性分析FreeCell的一个有趣特性是并非每一局都一定能赢。有些牌局从初始状态就是死局。如果你想让游戏更友好可以在发牌后运行一个求解器判断当前牌局是否可解。如果不可解就重新发牌。求解器的实现可以用回溯搜索尝试所有可能的移动如果某条路径能走到胜利状态就说明可解。但FreeCell的状态空间很大暴力搜索可能很慢。实用的做法是加一个启发式评估函数优先尝试“能收牌”“能空列”的移动同时设置一个搜索深度上限。public boolean isSolvable(GameState state, int depthLimit) { if (state.isWin()) return true; if (depthLimit 0) return false; ListMove possibleMoves state.getPossibleMoves(); // 按启发式排序优先尝试收牌和空列 possibleMoves.sort((a, b) - heuristic(b) - heuristic(a)); for (Move move : possibleMoves) { GameState next state.applyMove(move); if (isSolvable(next, depthLimit - 1)) { return true; } } return false; }这个功能对性能要求较高建议放在后台线程里执行避免阻塞界面。6.2 用JavaFX重写界面Swing虽然能用但界面风格比较老旧。如果你想让项目看起来更现代可以用JavaFX重写界面层。JavaFX的StackPane和Translate动画可以做出更流畅的牌移动效果而且支持CSS样式调整外观更方便。核心的游戏逻辑GameState、Move、规则校验可以完全复用只需要重写界面部分。这也是为什么我建议把逻辑和界面分离——逻辑层不依赖任何Swing类这样换界面框架时不需要改动逻辑代码。6.3 加入计时、计分与统计一个完整的游戏通常需要一些激励元素。你可以加入计时器记录每局用时加入计分系统根据移动步数和用时计算分数加入统计功能记录胜率、最快通关时间等。这些功能的数据可以存在本地文件里用简单的JSON格式读写。Java没有内置的JSON库但你可以用Properties类或者自己写一个简单的序列化方法。如果不想引入第三方库用java.util.prefs.Preferences也是一个选择它可以直接把数据存到系统注册表或用户目录下。Preferences prefs Preferences.userNodeForPackage(FreeCellApp.class); prefs.putInt(gamesPlayed, gamesPlayed); prefs.putInt(gamesWon, gamesWon); prefs.putLong(bestTime, bestTime);这个API用起来很简单但注意它不适合存大量数据只适合存一些简单的配置和统计值。6.4 移动端适配的可行性分析有人可能会问能不能把这个游戏移植到移动端技术上可行但需要把Swing替换成Android的View体系或者用LibGDX这样的跨平台游戏框架。核心逻辑层可以打包成一个纯Java库直接在Android项目里引用。不过移动端的交互方式和桌面端差异很大。桌面端用鼠标点击和拖拽移动端用触摸手势。你需要重新设计交互逻辑比如单击选中、再次单击移动的方式在移动端可能不如拖拽直观。另外移动端屏幕小牌的尺寸和间距都需要重新计算。我的建议是如果你只是想练手桌面端已经足够。如果你想做一个完整的跨平台项目可以考虑用LibGDX它支持桌面、Android、iOS多个平台而且游戏循环和渲染管线都是现成的。7. 一些实操心得与避坑建议写这个项目的过程中我踩过不少坑这里挑几个最有代表性的分享一下。第一个坑不要过早优化界面。我一开始花了很多时间在牌的绘制上想做出漂亮的渐变和阴影效果结果核心逻辑还没写完界面代码已经改了好几版。后来我调整了策略先用最简单的矩形和文字把游戏跑通确认逻辑没问题后再回头打磨界面。这个顺序很重要因为逻辑是骨架界面是皮肤骨架不稳皮肤再好看也没用。第二个坑撤销栈要用深拷贝。我最初实现撤销时直接把Card对象的引用存到Move里。结果发现撤销后如果再次移动同一张牌Move里的引用和实际状态会不一致。解决办法是Move里存牌的标识花色和点数撤销时根据标识从当前位置找到对应的牌对象。或者更简单Card对象一旦创建就不可变花色和点数不变这样引用共享是安全的。第三个坑自动收牌的循环要加终止条件。我写自动收牌时用了while(true)循环结果因为某个bug导致死循环程序直接卡死。后来改成do-while加一个collected标志确保每次循环至少收一张牌收不到就退出。这个教训是任何循环都要有明确的终止条件尤其是涉及状态变更的循环。第四个坑测试要覆盖边界条件。我最初测试时只测了正常移动没测空列、空自由格、回收位满等情况。结果玩家一操作就崩溃。后来我补了一批单元测试专门测边界条件空列取牌、自由格满时移动、回收位收A、多张牌移动数量刚好等于上限等等。这些测试帮我抓出了好几个隐藏bug。第五个坑状态栏提示不要用弹窗。我一开始用JOptionPane显示非法移动提示结果每次操作失败都弹一个对话框玩家必须点确定才能继续体验极差。后来改成状态栏文字提示2秒后自动消失流畅多了。这个细节虽小但对体验的影响很大。最后分享一个提高开发效率的小技巧用控制台命令驱动游戏逻辑。在界面还没做好的时候我写了一个简单的命令行界面用文字命令来移动牌比如move 3 5表示从第3列移到第5列。这样可以在没有图形界面的情况下测试核心逻辑速度比反复启动Swing窗口快得多。等逻辑稳定后再把界面接上去事半功倍。
