# 为什么正式教程应先验证完整工程环境，而不是从复制第一段 Java 代码开始

```text
旧方案：复制第一段 Java 代码 → 本地缺 JDK/依赖/数据库 → 编译失败、连接失败、调试失败 → 学习者以为框架难用
```

很多 Spring 教程一上来就贴 Controller、Service、Repository，默认读者已经装好 JDK、IDE、Maven、数据库和调试工具。

但真实工程里，环境不一致才是第一道墙。

我是老李，带团队接手过不少“代码能跑、环境跑不起来”的项目。

一个正式教程应该先验证完整工程环境，还是先复制第一段 Java 代码？

应该把 JDK、Maven、IDE、Docker、MySQL、Redis、HTTP 调试和 JVM 诊断一次打通，还是只保证单文件编译通过？

如果选错，会不会让后续每一章都在修环境，而不是学 Spring Boot？

# 01、故事

```text
周一 09:40 → 新同事工位 → 任务是跑起 Petclinic → 本地 JDK 版本不对、MySQL 没装、Debug 不会看线程 → 项目启动失败
```

周一早上，新同事被要求把 Spring 官方 Petclinic 跑起来。

任务是“先让项目在本机启动，能访问首页”。

他打开 IDE，导入项目，Maven 一直下载失败。

旁边同事催着要联调，他只能反复重启 IDE。

搜到的答案一会儿说改镜像，一会儿说装 JDK 17，一会儿又说要本地 MySQL。

他卡了两个小时，连 main 方法都没进去。

> 晨会催得急，
> 环境未通先写码。
> 报错层层叠，
> 不知根在哪。

# 02、问题

```text
需求变化：从“能编译”到“能开发、能调试、能连库、能观测” → 旧环境只验证 javac → 数据库、容器、调试、诊断全部失效
```

只验证 javac 或 IDE 里能打开文件，并不能证明工程环境可用。

Petclinic 需要 Maven Wrapper 下载依赖，需要 Docker 启动 MySQL 和 Redis，需要 IDE 连接源码和运行进程。

如果这些链路不通，后续数据访问、缓存、事务、测试、容器化章节都会反复失败。

可验证的验收标准是：执行 ./mvnw test 通过，./mvnw spring-boot:run 能启动，HTTP 请求能访问首页，Debug 能停在断点，MySQL 和 Redis 能通过客户端

验证。

> 编译非终点，
> 链路未通皆虚妄。
> 库连不上时，
> 代码再美也空转。

# 03、原理

```text
开发链 = JDK → Maven Wrapper → IDE → Docker → MySQL/Redis → Spring Boot → HTTP → Debug/JVM 诊断
```

Spring Boot 不是只靠 Java 文件运行。

它启动时要解析依赖、读取配置、连接数据源、暴露端口、注册 Bean。

Maven Wrapper 固定 Maven 版本，避免本机 Maven 差异。

Docker 统一 MySQL 和 Redis 版本，避免“我本地能跑，你本地不行”。

IDE 的 Debug 能力依赖源码与运行进程的对应关系。

JVM 诊断工具依赖 JDK 自带命令与运行用户权限。

反直觉的是：环境验证越早，业务代码写得越慢，但整体交付越快。

> 慢即是快时，
> 先铺管道后引水。
> 若先砌高墙，
> 水到墙前也白费。

# 04、架构

```text
输入：官方 Petclinic 源码 + 本机开发机 → 环境层：JDK/IDE/Maven/Docker/MySQL/Redis/HTTP/JVM 工具 → 输出：可运行、可调试、可观测的工程基线
```

这一篇不新增业务模块，而是建立工程基线。

基线分四层：语言运行时、构建工具、外部依赖、观测调试。

语言运行时是 JDK 21，构建工具是 Maven Wrapper，外部依赖是 Docker 中的 MySQL 和 Redis，观测调试是 IDE Debug 与 JDK 诊断命令。

收益是后续每章都能在一致环境上验证。

代价是首次搭建时间较长。

适用条件是所有需要长期演进同一个代码仓库的正式项目。

> 基线如地基，
> 不显眼却承千钧。
> 工具链贯通，
> 后续方可行远路。

# 05、第一版实战

