Spring Boot 4 模块化:把自动配置拆开之后,你怎么查、怎么改、怎么验证
先把基线钉死,后面所有内容都建立在这几个数字上:截至 2026 年 11 月,Boot 4 的文档主线是 4.1.2,最低 Java 17、最高兼容 Java 27,强制 Spring Framework 7.0.10 及以上,内嵌容器为 Tomcat 11.0.x / Jetty 12.1.x(Servlet 6.1),GraalVM 原生镜像要求 GraalVM 25。
这份基线里没有一条是"装个 starter 就能用"的。它们全部是约束:约束你的 JDK、你的容器版本、你的框架版本。本文讲的就是这些约束怎么落到你的工程里,以及落到哪一步该停。
1. 开工之前:这篇要求你带走四样东西
读完并做完后面的动手任务,你应当能:
- 能说出
spring-boot-autoconfigure被拆成按技术划分的模块之后,依赖树、排查路径、自定义 starter 这三处分别发生了什么变化。 - 会判断一个项目升级 Boot 4 的真实代价落在五个变化项里的哪几项,而不是笼统地说「要升级」。
- 能在自己的工程里跑通一次 AOT Cache 训练,并用
/actuator/startup拿到训练前后的启动耗时对比。 - 会判断什么时候不该用内建 API 版本管理——它解决的是路由,不解决 DTO 并存。
最后一条最容易被跳过。
学这一篇的目的不是记住新特性清单,是学会在升级评审会上说清「这项我们不做,理由是……」。前半句是查文档能得到的,后半句只能靠对代价的判断,而代价判断需要你先看懂下面这套结构。
2. 三层底座:依赖、代码、交付各自的入口
Boot 4 的改动铺在三层底座上,不是三个孤立的新特性。下面这张图是本文的组织结构,也是你读完之后脑子里该留下的形状。
三层的关系一句话能说完:依赖层管什么进来了,代码层管进来之后怎么写,交付层管怎么起得来。
再往下拆没有意义。
真正要知道的是每一层各有一个排查入口,记错了入口就会像下一节的团队一样,卡在读源码上。
3. 导入案例:一次卡在第四小时的升级
2026 年 3 月,一个 14 人团队升级一个跑了四年的订单中台。前置工作做得很齐:JDK 从 21 升到 25,镜像基础层换掉,依赖版本全部对齐到 Boot 4.1。
第一小时编译通过。
第二小时启动失败,报错指向自定义 starter 里的 @AutoConfigureAfter(XxxAutoConfiguration.class),那个类在 Boot 4 里已经搬到别的模块,包名也改了。
第三小时他们去读源码找新位置——这是 Boot 3 时代的肌肉记忆,翻 spring-boot-autoconfigure 的 AutoConfiguration.imports 就知道谁注册了什么。Boot 4 里那个巨型 jar 已经不存在了,翻了四十分钟没找到入口。
第四小时才有人想起来 /actuator/conditions。
请先想一个问题:为什么第三小时的做法在 Boot 3 有效,在 Boot 4 失效?答案不是「文件不存在了」这么表面,而是你的排查手段绑定了一个已经消失的物理结构。
4. 概念拆解:三个词,一张对照表,三个反例
4.1 模块(Module)
Boot 3 里 spring-boot-autoconfigure 是一个装着所有技术自动配置的大 jar,类路径上有什么就装配什么。Boot 4 把它按技术切成 spring-boot-webmvc、spring-boot-tomcat、spring-boot-jackson、spring-boot-data-jpa 这样的独立模块,官方 auto-configuration 附录本身也改成按模块分页列出。
定义一句话:模块是「一组条件类 + 一组配置属性 + 它们共同依赖的技术」的最小打包单位。
反例:很多人以为拆模块意味着「按需加载,用不到的代码不进内存」。不是。模块拆分影响的是类路径扫描范围,不是运行时内存。你的 8 秒启动不会因为升级就变成 3 秒。
4.2 模块化自动配置(Modularized Auto-configuration)
判定逻辑没变,还是 @ConditionalOnClass、@ConditionalOnMissingBean 那套条件注解在起作用。变的是这些条件类住在哪个 jar 里。
反例:以为「拆成模块 = 装配变聪明了,会自动少装一些东西」。不会。条件没命中就跳过,这条规则 Boot 2 就有了。拆模块只是让「用不到的技术」不再被你翻到。
4.3 装配报告(Conditions Report)
/actuator/conditions 输出的是每个自动配置类的匹配结果,分 positive matches、negative matches、unconditional 三类。Boot 3 时代它是个辅助工具,Boot 4 时代它是主入口。
反例:以为它只列「装配成功的」。negative matches 才是排查的主力,你要找的「为什么这个 Bean 没注册」通常在那里,附带一行具体的未命中原因。
| 概念 | Boot 3 里的形态 | Boot 4 里的形态 | 你的动作变化 |
|---|---|---|---|
| 自动配置载体 | 一个巨型 jar | 按技术分的多个模块 | 按模块定位,不再全局搜索 |
| 排查入口 | 读 AutoConfiguration.imports | /actuator/conditions | 先看报告,再读源码 |
| 自定义 starter | 引用 autoconfigure 里的类名 | 类可能已跨模块迁移 | 编译期报错,逐个对齐 |
| 启动优化 | CDS / -XX:ArchiveClassesAtExit | AOT Cache(JEP 483 机制) | 必须解压目录运行 |
| 空安全 | 文档约定 + @Nullable | JSpecify 注解体系 | 按包加 @NullMarked |
5. 动手任务:把装配报告读成结论
这个任务大约二十分钟,一台装了 JDK 25 的机器就够。
第一步,把 Boot 4 的依赖树打出来,确认模块真的进来了。
# 运行结果:能在输出里看到 spring-boot-webmvc、spring-boot-tomcat 等独立 artifact
mvn -q dependency:tree -Dincludes=org.springframework.boot | head -40# 预期输出(节选,版本号以你锁定的 BOM 为准)
[INFO] +- org.springframework.boot:spring-boot-starter-web:jar:4.1.2:compile
[INFO] | +- org.springframework.boot:spring-boot-webmvc:jar:4.1.2:compile
[INFO] | \- org.springframework.boot:spring-boot-tomcat:jar:4.1.2:compile
[INFO] \- org.springframework.boot:spring-boot-starter-actuator:jar:4.1.2:compile如果这里看到的还是 Boot 3 的 spring-boot-autoconfigure,先别往下走。多半是旧 BOM 的依赖管理把它锁在低版本了,这类问题在启动阶段的表现是「新特性一个都没生效,但什么也没报错」。
第二步,开两个端点。
# application.yml
management:
endpoints:
web:
exposure:
include: health,conditions,startup
endpoint:
startup:
enabled: true# 预期输出:一个很大的 JSON,重点看 negativeMatches 里有没有你想要的自动配置
curl -s localhost:8080/actuator/conditions | jq '.contexts[].negativeMatches | keys' | head -20第三步,故意破坏一次,确认你能看懂失败的样子。把 spring-boot-starter-web 换成 spring-boot-starter-webflux,重启,再看 conditions。
# 预期输出:WebMvcAutoConfiguration 从 positiveMatches 移到 negativeMatches
# 原因行类似:@ConditionalOnClass did not find required class 'jakarta.servlet.Servlet'
curl -s localhost:8080/actuator/conditions | jq '.contexts[].negativeMatches'能独立走到这一步,你就有了解读装配问题的基本能力。这一步的意义在于:你验证的不是「端点能不能打开」,而是「失败时报告长什么样」。只见过成功的样子,出问题时等于没学过。
一个可以省半天的小工具
升级时先把 spring-boot-properties-migrator 加进依赖,启动一次。它会把你还留着但已被移除或改名的配置属性直接打在日志里。这个工具的输出比编译错误值钱,因为编译错误你能看见,配置不生效你看不见。
别把 conditions 报告当成永久文档
它是运行时快照,会随 profile、环境变量、@ConditionalOnProperty 变化。排查时用它,别把它截图贴进设计文档。
6. 另外两处会改到你代码的地方
6.1 JSpecify 空安全:从注释走到编译期
Spring Framework 7 全量改用 JSpecify 注解声明可空性。包级 @NullMarked 表示「默认非空」,@Nullable 是 TYPE_USE 注解,写在类型前面而不是方法签名行首——这一点常被写错位置。
// package-info.java:整个包默认非空
@NullMarked
package com.example.order.query;
import org.jspecify.annotations.NullMarked;// 可空返回值写在类型前;配合构建期 NullAway 可以把 NPE 挡在编译阶段
public @Nullable OrderSnapshot findSnapshot(String orderNo) {
return repository.findByOrderNo(orderNo).orElse(null);
}
// 运行时也能判断可空性,适合写通用的校验或序列化组件
Nullness nullness = Nullness.forMethodReturnType(method);
boolean maybeNull = nullness.isNullable(); // 预期:true这里容易卡住的地方是存量代码。给一个写了五年的包加上 @NullMarked,第一天可能冒出几百条告警,其中大部分是框架回调参数。按包灰度推进,新模块强制,老模块只在重构窗口动。
6.2 内建 API 版本管理:省掉自研路由,但不解决 DTO 并存
Framework 7 把版本解析做进了 MVC。开启方式是一行配置,映射用 version 属性。
// Spring Framework 7.0.x:从请求头解析版本
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void configureApiVersioning(ApiVersionConfigurer configurer) {
configurer.useRequestHeader("API-Version"); // 也支持 query / path 段 / media type 参数
}
}// 固定版本与基线版本;"1.2+" 表示 1.2 及其之后所有受支持版本都命中
@RestController
@RequestMapping("/api/orders")
public class OrderController {
@GetMapping(version = "1.1")
public OrderV1 getV11(@RequestParam String orderNo) {
return OrderV1.from(service.find(orderNo));
}
@GetMapping(version = "1.2+")
public OrderV2 getV12(@RequestParam String orderNo) {
return OrderV2.from(service.find(orderNo));
}
}# 不带版本头:预期 400(版本默认必填)
curl -i localhost:8080/api/orders?orderNo=SO202611160001
# 带一个未支持的版本:预期 400,异常是 InvalidApiVersionException
curl -i -H 'API-Version: 9.9' 'localhost:8080/api/orders?orderNo=SO202611160001'要记住两条行为:版本不在受支持集合里抛 InvalidApiVersionException,返回 400;版本高于所有严格匹配、只剩基线匹配时抛 NotAcceptableApiVersionException,也是 400。未标版本的映射虽然「匹配任意版本」,但优先级最低,会被任何带版本的映射盖掉。弃用提示可以通过 StandardApiVersionDeprecationHandler 输出 RFC 9745 的 Deprecation / Sunset 头与 RFC 8594 的 Link 头。
它只解决「请求路由到哪个方法」,不解决「两版 DTO 怎么共存」。 如果你的网关已经按请求头做灰度路由,别在应用层再改写一次版本语义。两处规则打架时,排查成本远高于收益——这是我在第 8 节想让你自己判断的那道题。
7. 交付层:AOT Cache 与分层镜像的可复现实验
AOT Cache 的机制来自 JEP 483,简化后的 -XX:AOTCache / -XX:AOTCacheOutput 命令行开关要到 JDK 25 才齐(JEP 514)。
这两件事经常被合并成一句「JEP 483 的产物,要求 Java 25」。方向没错,界线模糊:机制在 24 就有了,你要用的那套开关在 25。低于 25 只能退回 CDS。
两种方式有个共同的硬约束:jar 必须以解压后的目录形式运行,否则缓存完全不生效,而且日志里没有任何提示。
# Java 25+:解压 -> 训练运行 -> 产出缓存
java -Djarmode=tools -jar my-app.jar extract --destination application
cd application
# -Dspring.context.exit=onRefresh 让容器刷新完就退出,避免跑真实业务
java -XX:AOTCacheOutput=app.aot -Dspring.context.exit=onRefresh -jar my-app.jar
# 之后带上缓存启动(必须仍然在解压目录下)
java -XX:AOTCache=app.aot -jar my-app.jar# 预期输出:JDK 25 会打印缓存加载统计,重点看 classes 与 methods 的加载条数
[0.312s][info][aot] Using AOT cache: app.aot
[0.318s][info][aot] Loaded 21431 classes, 68902 methods from AOT cache
# 训练后 first request 前的启动日志时间戳,才是你应该记录的那个数
[1.204s][info][startup] Started Application in 1.271 seconds注意训练运行的副作用:onRefresh 只保证容器刷新后退出,不保证不建立连接。数据源初始化、Flyway 迁移、静态初始化都可能打到真实中间件。把训练环境指向可丢弃的实例,否则一次训练就是一次误操作。
分层镜像的逻辑更朴素:layers.idx 定义 dependencies、spring-boot-loader、snapshot-dependencies、application 四层,顺序就是 COPY 顺序,越稳定的越靠前。
# 前提:Spring Boot 4.x 可执行 jar + Java 25 基础镜像
FROM eclipse-temurin:25-jre AS builder
WORKDIR /builder
COPY target/my-app.jar app.jar
# 训练失败就让构建失败,别把没有缓存的镜像发上线
RUN java -Djarmode=tools -jar app.jar extract --layers --destination extracted \
&& java -XX:AOTCacheOutput=app.aot -Dspring.context.exit=onRefresh -jar app.jar
FROM eclipse-temurin:25-jre
WORKDIR /application
COPY --from=builder /builder/extracted/dependencies/ ./
COPY --from=builder /builder/extracted/spring-boot-loader/ ./
COPY --from=builder /builder/extracted/snapshot-dependencies/ ./
COPY --from=builder /builder/extracted/application/ ./
ENTRYPOINT ["java","-XX:AOTCache=app.aot","org.springframework.boot.loader.launch.JarLauncher"]缓存有失效条件:应用更新或 JDK 版本变化后必须重新训练。所以训练要固化进 CI 镜像构建,而不是写在容器启动脚本里——后者会把省下的启动时间当场还回去。
至于能快多少,官方不给百分比。它取决于 bean 数量、类加载规模、页缓存命中率。用 /actuator/startup 对比训练前后才有意义。
8. 四个常见误解
很多人以为拆模块之后「用不到的技术」就不会进镜像了。实际上不是,因为它是否进镜像取决于你的 starter 依赖,模块拆分只影响扫描范围与排查路径,因为 jar 依然要跟着 starter 走。
很多人以为 AOT Cache 是个开关,加上就快。实际上它是一个构建产物,因为缓存必须配套同一次构建、同一份解压目录、同一个 JDK 版本,任一变化都会静默失效。
前两条有个共同点:都是把「默认行为」误读成了「新增功能」。
很多人以为 @NullMarked 加得越多越安全。实际上不是,因为存量包一次性加注解会产出几百条告警,真正的问题被淹掉,团队通常在第二周放弃——半途而废比不加更糟,因为没人再信那套注解。
很多人以为内建 API 版本管理能替掉自研方案。实际上它只覆盖路由,因为版本化的本质难点是 DTO 共存与契约演进,那部分它一点没管。
后两条的毛病不一样,是把「工具的边界」误读成了「工具的能力」。识别方法很简单:翻它不管你什么。
9. 迁移练习与思考题
第一题(判断):你们服务有对外 API 三个版本,网关侧已经按 X-Api-Ver 请求头做灰度。现在有人提议应用层也开启内建版本管理,理由「统一管理更清楚」。你会怎么表态?请给出至少一条能被验证的反驳依据。
第二题(动手):把你的服务在解压目录下跑一次 AOT 训练,然后用 /actuator/startup 对比训练前后。如果启动时间只差 200ms,说明什么?请写出你的排查顺序,而不是结论。
第三题(迁移):给一个 2019 年建的包加 @NullMarked 之前,你会先做哪一件事来判断这件事值不值得做?提示:这件事的成本主要不在注解本身。
10. 术语对照:八个词与它们的一句话解释
| 术语 | 英文 | 一句话解释 |
|---|---|---|
| 自动配置模块 | auto-configuration module | 按技术切分的 jar,各自带条件类与配置属性 |
| 装配报告 | conditions report | /actuator/conditions 输出的匹配/未匹配清单 |
| 空安全标记 | @NullMarked | 包级声明「默认非空」,配合 @Nullable 标注例外 |
| 类型使用注解 | TYPE_USE annotation | 可写在类型前的注解,JSpecify 的 @Nullable 属于此类 |
| 基线版本 | baseline version | 1.2+ 形式,表示该版本及其后续受支持版本 |
| AOT 缓存 | AOT cache | 训练运行产出的类加载与链接快照,需解压目录运行 |
| 分层索引 | layers.idx | 定义镜像四层内容与 COPY 顺序的文件 |
| 属性迁移器 | properties migrator | 把已移除/改名的配置属性打在日志里的升级辅助工具 |