新建一个空目录,里面只放三样东西:一个 pom.xml、一个 DemoApplication.java、一个返回固定 JSON 的控制器。执行 mvn -q -DskipTests package,再执行 java -jar target/demo-0.0.1.jar,进程立刻退出,退出码 1,报错是这样两句:
java.lang.UnsupportedClassVersionError: org/springframework/boot/loader/launch/JarLauncher
has been compiled by a more recent version of the Java Runtime (class file version 61.0),
this version of the Java Runtime only recognizes class file versions up to 55.0
这不是代码写错,也不是依赖没下全,而是运行这个 jar 的 Java 太旧。这台 Windows 11 机器上同时装了 Microsoft JDK 21 和 Oracle JDK 11,命令行默认指向 11。报错里 61.0 是 Java 17 的字节码版本(Spring Boot 3.x 自带的启动器就是按 17 编的),55.0 是 Java 11 能认到的上限,连启动器都加载不了,自然谈不上启动。
这篇只讲「怎么把一个服务搭起来并能上线」,Java 语法不在这里展开,需要补语法可以看 Java 基础语法。下面按真实顺序走:先定技术选型,再列环境和依赖,写出第一个能返回 JSON 的接口,打包启动,最后给一张启动失败时的排查表。
启动就退出:最少要检查的三件事
第一次遇到「进程秒退」,不要急着读业务代码,先按顺序确认运行环境。第一步看 java -version,注意是执行 java 的那个版本,不是 JAVA_HOME 里写的版本,两者经常不一致。第二步看 mvn -v 最后一行显示的 JDK,Maven 编译用的 JDK 和运行用的 JDK 可以完全不同。第三步看 jar 是不是可执行 jar,正常的 Spring Boot 包解压后应该有 BOOT-INF 目录和 org.springframework.boot.loader 相关的类,没有就说明打包插件没生效。
这台机器的实际情况是:mvn -v 显示 Apache Maven 3.9.9、runtime 是 JDK 21,但新开的终端里 java -version 仍然是 11。原因是系统变量 JAVA_HOME 指到了 11 的目录,而 Maven 用了另一份配置。解决办法不是改代码,而是把当前终端切到 21:临时设置 JAVA_HOME 指向 21 的安装目录,再把它的 bin 放到 PATH 最前面,重新开一个窗口确认 java -version 变成 21.0.13。
Windows 上切换 JDK 还有一个细节:改完系统变量要重新开终端,已经打开的窗口和 IDE 里的终端仍然拿着旧值。执行 where java 可以看到所有在 PATH 里的 java.exe,第一行才是真正被调用的那个。如果第一行指向 Program Files\Java\jdk-11,就把 21 的 bin 目录往前挪,或者直接在项目里用绝对路径的 java 启动,先把第一个接口跑通再整理环境。
为什么选 Spring Boot
Spring Boot 不是一个新框架,它是在 Spring 之上加了一层「默认答案」。Spring 本身能做的事它都能做,区别在于大量配置被约定替代:加一个 web 依赖就自带内嵌 Tomcat,配置文件放在 application.yml 就自动读,包扫描从启动类所在包往下找,不需要额外写 XML。这种「约定大于配置」省掉的不是几行代码,而是团队每次起项目都要重新讨论一遍的装配方式。
第二个理由是内嵌 Tomcat。传统 Java Web 的部署方式是打 war 包,丢进一个独立安装的 Tomcat 的 webapps 目录,容器和应用的版本、端口、连接器参数都要在容器外面配。Spring Boot 把 Tomcat 10.1.31 打进 jar 里,java -jar 就是一个完整的 HTTP 服务,部署单元从「容器加 war」变成「一个 jar 加一份配置」,回滚也简单:换回上一个 jar。
第三个理由是生态覆盖。数据库连接、迁移、健康检查、参数校验、安全、消息、缓存,官方和社区都有成熟的 starter,遇到问题时能搜到的答案也多。代价是依赖树会变大,一个 web 加 jdbc 的项目,依赖数量轻松过三十个,排查版本冲突时要会看 mvn dependency:tree。
用 Spring Boot
起步快,约定齐全,内嵌容器让部署单元变成一个 jar。适合绝大多数业务 API 和内部系统,也适合团队里没有专职中间件运维的情况。
手写 Spring MVC 加外置 Tomcat
装配完全可控,容器升级、连接器调优、类加载隔离都能自己定。代价是初始配置多,部署流程复杂,出问题时要在容器和应用两侧分别排查。
还有一条现实因素:招人和交接。Spring Boot 是国内 Java 后端最通用的口径,新人进来第一周就能改接口。如果项目本身有特殊约束,比如必须跑在已有的 WebLogic 里,或者对启动时间有硬指标,那才值得考虑不用它。否则选它省下的是长期沟通成本。
需要说清楚「starter」是什么:它不是框架,也不是插件,而是一组依赖的集合加上一份自动配置。加 spring-boot-starter-web,实际引入的是 Spring MVC、Jackson、内嵌 Tomcat 和校验组件;加 spring-boot-starter-jdbc,引入的是数据源、JdbcTemplate 和 HikariCP。知道这层关系,遇到「为什么我没写连接池代码却有连接池」时就不会困惑。
内嵌容器还带来一个隐性好处:开发、测试、生产三套环境用的是同一个 Tomcat 版本和同一份配置入口。外置容器的项目里,本地用 Maven 插件跑、测试用另一个 Tomcat、生产又是运维装的版本,连接器和编码参数的差异只有上线后才暴露。这个一致性在排查「本地好好的、线上乱码」这类问题时非常值钱。
环境与依赖清单
下面这套版本是这台机器上实际跑通的组合,逐项列清楚,缺一项都会在某个时刻报错。注意版本不是越新越好,Spring Boot 3.3.5 对应的 Tomcat、HikariCP、Flyway 都是它自己管好的,不要手动指定这些小版本,否则容易和自动配置打架。
| 组件 | 版本 | 作用 | 缺失或版本不对时 |
|---|---|---|---|
| JDK | Microsoft JDK 21.0.13 | 编译和运行 | 低于 17 时类加载失败,进程秒退 |
| Maven | 3.9.9 | 依赖管理与打包 | 无法解析 starter,或插件版本不兼容 |
| Spring Boot | 3.3.5 | 自动配置与依赖版本管理 | 父 pom 写错则依赖版本全乱 |
| 内嵌 Tomcat | 10.1.31 | 提供 HTTP 服务 | 缺 web starter 时服务不监听端口 |
| HikariCP | 5.1.0 | 数据库连接池 | 没有 jdbc starter 时启动报无 DataSource |
| Flyway | 10.10.0 | 数据库版本迁移 | 缺 flyway-core 时不执行迁移脚本 |
| H2 | 2.2.224 | 本机演示用内存数据库 | 缺驱动时报无法识别 JDBC URL |
依赖清单用父 pom 统一管理版本,自己只写 artifact,不写 version。下面这段就是完整依赖,可以直接抄进 pom.xml:
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.3.5</version>
</parent>
<properties>
<java.version>21</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-core</artifactId>
</dependency>
</dependencies>
两个容易忽略的点:h2 的 scope 是 runtime,编译时不该出现它的类;flyway-core 不需要写版本,父 pom 已经锁到 10.10.0。若手动写一个不匹配的 Flyway 版本,启动时会看到自动配置类找不到,报错信息通常不直观。
目录结构与第一个接口
目录不追求复杂,先按职责分四层:入口、接口层、业务层、数据层。小项目里 service 和 repository 可以暂时合并,但目录先留出来,后面加事务和迁移时不用大搬家。下面这个结构用分层卡片表示,越靠上越接近外部请求:
启动类必须放在所有业务类的最外层包,因为默认的组件扫描从这个类所在的包往下找。放到 com.example.demo.app 里而控制器在 com.example.demo.web,扫描不到,接口就会 404。这种 404 没有任何异常日志,只有一行访问记录,第一次遇到很容易怀疑路由写错。
启动类只有一行有效代码,但两个注解都不能省。@SpringBootApplication 把自动配置、组件扫描、配置类注册三件事合在一起:
package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
第一个接口选健康检查,因为它同时验证了 Web 和数据库两条链路。控制器注入 JdbcTemplate,执行一条 select 1,成功就返回两个字段。这里用 Map.of 直接构造响应,字段顺序在 JSON 里就是 status 在前、db 在后:
package com.example.demo.controller;
import java.util.Map;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HealthController {
private final JdbcTemplate jdbc;
public HealthController(JdbcTemplate jdbc) {
this.jdbc = jdbc;
}
@GetMapping("/health")
public Map<String, Object> health() {
jdbc.queryForObject("select 1", Integer.class);
return Map.of("status", "up", "db", true);
}
}
配置文件放在 src/main/resources/application.yml,端口用 8081,避开本机可能已经被占用的 8080。H2 用内存模式,加 DB_CLOSE_DELAY=-1 是为了让最后一个连接关闭后数据库不消失,否则连接池空闲回收时表就没了:
server:
port: 8081
spring:
datasource:
url: jdbc:h2:mem:app;DB_CLOSE_DELAY=-1
username: SA
password: ""
flyway:
locations: classpath:db/migration
app:
secret: ${APP_SECRET:dev-secret}
app.secret 这种写法表示优先读环境变量 APP_SECRET,没有就用冒号后面的开发默认值。把密钥写死在 yml 里迟早会进仓库,这一篇先埋下这个约定,第四篇讲令牌时会用到它。
这里没有手写 JSON 转换,是因为 web starter 已经带了 Jackson。控制器返回 Map 或普通对象,Spring 会调用消息转换器把它序列化成 JSON,并把 Content-Type 设成 application/json。字段顺序按 Map 的迭代顺序来,不保证跨版本稳定;对外接口如果需要固定顺序,就定义一个明确的返回对象,而不是依赖 Map 的偶然顺序。
启动后第一次请求健康检查,返回内容必须和下面逐字一致。注意 curl -s 去掉了进度信息,看到的就是响应体本身:
curl -s 127.0.0.1:8081/health
{"status":"up","db":true}
Flyway upgrade recommended: H2 2.2.224 is newer than this version of Flyway and support has not been tested. 这是版本组合的提示,不代表迁移失败。真正的迁移结果要看紧随其后的 Successfully applied 1 migration。打包、启动与真实日志
开发阶段用 mvn spring-boot:run 方便,但生产不要用它。生产打可执行 jar,构建和运行分开,构建机不需要装运行时,运行机不需要装 Maven:
mvn -q -DskipTests package
java -jar target/demo-0.0.1.jar
-DskipTests 只跳过测试执行,仍然会编译测试代码;-Dmaven.test.skip=true 连测试代码都不编译,构建更快,但会漏掉编译期错误。日常提交前跑一次不带跳过参数的 mvn package,部署时才用跳过参数。
启动过程在控制台能按顺序看到几条关键日志。先是 Tomcat 初始化并绑定端口,然后是连接池建连、Flyway 迁移、Tomcat 真正启动,最后是总耗时:
Tomcat initialized with port 8081 (http)
HikariPool-1 - Added connection conn0: url=jdbc:h2:mem:app user=SA
Flyway ... Migrating schema "PUBLIC" to version "1 - init"
Successfully applied 1 migration to schema "PUBLIC", now at version v1
Tomcat started on port 8081 (http) with context path '/'
Started DemoApplication in 9.799 seconds
9.799 秒是这台机器上的真实启动时间,包含 JVM 启动、类加载、连接池预热和迁移。第二次启动通常会快一些,因为操作系统缓存了 jar 文件;但在容器里每次都是冷启动,这个数字会稳定在十秒上下。给健康检查留的初始等待时间要大于它,否则编排系统会在服务还没起来时就判定失败并反复重启。
还有一条判断启动成功的土办法:看日志最后一行是不是 Started DemoApplication。前面出现异常但进程没退的情况也存在,比如端口冲突被捕获后重试,所以不能只看「进程还在」。
启动时还可以带参数覆盖配置,不用改 yml,也不用重新打包,例如 java -jar target/demo-0.0.1.jar --server.port=9090。命令行参数优先级高于环境变量,环境变量高于 yml,这个顺序在第六篇讲配置外置时会再展开。先用它验证配置文件到底有没有生效,比改文件重启更快。
启动失败时的对照表
下面这张表按「现象」查,不按理论分类。左边一列尽量写成你实际会看到的那句话,中间写根因,右边写第一条该执行的命令或该看的位置。顺序从上到下,越靠前越常见:
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 进程秒退,UnsupportedClassVersionError | 运行用的 JDK 低于 17 | java -version 和 mvn -v 的 JDK 是否一致 |
| 日志报 Port 8081 already in use | 端口被其他进程占用,或上次进程没退干净 | 用 netstat -ano 找 8081 对应的 PID |
| java -jar 报 no main manifest attribute | 没执行 spring-boot 插件的 repackage | 解压 jar 看有没有 BOOT-INF 目录 |
| 访问接口 404,日志无异常 | 控制器不在启动类所在包的下层 | 看启动类的包名和控制器包名 |
| 启动报 Failed to determine a suitable driver class | 数据源地址没配或驱动不在 classpath | 看 spring.datasource.url 和 h2 的 scope |
| Flyway 报错后进程退出 | 迁移脚本语法错,或连接池容量不够 | 看第一条 Flyway 异常和 db/migration 下的文件 |
| 本机 curl 通,服务器上不通 | 服务绑在 127.0.0.1,或安全组没放行 | 看 server.address 与实际监听地址 |
| 改了代码但行为没变 | 跑的是旧 jar,构建没重新打包 | 对比 target 下 jar 的修改时间 |
这张表里最值得记住的是第一行和第四行:前者是环境问题,后者是包结构问题,两类都不产生业务异常,日志里也看不出「代码写错」的痕迹。排查时先确认「进程用的是哪个 Java、jar 里到底装了什么」,能省掉大量试错。
使用时按现象逐行往下找,找到匹配的就先做右边那一步,不要一次改三个地方。很多时候「重启后好了」只是因为上次端口没释放,如果同时改了配置和代码,下次再遇到就不知道是哪一项起的作用。一次只动一个变量,是这个表真正的用法。
边界与代价
Spring Boot 的启动成本是实打实的:空服务 9.799 秒,依赖越多越慢。它适合常驻进程,不适合「来一个请求启一次」的场景。如果你的部署方式是函数计算,冷启动十秒基本不可接受,要么用预留实例,要么换更轻的运行时。这不是 Boot 的缺陷,是「把整个容器装进进程」这个选择的必然代价。
内存也有下限。一个带 web、jdbc、actuator 的空服务,JVM 堆加上元空间、线程栈、直接内存,常驻两三百兆是常态,具体数字随堆参数变化。给容器设 256 兆内存限制再跑它,很容易在启动阶段就被系统杀掉,日志里只看到进程退出,看不到 Java 异常。这个现象第六篇会展开。
jar 体积同样不小,web 加 jdbc 的包通常在二十兆以上,因为内嵌 Tomcat 和一堆自动配置类都打进去了。带来的直接好处是运行机不需要预装容器;坏处是每次发布都要传更大的文件,镜像层也更厚。分层构建、把依赖层和业务层拆开,可以让日常发布只传变化的那几兆。
到什么时候该考虑换方案?三个信号:启动时间成为发布瓶颈,比如每次滚动发布要等半分钟以上;内存单位成本远高于机器成本,比如边缘节点只有几十兆;依赖冲突频繁到每次升级都要花几天。满足其中两个,才值得评估 GraalVM 原生镜像或更轻的框架。只因为「感觉重」就换,通常会把省下的启动时间花在补基础设施上。
还有一个边界是团队能力。Boot 的自动配置在出问题时是黑盒,比如数据源没建起来,报错可能出现在很远的地方。会用的人看条件装配报告就能定位,不会的人只能一行行加日志。把 --debug 启动参数和条件评估报告写进排查手册,比换框架有效。
最后算一笔部署账。单实例启动十秒,滚动发布时新实例要等健康检查通过才接流量,用户感知到的不可用时间取决于实例数和摘流速度,而不是启动时间本身。两台实例轮流发,通常能做到零中断;只有一台时,任何重启都是几十秒的空白。真要在意这个数字,先加实例,再考虑换运行时,顺序别反。
当天能自己验证的练习
- 用
java -version和mvn -v分别记录两个 JDK 路径,然后只改当前终端的JAVA_HOME,确认java -version变成 21,再启动 jar。 - 把
server.port改成 8080 启动一次,再用另一个终端占用 8080,重启服务,把「端口被占用」的原文日志抄下来。 - 把启动类移到子包
com.example.demo.app,保留控制器原包,访问/health,确认返回 404 且日志无异常。 - 执行
jar tf target/demo-0.0.1.jar,找BOOT-INF/classes和BOOT-INF/lib,理解可执行 jar 的内部布局。 - 用
curl -i请求/health,把状态行、Content-Type 和响应体三部分分别记下来,确认 JSON 的类型是application/json。
小结
三句话收束:Spring Boot 的价值是约定和内嵌容器,让部署单元变成一个 jar;启动失败先分清是环境问题还是包结构问题,JDK 版本和组件扫描范围是最常见的两个根因;9.799 秒的启动时间是选型的代价,不是异常。
下一篇讲一个请求进来之后到底经过了哪些环节。这一篇只证明了「服务能起来、接口能返回」,但真实项目里,请求要先过过滤器、再过拦截器、才进控制器,异常还要走统一出口。把这些顺序搞明白,后面加鉴权和日志时才知道该把代码放在哪一层。