```text
环境：macOS/Linux/Windows + JDK 21 + IntelliJ IDEA + Docker Desktop → 配置：JAVA_HOME、Maven Wrapper、MySQL、Redis → 代码：官方 Petclinic → 启动：./mvnw spring-boot:run → 验证：HTTP 200、Debug 断点、redis-cli PING → V1：全链路首次跑通
```

第一步安装 JDK 21。

以 macOS 为例：

```bash
brew install openjdk@21
```

配置 JAVA_HOME：

```bash
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
export PATH="$JAVA_HOME/bin:$PATH"
```

验证：

```bash
java -version
javac -version
```

示例输出：

```text
openjdk version "21.0.2" 2024-01-16
OpenJDK Runtime Environment (build 21.0.2+13-58)
OpenJDK 64-Bit Server VM (build 21.0.2+13-58, mixed mode, sharing)
javac 21.0.2
```

第二步安装 IntelliJ IDEA，打开 Petclinic 后设置 Project SDK 为 JDK 21。

在 IDEA 中确认 Maven Wrapper 使用项目自带 .mvn/wrapper。

第三步安装 Docker Desktop 并启动。

启动 MySQL：

```bash
docker run -d --name petclinic-mysql \
  -e MYSQL_ROOT_PASSWORD=root \
  -e MYSQL_DATABASE=petclinic \
  -e MYSQL_USER=petclinic \
  -e MYSQL_PASSWORD=petclinic \
  -p 3306:3306 \
  mysql:8.4
```

启动 Redis：

```bash
docker run -d --name petclinic-redis \
  -p 6379:6379 \
  redis:7.4
```

验证 Redis：

```bash
docker exec -it petclinic-redis redis-cli PING
```

示例输出：

```text
PONG
```

第四步克隆官方项目：

```bash
git clone https://github.com/spring-projects/spring-petclinic.git
cd spring-petclinic
```

执行测试：

```bash
./mvnw test
```

启动应用：

```bash
./mvnw spring-boot:run
```

访问：

```bash
curl -I http://localhost:8080
```

示例输出：

```text
HTTP/1.1 200
```

第五步在 IDEA 中给 PetClinicController 的 showOwner 方法打断点，用 Debug 启动，浏览器访问 /owners/find，确认断点命中。

再练习条件断点、异常断点、Evaluate Expression 和线程查看。

第六步验证 JVM 诊断工具：

```bash
jcmd
jstack <pid>
jmap -histo <pid>
```

V1 完成标志：JDK、Maven、IDE、Docker、MySQL、Redis、Spring Boot、HTTP、Debug 全部跑通。

> 一链通到底，
> 从编译到断点停。
> 库中表可见，
> 缓存 PONG 回应声。

# 06、排查

```text
诊断树：启动失败 → 是 JDK 版本？是 Maven 依赖？是数据库连接？是端口占用？是 Docker 未启动？
```

问题一：./mvnw 报 Unsupported class file major version 65。

怀疑是 Maven 使用的 JDK 版本低于 21。

检查：

```bash
./mvnw -version
```

证据显示 Maven 运行在 JDK 17 上。

根因是 JAVA_HOME 未生效或 IDE 终端继承了旧环境变量。

修复：重新 export JAVA_HOME 并重启终端。

问题二：应用启动报 Access denied for user 'petclinic'@'localhost'。

怀疑是 MySQL 账号权限或密码不匹配。

检查：

```bash
docker exec -it petclinic-mysql mysql -upetclinic -ppetclinic -e "SELECT 1"
```

证据显示账号无法登录。

根因是容器创建时 MYSQL_USER 与 MYSQL_PASSWORD 未同时生效，或旧容器残留。

修复：删除旧容器和 volume，重新创建。

**错误尝试：** 一开始只改 application.properties 里的密码，没有重建容器，导致反复报同样的错。

> 报错如迷雾，
> 先查版本再查权。
> 莫急改配置，
> 证据未齐勿下判。

# 07、优化

```text
V1：手动 export JAVA_HOME、手动 docker run → 证据：换终端失效、容器参数易漏 → V2：固定 JDK 配置、用 Docker Compose 管理 MySQL 和 Redis
```

V1 的问题在于环境配置散落在多个终端和命令历史里。

换一个终端窗口，JAVA_HOME 就失效。

MySQL 和 Redis 每次手动 docker run，参数容易漏。

