新建一个空目录,里面只放三样东西:一个 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。

线上机器同样会遇到这个问题。容器镜像里装的是 JRE 11,构建流水线用的是 JDK 21,构建成功、部署即退。把「运行镜像的基础 JDK 版本」写进部署检查清单,比事后看日志便宜得多。

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 都是它自己管好的,不要手动指定这些小版本,否则容易和自动配置打架。

组件版本作用缺失或版本不对时
JDKMicrosoft JDK 21.0.13编译和运行低于 17 时类加载失败,进程秒退
Maven3.9.9依赖管理与打包无法解析 starter,或插件版本不兼容
Spring Boot3.3.5自动配置与依赖版本管理父 pom 写错则依赖版本全乱
内嵌 Tomcat10.1.31提供 HTTP 服务缺 web starter 时服务不监听端口
HikariCP5.1.0数据库连接池没有 jdbc starter 时启动报无 DataSource
Flyway10.10.0数据库版本迁移缺 flyway-core 时不执行迁移脚本
H22.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 可以暂时合并,但目录先留出来,后面加事务和迁移时不用大搬家。下面这个结构用分层卡片表示,越靠上越接近外部请求:

controller:接 HTTP 请求,只做参数绑定和状态码
service:业务规则与事务边界
repository:SQL 与数据映射
config:数据源、线程池、安全等装配
DemoApplication:启动入口,放在最外层包

启动类必须放在所有业务类的最外层包,因为默认的组件扫描从这个类所在的包往下找。放到 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 会打一条警告: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 低于 17java -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 启动参数和条件评估报告写进排查手册,比换框架有效。

最后算一笔部署账。单实例启动十秒,滚动发布时新实例要等健康检查通过才接流量,用户感知到的不可用时间取决于实例数和摘流速度,而不是启动时间本身。两台实例轮流发,通常能做到零中断;只有一台时,任何重启都是几十秒的空白。真要在意这个数字,先加实例,再考虑换运行时,顺序别反。

当天能自己验证的练习

  1. 用 java -version 和 mvn -v 分别记录两个 JDK 路径,然后只改当前终端的 JAVA_HOME,确认 java -version 变成 21,再启动 jar。
  2. 把 server.port 改成 8080 启动一次,再用另一个终端占用 8080,重启服务,把「端口被占用」的原文日志抄下来。
  3. 把启动类移到子包 com.example.demo.app,保留控制器原包,访问 /health,确认返回 404 且日志无异常。
  4. 执行 jar tf target/demo-0.0.1.jar,找 BOOT-INF/classes 和 BOOT-INF/lib,理解可执行 jar 的内部布局。
  5. 用 curl -i 请求 /health,把状态行、Content-Type 和响应体三部分分别记下来,确认 JSON 的类型是 application/json。

小结

三句话收束:Spring Boot 的价值是约定和内嵌容器,让部署单元变成一个 jar;启动失败先分清是环境问题还是包结构问题,JDK 版本和组件扫描范围是最常见的两个根因;9.799 秒的启动时间是选型的代价,不是异常。

下一篇讲一个请求进来之后到底经过了哪些环节。这一篇只证明了「服务能起来、接口能返回」,但真实项目里,请求要先过过滤器、再过拦截器、才进控制器,异常还要走统一出口。把这些顺序搞明白,后面加鉴权和日志时才知道该把代码放在哪一层。