数字华容道Java实战：棋盘建模、可解性检测到求解器一次搞定

简介：Java项目实战：数字华容道/石头迷阵游戏，面向Java初学者、课程设计学生及游戏开发爱好者。该项目基于Swing构建经典滑块拼图玩法，完整实现棋盘初始化、随机打乱且保证局面可解、上下左右移动判定、步数统计、胜利弹窗与重置功能，并配有数字方块、背景及胜利界面等图片素材，帮助读者把面向对象、二维数组、事件监听、界面布局知识应用到真实项目中。压缩包共22个文件，以3个Java源文件为核心，覆盖游戏入口、逻辑控制与界面绘制；另含18张PNG图片素材和1个iml工程模块文件，整体仅372KB，轻量易学。源码目录结构清晰，按com.itheima包组织业务类，src/image统一存放图片，可直接导入主流集成开发环境运行并二次开发。已有1018人学习下载，适合作为课程设计、项目实训、蓝桥杯备赛或自学练手的优质参考，便于深入理解Java游戏开发完整流程。

1. 数字华容道/石头迷阵游戏为什么是Java项目实战的绝佳练手题

一个4x4的滑块游戏，表面看只是把15个数字按顺序排列，但对Java工程师来说，它是一道把数组操作、随机算法、事件监听、搜索剪枝串起来的综合题。很多人在简历上写“数字华容道游戏”，面试官第一句就是：你的打乱算法怎么保证有解？这个问题能筛掉一半没做过深度思考的人。石头迷阵则是同一个游戏的换皮版本，把数字换成石头图标，规则完全一致。这个项目适合刚学完Java基础准备找项目实战的初学者，也适合想在面试前用一个小而完整的代码重新梳理逻辑的工程师。下面我按自己带项目时的顺序，从棋盘建模讲到求解器验证，每段代码都能放进你的项目里跑通。

2. 先把游戏逻辑写对：棋盘建模、移动判定与可解性检测

2.1 用二维数组还是一维数组？两种建模方式与选择理由

先决定数据模型。常见做法是用一个长度为size*size的一维数组来表示棋盘，0作为空白格。为什么不用int[][]？因为一维数组的下标可以直接对应UI层的组件索引，做交换时只需要记录blankIndex；而二维数组虽然直观，却要在每一层做row/col换算，多写不少代码，还容易把x和y搞反。

我一般会把棋盘逻辑放在一个独立类里，不让任何UI代码直接操作这个数组。这个类对外提供canMove、move、isSolved、getTile几个方法，内部怎么存都不影响外部调用。这样做的直接好处是：控制台版、Swing版、甚至后来接Spring Boot接口，都可以复用同一个模型类，也方便写单元测试。

如果你偏爱二维数组，也可以，但要写一个to1D(row, col)方法统一换算，并且保证所有调用都走这个方法。我在代码审查时见过好几次行列转换错误，根源都是这里，不是算法本身。与其用二维数组增加心智负担，不如一开始就用一维数组。

2.2 把移动封装成 move(int index)：边界判断与交换

移动的本质是把被点击的块与空白格交换。用一个方法完成这个操作，后续所有游戏模式都调用它。

public class NumberPuzzle { private final int size; private final int[] tiles; private int blankIndex; public NumberPuzzle(int size) { this.size = size; this.tiles = new int[size * size]; for (int i = 0; i < tiles.length - 1; i++) { tiles[i] = i + 1; } tiles[tiles.length - 1] = 0; blankIndex = tiles.length - 1; } public int getSize() { return size; } public int getTileCount() { return tiles.length; } public int getTile(int index) { return tiles[index]; } public int getBlankIndex() { return blankIndex; } public int[] getTiles() { return tiles.clone(); } public void setTiles(int[] source, int blankIndex) { System.arraycopy(source, 0, tiles, 0, tiles.length); this.blankIndex = blankIndex; } public boolean canMove(int index) { if (index < 0 || index >= tiles.length) return false; int row = index / size; int col = index % size; int blankRow = blankIndex / size; int blankCol = blankIndex % size; return Math.abs(row - blankRow) + Math.abs(col - blankCol) == 1; } public void move(int index) { if (!canMove(index)) { throw new IllegalArgumentException("无法移动：该块不在空白格旁边"); } tiles[blankIndex] = tiles[index]; tiles[index] = 0; blankIndex = index; } public boolean isSolved() { for (int i = 0; i < tiles.length - 1; i++) { if (tiles[i] != i + 1) return false; } return tiles[tiles.length - 1] == 0; } }