V2 把 JDK 配置写入 shell 配置文件：

```bash
echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 21)' >> ~/.zshrc
source ~/.zshrc
```

再用 Docker Compose 管理 MySQL 和 Redis：

```yaml
services:
  mysql:
    image: mysql:8.4
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: petclinic
      MYSQL_USER: petclinic
      MYSQL_PASSWORD: petclinic
    ports:
      - "3306:3306"
    volumes:
      - mysql-data:/var/lib/mysql
  redis:
    image: redis:7.4
    ports:
      - "6379:6379"
volumes:
  mysql-data:
```

启动：

```bash
docker compose up -d
```

这样环境可重复、可版本化。

> 散落终成患，
> 配置入文件方安。
> 容器归编排，
> 一键起落不慌乱。

# 08、演进

```text
V2：JDK 配置持久化 + Docker Compose 管理依赖 → 能力：环境可重复、可重建、可交接 → 遗留：IDE 配置和 JVM 诊断脚本尚未标准化
```

V2 之后，新同事拿到项目，只需安装 JDK 21、IDEA、Docker Desktop，然后执行 docker compose up -d 和 ./mvnw spring-boot:run。

用 V1 同一组请求验证：./mvnw test 通过，curl -I http://localhost:8080 返回 200，redis-cli PING 返回 PONG，Debug 断点命中。

收益是环境搭建从两小时降到二十分钟。

代价是首次需要理解 Docker Compose 文件。

适用条件是团队统一使用容器化外部依赖。

遗留问题是 IDE 的 Run Configuration 和 JVM 诊断命令还没有沉淀成团队文档。

> 从散到有序，
> 环境不再靠口传。
> 新人接手工，
> 二十分钟可开战。

# 09、洞见

```text
从“先写代码”到“先验证环境”，本质是从个人英雄主义转向工程基线思维
```

## 环境是代码的运行时契约
```text
代码 → 依赖 → 配置 → 外部服务 → 端口 → 观测
```

代码只是链路的一环。

没有 JDK、Maven、数据库和调试工具，代码无法被验证。

正式教程先验证环境，是在确认运行时契约成立。

## 反直觉判断：先慢后快
```text
首日搭环境 2 小时 → 后续每章省 30 分钟 → 24 章省 12 小时
```

很多人觉得搭环境浪费时间。

但环境问题不会消失，只会推迟到最不方便的时候爆发。

## 反直觉判断：容器不是运维的事
```text
开发库也进容器 → 版本一致 → 减少“我本地能跑”
```

开发阶段就用容器，能提前暴露配置、网络和权限问题。

等到上线才容器化，往往已经积累了大量环境假设。

## 调试能力是工程素养
```text
断点 → 条件 → 异常 → 表达式 → 线程 → JVM 命令
```

只会普通断点的人，遇到偶发问题只能加日志重启。

条件断点、异常断点和线程查看能大幅缩短定位时间。

> 契约先立定，
> 慢行反是快行舟。
> 容器非运维，
> 调试素养不可丢。

# 10、系统落地

```text
入口：开发者本机 → 服务：IDE + Maven Wrapper → 本模块：环境基线 → 存储：Docker MySQL/Redis → 未实现：业务代码尚未改动
```

原来只有官方 Petclinic 源码，没有统一的本地环境说明。

本篇增加了 JDK 21、Maven Wrapper、IDEA Debug、Docker Compose、MySQL、Redis、HTTP 调试和 JVM 诊断工具的环境基线。

现在能做什么：任何新成员可以在二十分钟内跑起 Petclinic，并具备调试和观测能力。

下一篇缺什么：还没有深入 Spring Boot 启动机制，需要解释 main 方法如何拉起内嵌 Tomcat 和 Spring 容器。

官方链接：https://github.com/spring-projects/spring-petclinic

> 基线已铺就，
> 开发调试皆可依。
> 下一程启程，
> 深入启动探玄机。

# 11、小结

```text
三问三答：先验证环境 → 先打通全链路 → 选错会反复修环境
```

第一问：正式教程应该先验证完整工程环境，因为环境是代码的运行时契约。

第二问：应该把 JDK、Maven、IDE、Docker、MySQL、Redis、HTTP 调试和 JVM 诊断一次打通，因为任何一环缺失都会阻塞后续章节。

