1. 为什么选择用Java手写一个FreeCell

1.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类是一个选择，但我更倾向于用ArrayList<Card>来模拟栈。

原因有三点。第一，Stack类继承自Vector，所有方法都是同步的，单线程游戏里这是不必要的开销。第二，ArrayList的add()和remove(size()-1)操作在尾部效率很高，完全满足需求。第三，ArrayList提供了更丰富的API，比如subList()、get(index)，在实现“一次移动多张牌”的功能时更方便。

public class GameState { private List<List<Card>> columns; // 八列牌堆 private List<Card> freeCells; // 四个自由格 private Map<Suit, List<Card>> foundations; // 四个回收位 private Deque<Move> moveHistory; // 撤销栈 }

自由格用List<Card>表示，初始时填充四个null，这样索引位置固定，方便定位。回收位用Map<Suit, List<Card>>，每个花色对应一个列表，列表的size就是当前该花色已回收的牌数，天然支持“下一张应该收哪张”的判断。

2.3 撤销功能的实现：命令模式的实际应用

撤销是FreeCell里不可或缺的功能，没有撤销的FreeCell几乎没法玩。实现撤销最优雅的方式是命令模式：每一次移动都封装成一个对象，记录移动的源位置、目标位置、移动了哪些牌，撤销时反向执行即可。

public class Move { private final Location from; private final Location to; private final List<Card> cards; private final boolean wasFaceUp; // 预留字段 // 构造函数、getter省略 }

Location可以是一个简单的类，用类型（COLUMN、FREE_CELL、FOUNDATION）和索引来标识位置。撤销时，从moveHistory弹出最后一个Move，把牌从to移回from，同时恢复相关状态。

这里有一个容易踩的坑：自动收牌也需要记录到撤销栈里。如果自动收牌不记录，玩家撤销时就会出现状态不一致。我的做法是，把自动收牌也封装成Move对象，连续压入栈中，这样撤销时会一步步回退，体验很自然。

3. 规则引擎的拆解与实现

3.1 移动合法性校验：把规则写成独立方法

FreeCell的移动规则可以归纳为几条：

1. 从列到列：只能移动列顶部的牌，且目标列的顶部牌必须比移动牌大1且颜色相反。
2. 从列到自由格：自由格必须为空。
3. 从自由格到列：目标列的顶部牌必须比移动牌大1且颜色相反。
4. 从列或自由格到回收位：回收位必须接受这张牌（同花色且比当前顶部牌大1，A可以直接放）。
5. 一次移动多张牌：需要满足“连续递减且颜色交替”的序列，且目标列顶部牌比序列第一张牌大1且颜色相反，同时自由格和空列的数量要足够作为中转。

把这些规则写成独立的方法，每个方法只负责一个判断：

public boolean canMoveToColumn(Card card, int columnIndex) { List<Card> 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) { List<Card> 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个空列，那么可移动的最大牌数是(2+1)×2^1=6张。

在实际代码中，我通常会在移动前计算当前可移动的最大牌数，如果玩家尝试移动的序列长度超过这个值，就拒绝操作并给出提示。

public int getMaxMovableCards() { int emptyFreeCells = 0; for (Card card : freeCells) { if (card == null) emptyFreeCells++; } int emptyColumns = 0; for (List<Card> 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++) { List<Card> 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.Entry<Suit, List<Card>> entry : foundations.entrySet()) { System.out.println("Foundation " + entry.getKey() + ": " + entry.getValue()); } }

另一个技巧是给每个Move对象加一个唯一ID，在撤销时打印ID，这样可以追踪每一次操作的顺序。

5.3 自动收牌导致的死局问题

自动收牌虽然方便，但有时候会把玩家逼入死局。比如，自动收了一张2之后，原本可以用来临时存放牌的列空出来了，但玩家可能正需要那张2在列上作为中转。

我的解决方案是：只自动收A，2及以上的牌不自动收。A是绝对安全的，因为A在回收位不影响任何列的移动逻辑。2虽然大多数时候安全，但在极少数情况下可能会造成问题。让玩家手动收2，虽然多了一步操作，但避免了死局的风险。

如果你坚持要自动收2，可以加一个设置选项，让玩家自己决定是否开启。我在代码里预留了一个autoCollectRank变量，默认值是Rank.ACE，玩家可以在设置里改成Rank.TWO。

5.4 常见问题速查表

6. 项目扩展与进阶方向

6.1 加入可解性分析

FreeCell的一个有趣特性是：并非每一局都一定能赢。有些牌局从初始状态就是死局。如果你想让游戏更友好，可以在发牌后运行一个求解器，判断当前牌局是否可解。如果不可解，就重新发牌。

求解器的实现可以用回溯搜索：尝试所有可能的移动，如果某条路径能走到胜利状态，就说明可解。但FreeCell的状态空间很大，暴力搜索可能很慢。实用的做法是加一个启发式评估函数，优先尝试“能收牌”“能空列”的移动，同时设置一个搜索深度上限。

public boolean isSolvable(GameState state, int depthLimit) { if (state.isWin()) return true; if (depthLimit <= 0) return false; List<Move> 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窗口快得多。等逻辑稳定后，再把界面接上去，事半功倍。