逻辑说明：canMove用曼哈顿距离判断两个格子是否相邻，而不是逐个写四个方向，这样当size变化时不需要改动。move里先把空白位填入被移动的块，再将被移动位置置0，最后更新空白下标。setTiles用于从外部加载一个初始局面，后面打乱和求解器都要用到。我们给size做成构造参数，而不是写死4，方便扩展3x3、5x5。

参数说明：setTiles里我用System.arraycopy而不是直接this.tiles = tiles，这样外部后续修改传入的数组不会污染棋盘内部状态。这个细节在写求解器时会避免一类很难查的bug。getTiles返回clone也是同样的防御性拷贝思路，很多玄学bug都来自外部直接拿到底层数组后乱改。

2.3 可解性检测：为什么3x3和4x4的判定不一样

如果只是把数字洗牌就开始游戏，你会得到大约一半根本解不出来的死局。规则是这样的：把除0外的方块按从左到右、从上到下展开成一列，统计每个数右边比自己小的数个数之和，称为逆序数。对奇数阶（3x3），可解条件是逆序数为偶数；对偶数阶（4x4），可解条件是“逆序数 + 空白格所在行从底部起的行号”为偶数。

public static boolean isSolvable(int[] tiles, int size) { int[] flat = new int[tiles.length - 1]; int idx = 0; for (int value : tiles) { if (value != 0) flat[idx++] = value; } int inversions = 0; for (int i = 0; i < flat.length; i++) { for (int j = i + 1; j < flat.length; j++) { if (flat[i] > flat[j]) inversions++; } } if (size % 2 == 1) { return inversions % 2 == 0; } else { int blankRow = findBlankRow(tiles, size); int blankRowFromBottom = size - 1 - blankRow; return (inversions + blankRowFromBottom) % 2 == 0; } } private static int findBlankRow(int[] tiles, int size) { for (int i = 0; i < tiles.length; i++) { if (tiles[i] == 0) return i / size; } return -1; }

逻辑说明：双重循环求逆序数在15个数时性能可以忽略。这个双重循环和冒泡排序的写法很像，面试时如果被问到排序，也能顺带聊两句。为什么偶数阶要额外看空白行号？因为每次水平移动会改变逆序数奇偶性，垂直移动会影响空白行位置，两类移动对奇偶性的影响需要合并计算。这里不展开证明，但你要知道结论，否则面试答不上来。

写完这个类后，建议你顺手写几个测试用例：从已解决状态反向推导出来的一步状态、两步状态，分别断言可解；再把两个非零块交换后断言不可解。这样后面的shuffle才不会偷偷引入死局。

3. 把源代码跑起来：从控制台版到Swing图形界面的改造路线

3.1 拿到源代码后先看什么：项目结构、入口类与构建方式

无论是从源码包解压还是自己建项目，第一个动作都是先看入口。常见的Java项目源码会按“模型、视图、控制”分层，即使是一个小游戏也建议这样组织：

number-puzzle/ ├── README.md ├── src/ │ └── main/java/com/example/puzzle/ │ ├── NumberPuzzle.java # 棋盘逻辑 │ ├── PuzzleSolver.java # 求解器 │ ├── GamePanel.java # Swing画布 │ └── Main.java # 入口 └── test/ └── java/com/example/puzzle/ └── NumberPuzzleTest.java # 单元测试

拿到别人的源码，不要上来就找界面文件。先读NumberPuzzle.java，确认规则和数据结构，再去找main方法。如果是一个还没有重构的单文件版本，那正好由你来拆分。用Git做源代码管理，每拆出一个类提交一次，出问题可以随时回退，这是我在项目实战里最看重的习惯。

构建方式方面，最简单的就是纯JDK：在src/main/java里直接javac Main.java跑。如果项目里带了pom.xml，就用Maven的mvn clean package；带build.gradle就用Gradle。不要一上来就依赖IDE的绿色三角形，先弄清构建命令，后面接数据库或者前后端分离项目才不会翻车。

3.2 控制台版最小实现：输入块编号循环与错误处理

控制台版最大的作用是验证模型层没有逻辑错误。你可以在不启动图形界面的情况下，把移动、胜利、非法输入都测一遍。