第三问：如果选错，后续每一章都会在修环境，而不是学 Spring Boot，最终失去对框架本身的信心。

当前状态：Petclinic 已在本机稳定运行，测试通过，数据库和缓存可验证，Debug 和 JVM 诊断可用。

> 三问皆已答，
> 环境先行是正解。
> 链路全贯通，
> 后续章节少波折。

# 12、作业

```text
理解 → 实战 → 排障 → 架构判断
```

## 理解题：为什么 Maven Wrapper 比本机全局 Maven 更适合正式教程？

Maven Wrapper 把 Maven 版本固定在项目里，所有开发者执行 ./mvnw 时使用同一版本，避免本机 Maven 版本差异导致的构建不一致。

## 实战题：用 Docker Compose 启动 MySQL 和 Redis，并分别验证连接、建表、SET/GET 和 TTL。

执行 docker compose up -d 后，用 docker exec -it petclinic-mysql mysql -upetclinic -ppetclinic petclinic

连接，执行 SHOW TABLES；

用 docker exec -it petclinic-redis redis-cli 执行 SET k v、GET k、TTL k。

## 排障题：应用启动报 Communications link failure，但 MySQL 容器在运行，如何定位？

先检查端口映射：docker port petclinic-mysql。

再检查应用配置的数据库地址是否为 localhost:3306。

再检查 MySQL 是否已接受连接：docker logs petclinic-mysql。

最后检查防火墙或 Docker 网络是否隔离。

## 架构判断题：开发环境是否应该完全依赖本地安装的 MySQL，而不是容器？

不应该。

本地安装的 MySQL 版本、配置和权限难以统一，容器能保证开发、测试、生产环境的一致性，减少“我本地能跑”的问题。

> 四题如四关，
> 理解实战排障判。
> 环境既已通，
> 后续深入不迷航。

# 13、升华

```text
工程结论：先验证完整环境，再写业务代码，是正式教程的第一原则
```

有依据的结论是：环境问题不会因为忽略而消失，只会推迟到更贵的阶段爆发。

Petclinic 作为长期演进项目，必须先把开发、运行、调试、观测的基线打牢。

下一篇将进入 Spring Boot 启动机制，解释 main 方法如何触发自动配置、内嵌容器和 Bean 装配。

> 地基既已深，
> 高楼方可层层起。
> 环境为序章，
> 启动机制是正题。

**系列项目：** Spring 官方 Petclinic 教学项目，服务兽医诊所的宠物与主人管理。

**已完成：** JDK 21、Maven Wrapper、IntelliJ IDEA、Docker Desktop、MySQL、Redis、HTTP 调试、JVM 诊断工具与 Petclinic 首次运行。

**本篇：** 建立可重复、可调试、可观测的完整工程环境基线。

**下一篇：** 深入 Spring Boot 启动机制，理解 main 方法、自动配置与内嵌容器。

很多 Spring 教程一上来就贴 Controller、Service、Repository，默认读者已经装好 JDK、IDE、Maven、数据库和调试工具。

《SpringBoot4进阶实战》第1招 搭好Java开发环境

以 Petclinic 为例，先搭通 JDK、IDE、Docker、MySQL、Redis、HTTP 与 JVM 诊断全链路，再谈业务代码。

架构师

编程语言

后端

开发工具

正式教程应先验证完整工程环境而非直接贴代码，因为JDK、Maven、Docker、MySQL、Redis、Debug和JVM工具链任何一环缺失都会阻塞学习。环境是运行时契约，提前打通全链路可避免后续每章修环境，将搭建时间从两小时降至二十分钟，确保可运行、可调试、可观测的工程基线。

代码解释

数据库

防火墙

Windows

容器

MySQL

Redis

Linux

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

《SpringBoot4进阶实战》第1招 搭好Java开发环境-腾讯云开发者社区-腾讯云

《SpringBoot4进阶实战》第1招搭好Java开发环境

《SpringBoot4进阶实战》第1招搭好Java开发环境

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《SpringBoot4进阶实战》第1招 搭好Java开发环境

《SpringBoot4进阶实战》第1招 搭好Java开发环境

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《SpringBoot4进阶实战》第1招搭好Java开发环境

《SpringBoot4进阶实战》第1招搭好Java开发环境