搭建可复现的 Java 实验室

这篇教程带你搭建一个可编译、可测试、可复现的 Java 21 实验室。完成后，你会得到固定构建版本的 Maven 工程、一个通过的 JUnit 测试、可校验的 Compose 文件和一个 Git 仓库。

Open Table of contents

开始前准备
快速开始
理解工程结构
固定 Java 和测试版本
校验容器环境
建立可复现约束
下一步

开始前准备

你需要一个终端、JDK 21、Git、Maven 3.9 或更高版本，以及 Docker Desktop 或 Docker Engine。Windows 用户在 PowerShell 中将 ./mvnw 替换为 mvnw.cmd。

先运行版本检查：

java --version
mvn --version
git --version
docker compose version

如果命令不存在，请从 JDK 21 下载页、 Maven 安装文档、Git 安装页和 Docker Compose 安装文档完成安装。团队生产环境还要根据组织策略选择 JDK 发行版和支持周期。

快速开始

示例工程已经包含源码、测试和构建配置。按下面五步验证环境。

下载 pom.xml下载、 GreetingService.java下载、 Main.java下载和 GreetingServiceTest.java下载，并保持相同目录结构。
在工程根目录生成 Maven Wrapper：
```
mvn wrapper:wrapper -Dmaven=3.9.14
```
运行测试：
```
./mvnw test
```
运行程序：
```
./mvnw exec:java
```

初始化 Git 仓库：

git init -b main
git add .
git commit -m "初始化 Java 实验室"

测试应显示 BUILD SUCCESS，程序应输出：

你好，架构师学习者！

理解工程结构

Maven 使用约定目录，让构建工具和 IDE 不需要猜测文件用途。

java-lab/
├── .mvn/wrapper/                 # Wrapper 的 Maven 版本和下载配置
├── src/main/java/                # 生产代码
├── src/test/java/                # 测试代码
├── compose.yaml                  # 本地容器环境
├── mvnw                          # macOS/Linux 构建入口
├── mvnw.cmd                      # Windows 构建入口
└── pom.xml                       # 依赖和构建规则

Maven Wrapper 是随工程提交的构建入口。它在首次运行时下载指定 Maven 版本，使开发机和 CI 使用相同构建工具。官方用法是 ./mvnw <goal>，其中 **Goal（目标）**表示 Maven 要执行的任务，例如 test。

固定 Java 和测试版本

pom.xml 使用 maven.compiler.release=21，这同时限制语言语法和 Java 标准库 API。只设置编译器的 source 选项不能阻止代码误用更高版本 API。

测试使用 JUnit 6.0.1 和 Maven Surefire 3.5.5。JUnit 是 Java 测试框架，Surefire 是 Maven 在 test 阶段发现并运行测试的插件。

运行一个指定测试可以缩短反馈时间：

./mvnw -Dtest=GreetingServiceTest test

如果出现 release version 21 not supported，当前 Maven 使用的不是 JDK 21。先检查 mvn --version 显示的 Java 路径，再修正 JAVA_HOME 或 IDE 的 Maven JDK。

校验容器环境

下载 compose.yaml下载，然后检查配置是否能被 Compose 解析：

docker compose config --quiet

命令没有输出且退出码为 0 表示配置有效。第一次实际启动会下载 Java 21 运行时镜像：

docker compose run --rm java-version

容器应输出 Java 21 版本。这个检查证明你的容器环境不依赖开发机上的 JDK。

建立可复现约束

“在我的机器上可以运行”通常意味着版本、配置或数据没有进入工程。把这些约束显式化。

提交 Wrapper 脚本和 .mvn/wrapper，不要提交本机 Maven 缓存。
提交 .env.example，不要提交真实密码、Token 或私钥。
在 pom.xml 固定插件版本，避免默认版本随环境变化。
在 README 或实验报告中记录操作系统、CPU 架构和 Docker 版本。
让 CI 运行与本地相同的 ./mvnw test。

Maven Wrapper 会下载构建工具，因此生产团队还应配置内部制品代理、SHA-256 校验和依赖来源审计。可参考 Maven Wrapper 官方说明。

下一步

阅读如何读源码：调用链、断点、测试与最小复现，使用刚搭建的实验室练习从问题进入源码，而不是无目标地逐行阅读。