import java.util.Scanner; public class ConsoleMain { public static void main(String[] args) { NumberPuzzle game = new NumberPuzzle(4); Scanner scanner = new Scanner(System.in); while (!game.isSolved()) { System.out.println("当前棋盘："); printBoard(game); System.out.print("输入要移动的块编号（1-" + (game.getTileCount() - 1) + "，0退出）："); String line = scanner.nextLine(); int num; try { num = Integer.parseInt(line.trim()); } catch (NumberFormatException e) { System.out.println("输入的不是数字，请重试。"); continue; } if (num == 0) break; int index = num - 1; if (game.canMove(index)) { game.move(index); } else { System.out.println("这个块当前不能移动。"); } } printBoard(game); System.out.println(game.isSolved() ? "恭喜复原！" : "手动退出。"); scanner.close(); } private static void printBoard(NumberPuzzle game) { int size = game.getSize(); for (int r = 0; r < size; r++) { for (int c = 0; c < size; c++) { int v = game.getTile(r * size + c); System.out.printf("%2d ", v == 0 ? 0 : v); } System.out.println(); } } }

逻辑说明：这里我用nextLine()而不是nextInt()，是因为用户如果输入“3 空格回车”，nextInt()会把残留换行留给下一次输入，造成跳过。先用trim()去掉首尾空白，再解析，遇到非数字就continue，这样整个外部输入通道是干净的。打印棋盘用printf("%2d")对齐，改成石头迷阵时只需要把数字替换成图标名称。

参数说明：printBoard里通过game.getSize()拿边长，不再写死4。这个“小暴露”是重构的第一步，后续Swing版也会用到，避免在多个地方重复定义。

3.3 Swing界面：JButton网格、事件绑定与刷新策略

图形界面这一步，我推荐用Swing而不是JavaFX，原因只有一个：Swing是JDK自带的，零依赖，直接javac Main.java就能跑，适合项目实战和面试演示。JavaFX在较新的JDK里已经被拆分出去，配置成本更高。

import javax.swing.*; import java.awt.*; public class GamePanel extends JPanel { private final NumberPuzzle game; private final JButton[] buttons; public GamePanel(NumberPuzzle game) { this.game = game; int size = game.getSize(); setLayout(new GridLayout(size, size)); buttons = new JButton[size * size]; for (int i = 0; i < buttons.length; i++) { JButton button = new JButton(); button.setFont(new Font("SansSerif", Font.BOLD, 24)); int index = i; button.addActionListener(e -> { if (game.canMove(index)) { game.move(index); refresh(); } }); buttons[i] = button; add(button); } refresh(); } private void refresh() { int size = game.getSize(); for (int i = 0; i < buttons.length; i++) { int value = game.getTile(i); buttons[i].setText(value == 0 ? "" : String.valueOf(value)); buttons[i].setEnabled(value != 0); } } }

逻辑说明：按钮下标直接用一维棋盘下标，点击事件里先判断canMove再move，然后统一调refresh()。refresh()全量更新文字和可用状态，虽然简单，但16个按钮完全不会卡顿。setEnabled(false)让空白格不可点击，避免用户在空白块上点出“无法移动”的提示，体验更好。

这里有一个关键点：GamePanel不持有Scanner，只持有game对象，所有输入都来自事件回调。这样模型和视图彻底分离，后面如果改成REST接口或增加AI自动求解，都不需要动视图代码。

Main类只要创建一个JFrame，把GamePanel加进去即可：

import javax.swing.*; public class Main { public static void main(String[] args) { SwingUtilities.invokeLater(() -> { JFrame frame = new JFrame("数字华容道"); frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); frame.add(new GamePanel(new NumberPuzzle(4))); frame.pack(); frame.setLocationRelativeTo(null); frame.setVisible(true); }); } }

这里要注意用SwingUtilities.invokeLater启动Swing线程，而不是直接在main线程创建组件。这是Java面试题里常问的单线程模型，也算项目实战里的正规写法。如果你想往前后端分离项目实战方向扩展，也可以把NumberPuzzle抽成纯Java模型，再用Spring Boot暴露REST接口，前端用Vue调接口，不过那是另一个话题了。

4. 石头迷阵变体：图标代替数字、自定义尺寸与随机打乱算法

4.1 石头迷阵和数字华容道的关系：换皮不换核

“石头迷阵”听起来像另一个游戏，其实它只是数字华容道的换皮版本：把16个格子里1～15的数字替换成不同颜色或纹理的石头块，目标变成把石头按顺序排列。规则、移动逻辑、可解性检测完全复用。很多游戏项目实战的题目里写“数字华容道/石头迷阵”，目的就是让你把通用逻辑拆出来，UI只是主题。

我一般会把主题资源抽出来单独管理。数字版用一个int就行；石头版则需要维护Map<Integer, Icon>，把每个数字映射到一张图片。这样针对“石头迷阵”的改动，只会落在UI层，模型层一个字节都没变。这也是面试时能讲清楚“面向对象设计”的地方。

4.2 随机打乱为什么不能只靠shuffle：50%的错误局面过滤

初学者最容易犯的错误是直接对数组做Collections.shuffle，然后交给玩家。前面说过，随机洗牌只有一半情况可解。这也是很多“数字华容道项目”被投诉的根本原因。正确做法是洗完牌后用isSolvable检查，如果无解，就交换前两个非零块。

import java.util.*; public class PuzzleShuffler { public static void shuffle(NumberPuzzle game) { int size = game.getSize(); int[] tiles = new int[size * size]; for (int i = 0; i < tiles.length - 1; i++) tiles[i] = i + 1; tiles[tiles.length - 1] = 0; List<Integer> list = new ArrayList<>(); for (int v : tiles) list.add(v); Collections.shuffle(list); int[] shuffled = list.stream().mapToInt(Integer::intValue).toArray(); if (!NumberPuzzle.isSolvable(shuffled, size)) { // 交换前两个非零块，翻转奇偶性 int first = -1, second = -1; for (int i = 0; i < shuffled.length; i++) { if (shuffled[i] == 0) continue; if (first == -1) first = i; else if (second == -1) { second = i; break; } } int tmp = shuffled[first]; shuffled[first] = shuffled[second]; shuffled[second] = tmp; } game.setTiles(shuffled, findBlank(shuffled)); } private static int findBlank(int[] tiles) { for (int i = 0; i < tiles.length; i++) { if (tiles[i] == 0) return i; } return -1; } }

逻辑说明：交换两个非零块会把逆序数奇偶性翻转，因此无解变成有解。为什么交换两个而不是三个？因为一次相邻交换最少影响一次逆序数，两次交换又会翻回来，作为修正手段，单个对换是最小的改动。这里没有使用固定种子，如果想让测试可复现，可以让shuffle接收一个long seed参数传给Collections.shuffle。

参数说明：list.stream().mapToInt(...)是一种快速把List<Integer>转int[]的写法，熟悉Lambda的人会觉得很顺手。如果你还在用老版本Java，可以手动for循环填充。这个类独立成PuzzleShuffler，是因为它同时要被游戏初始化、关卡生成和测试代码调用。

4.3 自定义尺寸与难度参数化：从3x3到5x5

把size变成构造参数后，3x3（八数码）、4x4（十五数码）、5x5（二十四数码）都能跑。不同尺寸的判定差异已经在2.3里处理，UI的GridLayout也自动跟着变，主题映射则只需准备相应数量的图标。

难度参数除了尺寸，还可以控制打乱次数。但注意：打乱次数多不代表更难，因为移动路径可能重复，反而可能产生简单局面。更可靠的难度参数是“从目标状态反向随机走N步”，每步只做合法的反向移动。这样保证初始局面一定可解，而且步数有上限。这个思路本身就是一个递归回溯过程，和后面说的求解器形成闭环。

主题替换的代码可以像这样写：在GamePanel里增加一个applyTheme(Map<Integer, Icon> iconMap)方法，遍历按钮，把非空格按钮设置为对应图标。

public void applyTheme(Map<Integer, Icon> icons) { for (int i = 0; i < buttons.length; i++) { int value = game.getTile(i); if (value == 0) { buttons[i].setIcon(null); } else { buttons[i].setIcon(icons.get(value)); } } refresh(); }

逻辑说明：icons.get(value)直接按数字取资源，不需要知道具体是哪块石头。图片首次加载应该放在Main里统一做一次，存进Map再传入，避免每次刷新都读磁盘。石头迷阵界面还可以把数字改成石头1、石头2的标题，但核心逻辑完全一致。这个参数化过程也适合参加蓝桥杯数字拼图题，你只需要把size换成题目给的n。

5. 避坑：数字华容道Java项目实战的5个常见踩坑点

5.1 打乱后永远无法复原：shuffle撞上不可解排列

现象：玩家玩到只剩两个数字对调，无论怎么移都差一步；或者你自己测试时，从初始状态开始就找不到解。 原因：打乱只用了Collections.shuffle，没有做可解性检测。无序排列中有一半不可达，开局就是死局。 解决：打乱后调用2.3里的isSolvable，无解则交换前两个非零块。更稳妥的做法是采用4.3提到的“反向移动N步”生成局面，天然可解。我在项目里默认用后者，随机洗牌只留作彩蛋模式。

5.2 点击按钮后界面没反应，但调试信息显示move执行了

现象：控制台打印了移动成功的日志，但屏幕上的数字纹丝不动。 原因：移动后没有调用刷新方法，或者刷新时更新了模型数组但没更新按钮文字。 解决：在按钮事件里走统一的refresh()，这个函数负责把每个按钮的setText、setEnabled和图标都重新设置一遍。我写过一个反面案例：在move方法里刷新，结果控制台版也被牵连，出现了空指针。正确的做法是刷新只存在于UI层，模型层不做任何与界面有关的操作。

5.3 按钮文字和期望位置错位：一维下标与行列转换弄反

现象：你点击第3行第2列的块，结果第2行第3列在动。 原因：在UI代码里自己写了行列换算，比如index = row + col * size，而正确的是一维数组按行优先存储，index = row * size + col。二维数组如果直接用[col][row]，也会发生同样错位。 解决：模型层直接暴露一维下标，UI层不做二次转换。如果项目已经有二维数组，写一个to1D(int row, int col)工具方法，并加单元测试验证坐标映射。这个坑也常出现在拼图、扫雷、连连看之类的二维网格项目里，先统一好映射，后面就不会翻车。

5.4 5x5以上刷图卡顿：每次移动都重读图片资源

现象：3x3流畅，5x5或石头迷阵使用大量图片后，每次点击有明显卡顿。 原因：setIcon每次都从硬盘读ImageIcon，图片缩放也在刷新代码里重复执行。在Java里，磁盘I/O是最大的性能黑匣子，不能放到高频路径。 解决：在启动时把ImageIcon加载到Map<Integer, Icon>缓存，刷新时只做setIcon(icons.get(value))。如果需要缩放，用new ImageIcon(img.getScaledInstance(w, h, Image.SCALE_SMOOTH))，也放到初始化阶段。这样指数级减少I/O，界面自然流畅。

5.5 源码包导入后中文乱码或编译失败：编码与JDK版本不一致

现象：从网上拿来的源码在IDE里中文注释全乱，或者javac报“非法字符: '\uff1b'”这类错误。 原因：源码是GBK编码，而IDE默认UTF-8；或者用了var等新语法，但编译器还在JDK 8。 解决：用IDE的File Encodings把项目编码切到UTF-8，再统一转码；如果命令行编译，加-encoding UTF-8。对于JDK版本，在pom.xml里设置maven.compiler.source/target为一组自己验证过的版本，不要盲目用最新。源代码管理上，我习惯在项目根目录放一个.editorconfig，强制UTF-8和LF换行，这是被乱码坑过之后养成的习惯。这些坑如果写成自动化测试用例，也能变成很好的软件测试项目实战素材。

6. 进阶：给游戏加一个回溯求解器，用最少步数验证你的打乱算法

数字华容道项目做完后，我建议你再加一个自动求解功能。常见做法是BFS，但4x4的状态空间非常大，全量BFS会吃光内存。所以我改用迭代加深搜索（IDS），从深度0开始逐层加深，每次做DFS，并且跳过空白格本身来减少无效分支。这个策略对4x4随机打乱通常几十步内能出解，虽然不保证最少步数，但能作为打乱算法的反向验证。

import java.util.*; public class PuzzleSolver { public List<Integer> solve(NumberPuzzle game) { int maxDepth = 80; for (int depth = 0; depth <= maxDepth; depth++) { List<Integer> path = new ArrayList<>(); if (dfs(game, depth, path)) { return path; } } return null; } private boolean dfs(NumberPuzzle game, int depth, List<Integer> path) { if (game.isSolved()) return true; if (depth == 0) return false; int[] savedTiles = game.getTiles().clone(); int savedBlank = game.getBlankIndex(); for (int i = 0; i < game.getTileCount(); i++) { if (i == savedBlank) continue; if (!game.canMove(i)) continue; game.move(i); path.add(i); if (dfs(game, depth - 1, path)) return true; path.remove(path.size() - 1); game.setTiles(savedTiles, savedBlank); } return false; } }

逻辑说明：depth是递归层数，每层只额外做一步。savedTiles和savedBlank在递归前保存，回溯时恢复，保证状态不污染。i == savedBlank是跳过空白格本身，因为点击空白格没有意义；canMove(i)保证相邻。这个版本没有做严格的路径剪枝，如果你追求性能，可以再加一个prevIndex参数，避免把上一步刚移过来的块立刻移回去。

实际使用时，我在游戏初始化完成后调一次solve，如果返回的路径长度大于0，才把局面开放给玩家；如果返回null，说明打乱算法又出了问题。有一次我改了shuffle的种子逻辑，忘了重新验证，结果测试妹子玩三局就有两局死局，最后就是用这个求解器定位出来的。现在我的习惯是每个打乱器都配一个求解器做回归测试，测出平均求解步数和最大深度，作为难度指标写进项目说明里。这个小习惯帮我少了很多玄学调参的夜晚，希望帮到你。

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