SpringBoot 3.x 出来已经有一段时间了我手头维护的项目也从 2.7 陆续升到了 3.5。要说这几年 SpringBoot 新特性最集中、对普通开发者影响最大的一次就是这波从 Spring Framework 6 / Spring Boot 3 开始的技术栈换代。很多人一听“新特性”第一反应是要学一堆新东西也有人直接卡在“版本太高”“javax 变 jakarta”“虚拟线程到底怎么用”这些具体问题上。这篇文章算是我这两年做迁移和落地时的一份复盘把真正影响日常开发、值得优先了解和上手的新特性整理出来重点讲清楚它们解决什么问题、怎么配置、有哪些坑。适合正在做 Spring Boot 版本升级、写自定义 starter、或者准备把虚拟线程和原生镜像用到生产环境的 Java 开发者也适合想系统了解 3.x 变化的朋友。1. 从 2.7 升到 3.x必须先迈过三道坎1.1 javax 到 jakarta一次全局改名运动升级到 Spring Boot 3 后大部分人遇到的第一个报错就是javax.servlet不存在了。这背后是 Java EE 移交到 Eclipse 基金会之后改名为 Jakarta EE命名空间从javax.*变成了jakarta.*。Spring Boot 3 / Spring Framework 6 基于 Jakarta EE 9 规范所以不仅是 Spring 自身所有依赖它编译的第三方库相关的 import 都得跟着变。我在一个老项目里做升级时全局搜javax.servlet发现不仅代码里有web.xml、pom.xml、甚至一些硬编码字符串里都有。最直接的做法是把javax.sql、javax.persistence、javax.validation、javax.jms这些常用包手动替换成对应的jakarta包。提供jakarta.servlet-api、jakarta.validation-api、jakarta.persistence-api这些坐标的都是官方或者 Eclipse 项目替换起来不难。但要特别注意第三方库如果还用旧的javax.坐标编译升级后大概率会在启动时抛NoClassDefFoundError。所以这一步的核心不是改代码而是先把依赖树理清楚看看哪些库还在用旧命名空间。比如老牌的springfoxSwagger 2在 Spring Boot 3 下基本不可用后来我们换成了springdoc-openapi2.x这个问题才彻底解决。MyBatis 也是一样必须用基于 Jakarta 编译的mybatis-spring-boot-starter3.0。我建议不要直接在 IDE 里做暴力全局替换最好先用 Maven 依赖树把所有旧坐标列出来再用 OpenRewrite 或者手动分组替换这样不容易漏改。1.2 Java 17 其实是底线不是门槛Spring Boot 3.x 要求 Java 17Spring Framework 6 也一样。Java 17 是长期支持版本所以官方直接把基线定在了 17。很多团队还在用 Java 8升级的时候光改pom.xml里的版本号远远不够还要把 IDE 编译级别、CI 构建镜像、生产环境的 JRE 都同步升级。实际踩坑中最常见的是老项目里用了一些内部 API比如sun.misc.Unsafe或者某些过期的javac参数在 Java 17 下要么被限制访问要么直接编译报错。还有一些依赖 Jar 虽然是 Java 8 编译的、可以继续用但运行时会因为反射和模块限制产生诡异问题。我在一个项目里遇到过InaccessibleObjectException就是某个库通过反射访问 JDK 内部类被拦截。解决办法是加--add-opens但本质上还是尽快升级到兼容 Java 17 的库版本。如果你打算用虚拟线程那建议直接上 JDK 21。因为虚拟线程在 JDK 21 才算正式稳定Spring Boot 3.2 对虚拟线程的支持也是围绕 JDK 21 做的。现在大多数公司从 Java 8 升到 21 也不是不行只要第三方库兼容这一步反而能省掉以后二次升级的麻烦。1.3 版本太高先分清框架版本和生态兼容版本很多人一看到“SpringBoot 新特性”就担心版本太高等问题。实际上 Spring Boot 3.5 这个阶段的稳定度和当年 2.7 是一样的问题往往出在第三方生态上而不是框架本身。判断成败的关键只有一条你的依赖库是否已经基于 Jakarta 编译是否与 Spring Framework 6 的运行模型兼容。在升级时我把 Spring Boot 的版本和几个关键词对照了一下方便团队一起评估Spring Boot 版本Java 要求核心变化2.7Java 8过渡版本开始支持新自动配置 imports 文件3.0Java 17要求 Jakarta EE 9自动配置彻底移除 spring.factories3.2Java 17 推荐 21正式支持虚拟线程引入 RestClient3.4Java 17支持结构化日志、CDS、Docker Compose 增强3.5Java 17基于 Spring Framework 6.2调度任务等虚拟线程体验更完善如果你用 Spring Cloud还要同步关注 Spring Cloud 的 release train 和 Spring Boot 版本对应关系不能自己乱配。依赖下载慢的话用阿里云 Maven 镜像加速也很常见配置好之后整个构建体验会顺畅很多。判断“这个第三方库能不能上 Boot 3”去它的官网或者 GitHub 看是否发布过 jakarta 版本就行没必要抱着旧版本死守。2. 虚拟线程使用实录spring.threads.virtual.enabled 到底开了什么2.1 为什么大家都在推虚拟线程传统的 Java 并发模型里一个请求通常占一个平台线程而平台线程的栈空间默认 1MB 左右线程一多内存和上下文切换开销就很大。Tomcat 默认线程池也就 200 个一旦接口内部阻塞在数据库查询、Redis 调用或者远程 RPC 上吞吐量就卡死了。这是我们做服务压测时最常见的问题线程没少开但都阻塞着等下游返回。虚拟线程的思路是完全不同的。它由 JVM 调度不再绑定内核线程阻塞时会自动让出载体线程去跑其他任务所以可以创建几十万甚至百万个虚拟线程非常适合 IO 密集型的业务。打个比方传统线程就像每个包间固定配一个大厨顾客多了只能排队虚拟线程是流水线厨房客人等菜的时候大厨已经在炒别的菜了整体效率完全不一样。但这里要提醒一句虚拟线程并不适合 CPU 密集型任务。如果接口内部做大量加解密、复杂计算虚拟线程反而可能因为调度开销略微变慢。判断你的业务适不适合用虚拟线程就看链路里是不是大量时间花在等待外部资源上。2.2 在 Spring Boot 里启用虚拟线程的三种方式Spring Boot 3.2 开始最简单的启用方式就是一行配置spring: threads: virtual: enabled: true这个配置打开后Spring 托管的TaskExecutor、TaskScheduler会优先使用虚拟线程同时在很多场景下 Servlet 容器处理请求的线程也会走虚拟线程。我的经验是如果你只有一个普通 Web 服务先把它打开跑一轮压测看看效果大多数 IO 型接口都能直接受益。如果你想更精细地控制某个执行器不全局开启可以自己定义一个执行器 Bean。JDK 21 提供了现成的工厂方法Bean public AsyncTaskExecutor customVirtualExecutor() { return new TaskExecutorAdapter(Executors.newVirtualThreadPerTaskExecutor()); }然后在使用Async时指定执行器名称Async(customVirtualExecutor) public void doSomething() { // 异步业务逻辑 }这种方式非常灵活尤其适合那些只想把部分并发任务放到虚拟线程上的场景也正好是newVirtualThreadPerTaskExecutor这个写法最常见的落地场景。如果公司里有多套服务我建议先用全局配置观察收益再逐步对特定线程池做精细化调整。2.3 用上虚拟线程后最容易翻车的几件事虚拟线程不是银弹我实际跑下来遇到过几个比较明显的坑。第一个坑是synchronized与固定载体线程的冲突。虚拟线程在某些情况下会被 “pin” 到载体线程比如进入synchronized块时可能无法释放载体线程去执行其他虚拟线程这正是官方还在优化的方向。所以在新代码里能不用synchronized就尽量用ReentrantLock或LockSupport。第二个坑是ThreadLocal。虚拟线程便宜到能创建海量实例如果你在每个虚拟线程里放一个大的 ThreadLocal 对象内存会被瞬间放大。像HikariCP连接池、某些框架的上下文传递都用到了 ThreadLocal开启虚拟线程后要特别关注内存变化必要时只在特定入口传递必要数据不要全局塞对象。第三个坑是连接池和外部资源。虚拟线程只解决了“线程等待”的问题并没有让数据库连接、Redis 连接变多。当请求并发飙升时瓶颈会迅速转移到这些真实稀缺资源上。我有一次压测发现接口 CPU 占用率不高但数据库连接池被占满了大量请求还是超时。后来把连接池调大并优化了慢 SQL吞吐才真正提上去。这里整理了一张线程模型对比表方便直观理解维度平台线程虚拟线程内存开销1MB 级栈空间轻量可达百万级调度方式内核/操作系统JVM 调度适用场景通用IO 密集型高并发上下文切换开销较大非常低限制池大小有限避免 synchronized、ThreadLocal压测效果也说一下。我们有个内部服务接口里有一个耗时 200ms 的慢 SQLTomcat 默认 200 线程时800 QPS 就开始出现大量超时开了虚拟线程之后只要数据库连接池扛得住QPS 能到 2500 左右。但另一个接口内部做大量 RSA 加解密虚拟线程下性能提升有限甚至还略有下降。所以先评估你的业务是 IO 密集还是计算密集再决定要不要上。3. GraalVM 原生镜像与 AOT启动速度的另一条路3.1 Spring Boot 3 的 AOT 处理到底做了什么云原生和 Serverless 场景下启动速度很关键。传统 JVM 应用启动往往需要好几秒内存占用动辄几百 MB而 GraalVM 原生镜像可以把应用编译成机器码启动时间压到几十毫秒内存也能大幅下降。Spring Boot 3 为此引入了 AOTAhead-Of-Time处理机制。它不再完全依赖运行时扫描反射和配置而是在构建阶段就把 Spring 的 Bean 定义、自动配置、条件判断、反射信息等静态化处理生成 GraalVM 需要的reflect-config.json、resource-config.json等提示文件。这样最终生成的原生可执行文件不需要 JVM 启动时再做大量类加载和反射分析启动自然快。这也是 Spring Boot 新特性里比较偏底层的一项如果你负责运维或搭建基础架构非常值得跟进。如果你只写业务代码可能感知不强但部署体验会明显变化。3.2 本地编译一把梭配置原生镜像的核心环节想跑通原生镜像需要先准备好环境。我用的是 GraalVM JDK 21安装后通过gu install native-image安装native-image组件。然后在pom.xml里加上 GraalVM 官方提供的构建插件plugin groupIdorg.graalvm.buildtools/groupId artifactIdnative-maven-plugin/artifactId version0.10.4/version extensionstrue/extensions /plugin执行构建命令mvn -Pnative native:compile构建完成后会在target/目录下生成一个原生可执行文件直接运行就行。需要注意构建过程比普通打包慢很多也比较吃内存。我们 CI 机器 8GB 内存时偶尔会 OOM后来换到 16GB 才稳定。如果你只在本地试记得预留资源别在开着一堆 IDE 的情况下构建。3.3 原生镜像下哪些老套路会失效原生镜像最大的门槛在于它默认不支持运行时的动态特性比如反射、动态代理、JNI、资源扫描。Spring Boot 3 自己已经为常用框架和自动配置做了大量适配但你自己业务代码里的反射操作还是得手动声明。处理方式是两类一是用注解RegisterReflectionForBinding把你的 DTO、实体类注册进去二是实现RuntimeHintsRegistrar在构建期注册反射、资源、代理、序列化等各类 Hint。我把常见的几种动态场景和对应处理方式整理成了表动态特性原生镜像处理方式反射RegisterReflectionForBinding或 RuntimeHintsRegistrar资源文件构建期注册 resource hintJava 序列化/JSON 序列化注册反射信息与序列化配置动态代理注册代理 HintJNI尽量改为纯 Java 实现还要特别提醒CGLIB 在 GraalVM 原生镜像下支持有限所以如果类结构太依赖动态代理做原生编译时会比较痛苦。这也是为什么 Spring Boot 团队会在 AOT 阶段尽量把代理调用转换成静态调用但业务代码还是要尽量设计得“显式”一些。3.4 不想折腾原生镜像CDS 可以试试如果觉得 GraalVM 门槛太高只想降低一点启动时间Spring Boot 3.4 开始支持 JVM 模式下的 CDSClass Data Sharing自动配置。CDS 的思路是让多个 JVM 进程共享类元数据启动时省去重复加载类的时间一般能带来 10% 到 20% 的启动加速。在application.yml里开启spring: cds: enabled: true第一次启动时应用会生成 CDS 存档之后启动复用。要注意类路径变化后需要重新生成存档。这种方式保留原有的 JVM 运行模型没有原生镜像那么多动态限制非常适合现阶段不想迁移到 GraalVM 的团队。4. 自动装配与默认 CGLIB 代理自定义组件的适应指南4.1 自动装配原理拆解从 spring.factories 到 AutoConfiguration.imports自动装配是 Spring Boot 的灵魂。很多人面试时背“自动装配原理”说来说去就是SpringBootApplication里的EnableAutoConfiguration以及AutoConfigurationImportSelector会读取配置文件里的自动配置类。但在 Spring Boot 3 里这个“配置文件”本身发生了变化。Spring Boot 2.7 之前自动配置类声明在META-INF/spring.factories中从 2.7 开始引入了新的META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件到 3.0 就彻底移除了spring.factories里的自动配置加载机制。所以你如果维护过老的自定义 starter升级到 Boot 3 后第一件事就是看自动配置类有没有被加载。新的 imports 文件很简单每行一个自动配置类的全限定名com.example.starter.autoconfigure.ExampleAutoConfiguration自动配置类用AutoConfiguration标注内部再用ConditionalOnClass、ConditionalOnMissingBean、ConditionalOnProperty这些条件注解控制生效范围。排查 Bean 为什么没生效时主要看启动时打印的自动配置报告Positive matches里是生效的自动配置Negative matches里是没生效的原因。我在自己写的 starter 里还养成了用AutoConfiguration(before ...)或after ...显式声明顺序的习惯避免多个 starter 之间装配顺序不一致导致莫名其妙的 Bean 冲突。4.2 为什么 Spring Boot 3 默认使用 CGLIB 代理Spring AOP 有两种代理方式JDK 动态代理和 CGLIB 代理。JDK 代理要求目标类必须有接口CGLIB 通过继承目标类生成子类来代理不需要接口。以前 Spring Boot 2 的逻辑是有接口就优先走 JDK 代理没有接口才走 CGLIB。Spring Boot 3 开始默认已经是强制 CGLIB也就是spring.aop.proxy-target-classtrue。为什么这么改一个核心原因是Configuration类里的Bean方法需要保证单例语义这依赖 CGLIB 对Bean方法的拦截。统一的 CGLIB 方案还能减少接口混用带来的各种坑让代理行为更可预测。代价也很明确final类、final方法不能被 CGLIB 代理。如果你在业务服务上写了final切面注入会直接失效报错还很让人困惑。我自己的习惯是在 Boot 3 项目里干脆不写final类作为 Spring Bean所有需要做事务、缓存、权限控制的类都保持非final。如果你确实需要 JDK 动态代理可以配置spring.aop.proxy-target-classfalse但在 Spring Boot 3 里很多内部组件仍会强制使用 CGLIB所以不如从一开始就按 CGLIB 的方式设计代码。4.3 自定义 starter 需要注意的兼容性问题自定义 starter 是很多中大型团队逃不掉的工作。升级到 Spring Boot 3 之后有几个兼容点需要注意。首先是自动配置声明位置必须从spring.factories移到AutoConfiguration.imports。其次是依赖坐标凡是javax.*的接口全部换成jakarta.*如果有对 Servlet 容器做自定义也要同步用新 API。还有一个很容易踩的坑自动配置类所在包不要和业务代码的ComponentScan扫描范围重合不然自动配置的ConditionalOnMissingBean会失效。写自动配置类的时候我建议配合spring-boot-test-autoconfigure写专门的自动化测试验证不同条件组合下 Bean 是否按预期装配。这个习惯帮我在升级时提前发现了很多问题而不是等到应用启动到一半才报错。5. 开发体验层面的新东西RestClient、结构化日志与更多5.1 RestClient 让同步 HTTP 调用舒服多了以前写同步 HTTP 调用老牌选手是RestTemplate功能强大但 API 设计比较陈旧链式调用不够直观。后来WebClient出来了API 设计现代化可它本质是非阻塞的强行同步使用又不太顺手。Spring Framework 6.1 和 Spring Boot 3.2 带来了RestClient填补了“现代化 API 同步调用”这个缺口。一段简单的用法是这样的RestClient client RestClient.builder() .baseUrl(https://api.example.com) .defaultHeader(Authorization, Bearer token) .build(); ResponseEntityProduct response client.get() .uri(/products/{id}, 42) .retrieve() .toEntity(Product.class);API 风格和WebClient很像但返回值是同步的学习成本很低。以前经常有人问我“multipart 文件怎么用 RestTemplate 传”现在用 RestClient 也支持MultipartBodyBuilder写起来比 RestTemplate 干净很多。如果你是新项目同步调用我建议直接上 RestClient。老项目里RestTemplate还能继续用不用着急迁移。三个客户端的差别可以从这个表里快速了解客户端风格同步/异步推荐场景RestTemplate老式模板同步老项目维护WebClient响应式流式异步非阻塞高并发、事件驱动RestClient现代化链式同步新项目同步调用5.2 结构化日志与可观测性Spring Boot 3.4 开始支持结构化日志简单说就是把传统文本日志转成 JSON 格式方便日志采集系统直接解析字段比如 traceId、spanId、level 等。配置起来非常轻量logging: structured: format: console: ecs其中ecs是 Elastic Common Schemalogstash是老牌的 Logstash 格式gelf也可以选。生产环境配上这个之后排查问题时在日志平台按 traceId 过滤就行不用再用正则去文本里捞。我自己的做法是只在生产环境的 profile 下开启 JSON 结构化日志本地开发还是用普通格式因为控制台看 JSON 实在太费眼。配合 Micrometer Tracing 和 OpenTelemetry链路信息会自动写到日志里前后端排查链路会方便很多。5.3 Docker Compose、CDS 与优雅停机部署环节的细节优化Spring Boot 3.1 开始对 Docker Compose 提供了一等公民支持3.4 又做了增强。开发时你可以在docker-compose.yml里定义 MySQL、Redis 等服务Spring Boot 启动时会自动读取容器信息把数据源配置指过去。这个功能对本地开发特别友好不用人为维护一套复杂的连接配置。优雅停机则是生产发布必备的。以前应用被 kill 时正在处理的请求会突然中断用户端直接看到连接重置。配置两个属性就能改善server: shutdown: graceful spring: lifecycle: timeout-per-shutdown-phase: 30s这样停机时 Spring 会先停止接收新请求再等待已有请求处理完最多等 30 秒。在线发布时用户体感会好很多。另外要注意Spring Boot 3 把一些配置前缀做了整理比如静态资源相关配置从spring.resources.*移动到了spring.web.resources.*。这个在升级老项目时很容易忽略导致静态资源 404。5.4 新 banner 与在线生成器看起来不起眼的小事Spring Boot 3 换过默认 banner 的字体3.2 又更新过一次。新版默认 banner 明显比 2.x 时代更简洁风格也更现代。很多在线的 ASCII banner 生成器已经适配了 Spring Boot 3 的新字体。如果你想定制自己的 banner把生成的文本放到classpath:banner.txt就行。这个功能对生产没有任何影响但团队内部分享、启动截图时还挺有意思。我见过有团队把项目名和吉祥物做成 banner每次启动都很有仪式感。在线生成器几分钟就能搞定完全不用手写 ASCII 艺术。6. 常见问题排查升级与集成时的高频报错速查6.1 升级步骤别直接改版本号就完事很多人在 pom 里把 Spring Boot 版本从 2.7 改成 3.0以为万事大吉结果启动就崩溃。我的建议是不要直接改版本先按这个顺序走一遍把 IDE 和构建环境的 JDK 升到 17 或 21进入 Spring Boot 3 的基线要求。全局搜索代码中的javax.*区分“必须替换的框架 API”和“字符串常量”分批替换。更新第三方依赖到支持 Jakarta 的版本这一步最花时间但值得提前列清单。启动应用用--debug或logging.level.org.springframework.boot.autoconfigureDEBUG看自动配置报告确认关键 Bean 是否装配。跑全量测试重点看 JSON 序列化、反射、文件上传、定时任务这些容易受版本影响的模块。依赖下载如果特别慢可以把 Maven 中央仓库换成阿里云镜像构建体验会好很多。IDE 里运行服务时直接在 Run Configuration 的 Program arguments 里写--server.port8081就能覆盖端口Spring Boot 3.x 依然适用。6.2 高频报错与解决方案速查表实践过程中下面这些报错出现频率最高我整理成了一张表方便大家快速定位报错或现象可能原因解决方案NoClassDefFoundError: javax.servlet.*第三方库还是旧命名空间升级到 jakarta 兼容版本Failed to load AutoConfiguration.imports自定义 starter 还在用 spring.factories新建 AutoConfiguration.imports 文件Parameter 0 of method ... required a single bean自动配置条件不满足看 Positive/Negative matches 排查条件NoClassDefFoundError: jakarta.xml.bind.*缺少 JAXB 实现加入jakarta.xml.bind-api及实现CGLIB 无法代理 final 类/方法类或方法被 final 修饰去掉 final或改接口配合 JDK 代理HikariPool ... Connection is not available数据库连接池耗尽优化慢 SQL、排查连接泄漏Unsupported class file major versionJDK 版本过低编译、运行都确保 JDK 17前两个问题在自定义 starter 中尤其常见第三个则提醒我们尽量用自动配置报告去判断条件是否满足而不是瞎猜。6.3 各中间件集成的兼容性清单结合大家经常搜的一些场景我整理了中间件集成时的兼容性检查点整合 Flink老版本 Flink 对 Spring Boot 3 支持不好建议用 Flink 1.20 以上版本。实在要用旧版可以把 Flink client 放到独立模块通过 REST API 配合避免NoClassDefFoundError污染主服务类加载。集成金仓 V8旧版 JDBC 驱动可能不兼容新 HikariCP 的自动检测逻辑优先换新驱动再检查 JPA 或 MyBatis 的方言配置。整合 ActiveMQ把javax.jms相关的依赖全部换成jakarta.jms同时用 Spring Boot 3 对应的 starter不要混搭。MyBatis用mybatis-spring-boot-starter3.0老版本 2.x starter 在 Boot 3 下会自动装配失败。多数据源场景建议自定义SqlSessionFactory来避免自动配置互相干扰。HanLP 分词这类纯算法库一般不受 Servlet/JPA 影响主要检查它的底层依赖是否与 JDK 17/21 兼容。若依框架这种 Spring Boot 脚手架项目升级时要连带看它的自动配置和权限模块是否基于 Jakarta 重编译跑通后再引入 TDengine、MySQL 等多数据源方案。6.4 我的实际体会从我这边十几个服务的升级结果来看Spring Boot 3.x 并不是一次伤筋动骨的重写更像是一次技术栈换底。最耗时的是第三方依赖适配而不是 Spring 本身。虚拟线程对 IO 型服务的效果最直接配置简单收益明显原生镜像是好东西但构建复杂度和维护成本不适合所有团队CDS 可以作为过渡方案CGLIB 带来的影响比想象中小只要不随便写 final 类就没有太大感觉。如果你现在还在 2.7 徘徊我的建议是尽早把升级排进迭代越晚第三方生态适配的压力越大。升级时养成看自动配置报告和依赖树的习惯比对着报错盲目改代码高效得多。Spring Boot 3.x 的新特性本质上都在围绕两个方向走把云原生部署做到位把高并发场景下的开发者体验做到位。理解了这条主线其他细节都只是时间问题。
SpringBoot 3.x 出来已经有一段时间了我手头维护的项目也从 2.7 陆续升到了 3.5。要说这几年 SpringBoot 新特性最集中、对普通开发者影响最大的一次就是这波从 Spring Framework 6 / Spring Boot 3 开始的技术栈换代。很多人一听“新特性”第一反应是要学一堆新东西也有人直接卡在“版本太高”“javax 变 jakarta”“虚拟线程到底怎么用”这些具体问题上。这篇文章算是我这两年做迁移和落地时的一份复盘把真正影响日常开发、值得优先了解和上手的新特性整理出来重点讲清楚它们解决什么问题、怎么配置、有哪些坑。适合正在做 Spring Boot 版本升级、写自定义 starter、或者准备把虚拟线程和原生镜像用到生产环境的 Java 开发者也适合想系统了解 3.x 变化的朋友。1. 从 2.7 升到 3.x必须先迈过三道坎1.1 javax 到 jakarta一次全局改名运动升级到 Spring Boot 3 后大部分人遇到的第一个报错就是javax.servlet不存在了。这背后是 Java EE 移交到 Eclipse 基金会之后改名为 Jakarta EE命名空间从javax.*变成了jakarta.*。Spring Boot 3 / Spring Framework 6 基于 Jakarta EE 9 规范所以不仅是 Spring 自身所有依赖它编译的第三方库相关的 import 都得跟着变。我在一个老项目里做升级时全局搜javax.servlet发现不仅代码里有web.xml、pom.xml、甚至一些硬编码字符串里都有。最直接的做法是把javax.sql、javax.persistence、javax.validation、javax.jms这些常用包手动替换成对应的jakarta包。提供jakarta.servlet-api、jakarta.validation-api、jakarta.persistence-api这些坐标的都是官方或者 Eclipse 项目替换起来不难。但要特别注意第三方库如果还用旧的javax.坐标编译升级后大概率会在启动时抛NoClassDefFoundError。所以这一步的核心不是改代码而是先把依赖树理清楚看看哪些库还在用旧命名空间。比如老牌的springfoxSwagger 2在 Spring Boot 3 下基本不可用后来我们换成了springdoc-openapi2.x这个问题才彻底解决。MyBatis 也是一样必须用基于 Jakarta 编译的mybatis-spring-boot-starter3.0。我建议不要直接在 IDE 里做暴力全局替换最好先用 Maven 依赖树把所有旧坐标列出来再用 OpenRewrite 或者手动分组替换这样不容易漏改。1.2 Java 17 其实是底线不是门槛Spring Boot 3.x 要求 Java 17Spring Framework 6 也一样。Java 17 是长期支持版本所以官方直接把基线定在了 17。很多团队还在用 Java 8升级的时候光改pom.xml里的版本号远远不够还要把 IDE 编译级别、CI 构建镜像、生产环境的 JRE 都同步升级。实际踩坑中最常见的是老项目里用了一些内部 API比如sun.misc.Unsafe或者某些过期的javac参数在 Java 17 下要么被限制访问要么直接编译报错。还有一些依赖 Jar 虽然是 Java 8 编译的、可以继续用但运行时会因为反射和模块限制产生诡异问题。我在一个项目里遇到过InaccessibleObjectException就是某个库通过反射访问 JDK 内部类被拦截。解决办法是加--add-opens但本质上还是尽快升级到兼容 Java 17 的库版本。如果你打算用虚拟线程那建议直接上 JDK 21。因为虚拟线程在 JDK 21 才算正式稳定Spring Boot 3.2 对虚拟线程的支持也是围绕 JDK 21 做的。现在大多数公司从 Java 8 升到 21 也不是不行只要第三方库兼容这一步反而能省掉以后二次升级的麻烦。1.3 版本太高先分清框架版本和生态兼容版本很多人一看到“SpringBoot 新特性”就担心版本太高等问题。实际上 Spring Boot 3.5 这个阶段的稳定度和当年 2.7 是一样的问题往往出在第三方生态上而不是框架本身。判断成败的关键只有一条你的依赖库是否已经基于 Jakarta 编译是否与 Spring Framework 6 的运行模型兼容。在升级时我把 Spring Boot 的版本和几个关键词对照了一下方便团队一起评估Spring Boot 版本Java 要求核心变化2.7Java 8过渡版本开始支持新自动配置 imports 文件3.0Java 17要求 Jakarta EE 9自动配置彻底移除 spring.factories3.2Java 17 推荐 21正式支持虚拟线程引入 RestClient3.4Java 17支持结构化日志、CDS、Docker Compose 增强3.5Java 17基于 Spring Framework 6.2调度任务等虚拟线程体验更完善如果你用 Spring Cloud还要同步关注 Spring Cloud 的 release train 和 Spring Boot 版本对应关系不能自己乱配。依赖下载慢的话用阿里云 Maven 镜像加速也很常见配置好之后整个构建体验会顺畅很多。判断“这个第三方库能不能上 Boot 3”去它的官网或者 GitHub 看是否发布过 jakarta 版本就行没必要抱着旧版本死守。2. 虚拟线程使用实录spring.threads.virtual.enabled 到底开了什么2.1 为什么大家都在推虚拟线程传统的 Java 并发模型里一个请求通常占一个平台线程而平台线程的栈空间默认 1MB 左右线程一多内存和上下文切换开销就很大。Tomcat 默认线程池也就 200 个一旦接口内部阻塞在数据库查询、Redis 调用或者远程 RPC 上吞吐量就卡死了。这是我们做服务压测时最常见的问题线程没少开但都阻塞着等下游返回。虚拟线程的思路是完全不同的。它由 JVM 调度不再绑定内核线程阻塞时会自动让出载体线程去跑其他任务所以可以创建几十万甚至百万个虚拟线程非常适合 IO 密集型的业务。打个比方传统线程就像每个包间固定配一个大厨顾客多了只能排队虚拟线程是流水线厨房客人等菜的时候大厨已经在炒别的菜了整体效率完全不一样。但这里要提醒一句虚拟线程并不适合 CPU 密集型任务。如果接口内部做大量加解密、复杂计算虚拟线程反而可能因为调度开销略微变慢。判断你的业务适不适合用虚拟线程就看链路里是不是大量时间花在等待外部资源上。2.2 在 Spring Boot 里启用虚拟线程的三种方式Spring Boot 3.2 开始最简单的启用方式就是一行配置spring: threads: virtual: enabled: true这个配置打开后Spring 托管的TaskExecutor、TaskScheduler会优先使用虚拟线程同时在很多场景下 Servlet 容器处理请求的线程也会走虚拟线程。我的经验是如果你只有一个普通 Web 服务先把它打开跑一轮压测看看效果大多数 IO 型接口都能直接受益。如果你想更精细地控制某个执行器不全局开启可以自己定义一个执行器 Bean。JDK 21 提供了现成的工厂方法Bean public AsyncTaskExecutor customVirtualExecutor() { return new TaskExecutorAdapter(Executors.newVirtualThreadPerTaskExecutor()); }然后在使用Async时指定执行器名称Async(customVirtualExecutor) public void doSomething() { // 异步业务逻辑 }这种方式非常灵活尤其适合那些只想把部分并发任务放到虚拟线程上的场景也正好是newVirtualThreadPerTaskExecutor这个写法最常见的落地场景。如果公司里有多套服务我建议先用全局配置观察收益再逐步对特定线程池做精细化调整。2.3 用上虚拟线程后最容易翻车的几件事虚拟线程不是银弹我实际跑下来遇到过几个比较明显的坑。第一个坑是synchronized与固定载体线程的冲突。虚拟线程在某些情况下会被 “pin” 到载体线程比如进入synchronized块时可能无法释放载体线程去执行其他虚拟线程这正是官方还在优化的方向。所以在新代码里能不用synchronized就尽量用ReentrantLock或LockSupport。第二个坑是ThreadLocal。虚拟线程便宜到能创建海量实例如果你在每个虚拟线程里放一个大的 ThreadLocal 对象内存会被瞬间放大。像HikariCP连接池、某些框架的上下文传递都用到了 ThreadLocal开启虚拟线程后要特别关注内存变化必要时只在特定入口传递必要数据不要全局塞对象。第三个坑是连接池和外部资源。虚拟线程只解决了“线程等待”的问题并没有让数据库连接、Redis 连接变多。当请求并发飙升时瓶颈会迅速转移到这些真实稀缺资源上。我有一次压测发现接口 CPU 占用率不高但数据库连接池被占满了大量请求还是超时。后来把连接池调大并优化了慢 SQL吞吐才真正提上去。这里整理了一张线程模型对比表方便直观理解维度平台线程虚拟线程内存开销1MB 级栈空间轻量可达百万级调度方式内核/操作系统JVM 调度适用场景通用IO 密集型高并发上下文切换开销较大非常低限制池大小有限避免 synchronized、ThreadLocal压测效果也说一下。我们有个内部服务接口里有一个耗时 200ms 的慢 SQLTomcat 默认 200 线程时800 QPS 就开始出现大量超时开了虚拟线程之后只要数据库连接池扛得住QPS 能到 2500 左右。但另一个接口内部做大量 RSA 加解密虚拟线程下性能提升有限甚至还略有下降。所以先评估你的业务是 IO 密集还是计算密集再决定要不要上。3. GraalVM 原生镜像与 AOT启动速度的另一条路3.1 Spring Boot 3 的 AOT 处理到底做了什么云原生和 Serverless 场景下启动速度很关键。传统 JVM 应用启动往往需要好几秒内存占用动辄几百 MB而 GraalVM 原生镜像可以把应用编译成机器码启动时间压到几十毫秒内存也能大幅下降。Spring Boot 3 为此引入了 AOTAhead-Of-Time处理机制。它不再完全依赖运行时扫描反射和配置而是在构建阶段就把 Spring 的 Bean 定义、自动配置、条件判断、反射信息等静态化处理生成 GraalVM 需要的reflect-config.json、resource-config.json等提示文件。这样最终生成的原生可执行文件不需要 JVM 启动时再做大量类加载和反射分析启动自然快。这也是 Spring Boot 新特性里比较偏底层的一项如果你负责运维或搭建基础架构非常值得跟进。如果你只写业务代码可能感知不强但部署体验会明显变化。3.2 本地编译一把梭配置原生镜像的核心环节想跑通原生镜像需要先准备好环境。我用的是 GraalVM JDK 21安装后通过gu install native-image安装native-image组件。然后在pom.xml里加上 GraalVM 官方提供的构建插件plugin groupIdorg.graalvm.buildtools/groupId artifactIdnative-maven-plugin/artifactId version0.10.4/version extensionstrue/extensions /plugin执行构建命令mvn -Pnative native:compile构建完成后会在target/目录下生成一个原生可执行文件直接运行就行。需要注意构建过程比普通打包慢很多也比较吃内存。我们 CI 机器 8GB 内存时偶尔会 OOM后来换到 16GB 才稳定。如果你只在本地试记得预留资源别在开着一堆 IDE 的情况下构建。3.3 原生镜像下哪些老套路会失效原生镜像最大的门槛在于它默认不支持运行时的动态特性比如反射、动态代理、JNI、资源扫描。Spring Boot 3 自己已经为常用框架和自动配置做了大量适配但你自己业务代码里的反射操作还是得手动声明。处理方式是两类一是用注解RegisterReflectionForBinding把你的 DTO、实体类注册进去二是实现RuntimeHintsRegistrar在构建期注册反射、资源、代理、序列化等各类 Hint。我把常见的几种动态场景和对应处理方式整理成了表动态特性原生镜像处理方式反射RegisterReflectionForBinding或 RuntimeHintsRegistrar资源文件构建期注册 resource hintJava 序列化/JSON 序列化注册反射信息与序列化配置动态代理注册代理 HintJNI尽量改为纯 Java 实现还要特别提醒CGLIB 在 GraalVM 原生镜像下支持有限所以如果类结构太依赖动态代理做原生编译时会比较痛苦。这也是为什么 Spring Boot 团队会在 AOT 阶段尽量把代理调用转换成静态调用但业务代码还是要尽量设计得“显式”一些。3.4 不想折腾原生镜像CDS 可以试试如果觉得 GraalVM 门槛太高只想降低一点启动时间Spring Boot 3.4 开始支持 JVM 模式下的 CDSClass Data Sharing自动配置。CDS 的思路是让多个 JVM 进程共享类元数据启动时省去重复加载类的时间一般能带来 10% 到 20% 的启动加速。在application.yml里开启spring: cds: enabled: true第一次启动时应用会生成 CDS 存档之后启动复用。要注意类路径变化后需要重新生成存档。这种方式保留原有的 JVM 运行模型没有原生镜像那么多动态限制非常适合现阶段不想迁移到 GraalVM 的团队。4. 自动装配与默认 CGLIB 代理自定义组件的适应指南4.1 自动装配原理拆解从 spring.factories 到 AutoConfiguration.imports自动装配是 Spring Boot 的灵魂。很多人面试时背“自动装配原理”说来说去就是SpringBootApplication里的EnableAutoConfiguration以及AutoConfigurationImportSelector会读取配置文件里的自动配置类。但在 Spring Boot 3 里这个“配置文件”本身发生了变化。Spring Boot 2.7 之前自动配置类声明在META-INF/spring.factories中从 2.7 开始引入了新的META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件到 3.0 就彻底移除了spring.factories里的自动配置加载机制。所以你如果维护过老的自定义 starter升级到 Boot 3 后第一件事就是看自动配置类有没有被加载。新的 imports 文件很简单每行一个自动配置类的全限定名com.example.starter.autoconfigure.ExampleAutoConfiguration自动配置类用AutoConfiguration标注内部再用ConditionalOnClass、ConditionalOnMissingBean、ConditionalOnProperty这些条件注解控制生效范围。排查 Bean 为什么没生效时主要看启动时打印的自动配置报告Positive matches里是生效的自动配置Negative matches里是没生效的原因。我在自己写的 starter 里还养成了用AutoConfiguration(before ...)或after ...显式声明顺序的习惯避免多个 starter 之间装配顺序不一致导致莫名其妙的 Bean 冲突。4.2 为什么 Spring Boot 3 默认使用 CGLIB 代理Spring AOP 有两种代理方式JDK 动态代理和 CGLIB 代理。JDK 代理要求目标类必须有接口CGLIB 通过继承目标类生成子类来代理不需要接口。以前 Spring Boot 2 的逻辑是有接口就优先走 JDK 代理没有接口才走 CGLIB。Spring Boot 3 开始默认已经是强制 CGLIB也就是spring.aop.proxy-target-classtrue。为什么这么改一个核心原因是Configuration类里的Bean方法需要保证单例语义这依赖 CGLIB 对Bean方法的拦截。统一的 CGLIB 方案还能减少接口混用带来的各种坑让代理行为更可预测。代价也很明确final类、final方法不能被 CGLIB 代理。如果你在业务服务上写了final切面注入会直接失效报错还很让人困惑。我自己的习惯是在 Boot 3 项目里干脆不写final类作为 Spring Bean所有需要做事务、缓存、权限控制的类都保持非final。如果你确实需要 JDK 动态代理可以配置spring.aop.proxy-target-classfalse但在 Spring Boot 3 里很多内部组件仍会强制使用 CGLIB所以不如从一开始就按 CGLIB 的方式设计代码。4.3 自定义 starter 需要注意的兼容性问题自定义 starter 是很多中大型团队逃不掉的工作。升级到 Spring Boot 3 之后有几个兼容点需要注意。首先是自动配置声明位置必须从spring.factories移到AutoConfiguration.imports。其次是依赖坐标凡是javax.*的接口全部换成jakarta.*如果有对 Servlet 容器做自定义也要同步用新 API。还有一个很容易踩的坑自动配置类所在包不要和业务代码的ComponentScan扫描范围重合不然自动配置的ConditionalOnMissingBean会失效。写自动配置类的时候我建议配合spring-boot-test-autoconfigure写专门的自动化测试验证不同条件组合下 Bean 是否按预期装配。这个习惯帮我在升级时提前发现了很多问题而不是等到应用启动到一半才报错。5. 开发体验层面的新东西RestClient、结构化日志与更多5.1 RestClient 让同步 HTTP 调用舒服多了以前写同步 HTTP 调用老牌选手是RestTemplate功能强大但 API 设计比较陈旧链式调用不够直观。后来WebClient出来了API 设计现代化可它本质是非阻塞的强行同步使用又不太顺手。Spring Framework 6.1 和 Spring Boot 3.2 带来了RestClient填补了“现代化 API 同步调用”这个缺口。一段简单的用法是这样的RestClient client RestClient.builder() .baseUrl(https://api.example.com) .defaultHeader(Authorization, Bearer token) .build(); ResponseEntityProduct response client.get() .uri(/products/{id}, 42) .retrieve() .toEntity(Product.class);API 风格和WebClient很像但返回值是同步的学习成本很低。以前经常有人问我“multipart 文件怎么用 RestTemplate 传”现在用 RestClient 也支持MultipartBodyBuilder写起来比 RestTemplate 干净很多。如果你是新项目同步调用我建议直接上 RestClient。老项目里RestTemplate还能继续用不用着急迁移。三个客户端的差别可以从这个表里快速了解客户端风格同步/异步推荐场景RestTemplate老式模板同步老项目维护WebClient响应式流式异步非阻塞高并发、事件驱动RestClient现代化链式同步新项目同步调用5.2 结构化日志与可观测性Spring Boot 3.4 开始支持结构化日志简单说就是把传统文本日志转成 JSON 格式方便日志采集系统直接解析字段比如 traceId、spanId、level 等。配置起来非常轻量logging: structured: format: console: ecs其中ecs是 Elastic Common Schemalogstash是老牌的 Logstash 格式gelf也可以选。生产环境配上这个之后排查问题时在日志平台按 traceId 过滤就行不用再用正则去文本里捞。我自己的做法是只在生产环境的 profile 下开启 JSON 结构化日志本地开发还是用普通格式因为控制台看 JSON 实在太费眼。配合 Micrometer Tracing 和 OpenTelemetry链路信息会自动写到日志里前后端排查链路会方便很多。5.3 Docker Compose、CDS 与优雅停机部署环节的细节优化Spring Boot 3.1 开始对 Docker Compose 提供了一等公民支持3.4 又做了增强。开发时你可以在docker-compose.yml里定义 MySQL、Redis 等服务Spring Boot 启动时会自动读取容器信息把数据源配置指过去。这个功能对本地开发特别友好不用人为维护一套复杂的连接配置。优雅停机则是生产发布必备的。以前应用被 kill 时正在处理的请求会突然中断用户端直接看到连接重置。配置两个属性就能改善server: shutdown: graceful spring: lifecycle: timeout-per-shutdown-phase: 30s这样停机时 Spring 会先停止接收新请求再等待已有请求处理完最多等 30 秒。在线发布时用户体感会好很多。另外要注意Spring Boot 3 把一些配置前缀做了整理比如静态资源相关配置从spring.resources.*移动到了spring.web.resources.*。这个在升级老项目时很容易忽略导致静态资源 404。5.4 新 banner 与在线生成器看起来不起眼的小事Spring Boot 3 换过默认 banner 的字体3.2 又更新过一次。新版默认 banner 明显比 2.x 时代更简洁风格也更现代。很多在线的 ASCII banner 生成器已经适配了 Spring Boot 3 的新字体。如果你想定制自己的 banner把生成的文本放到classpath:banner.txt就行。这个功能对生产没有任何影响但团队内部分享、启动截图时还挺有意思。我见过有团队把项目名和吉祥物做成 banner每次启动都很有仪式感。在线生成器几分钟就能搞定完全不用手写 ASCII 艺术。6. 常见问题排查升级与集成时的高频报错速查6.1 升级步骤别直接改版本号就完事很多人在 pom 里把 Spring Boot 版本从 2.7 改成 3.0以为万事大吉结果启动就崩溃。我的建议是不要直接改版本先按这个顺序走一遍把 IDE 和构建环境的 JDK 升到 17 或 21进入 Spring Boot 3 的基线要求。全局搜索代码中的javax.*区分“必须替换的框架 API”和“字符串常量”分批替换。更新第三方依赖到支持 Jakarta 的版本这一步最花时间但值得提前列清单。启动应用用--debug或logging.level.org.springframework.boot.autoconfigureDEBUG看自动配置报告确认关键 Bean 是否装配。跑全量测试重点看 JSON 序列化、反射、文件上传、定时任务这些容易受版本影响的模块。依赖下载如果特别慢可以把 Maven 中央仓库换成阿里云镜像构建体验会好很多。IDE 里运行服务时直接在 Run Configuration 的 Program arguments 里写--server.port8081就能覆盖端口Spring Boot 3.x 依然适用。6.2 高频报错与解决方案速查表实践过程中下面这些报错出现频率最高我整理成了一张表方便大家快速定位报错或现象可能原因解决方案NoClassDefFoundError: javax.servlet.*第三方库还是旧命名空间升级到 jakarta 兼容版本Failed to load AutoConfiguration.imports自定义 starter 还在用 spring.factories新建 AutoConfiguration.imports 文件Parameter 0 of method ... required a single bean自动配置条件不满足看 Positive/Negative matches 排查条件NoClassDefFoundError: jakarta.xml.bind.*缺少 JAXB 实现加入jakarta.xml.bind-api及实现CGLIB 无法代理 final 类/方法类或方法被 final 修饰去掉 final或改接口配合 JDK 代理HikariPool ... Connection is not available数据库连接池耗尽优化慢 SQL、排查连接泄漏Unsupported class file major versionJDK 版本过低编译、运行都确保 JDK 17前两个问题在自定义 starter 中尤其常见第三个则提醒我们尽量用自动配置报告去判断条件是否满足而不是瞎猜。6.3 各中间件集成的兼容性清单结合大家经常搜的一些场景我整理了中间件集成时的兼容性检查点整合 Flink老版本 Flink 对 Spring Boot 3 支持不好建议用 Flink 1.20 以上版本。实在要用旧版可以把 Flink client 放到独立模块通过 REST API 配合避免NoClassDefFoundError污染主服务类加载。集成金仓 V8旧版 JDBC 驱动可能不兼容新 HikariCP 的自动检测逻辑优先换新驱动再检查 JPA 或 MyBatis 的方言配置。整合 ActiveMQ把javax.jms相关的依赖全部换成jakarta.jms同时用 Spring Boot 3 对应的 starter不要混搭。MyBatis用mybatis-spring-boot-starter3.0老版本 2.x starter 在 Boot 3 下会自动装配失败。多数据源场景建议自定义SqlSessionFactory来避免自动配置互相干扰。HanLP 分词这类纯算法库一般不受 Servlet/JPA 影响主要检查它的底层依赖是否与 JDK 17/21 兼容。若依框架这种 Spring Boot 脚手架项目升级时要连带看它的自动配置和权限模块是否基于 Jakarta 重编译跑通后再引入 TDengine、MySQL 等多数据源方案。6.4 我的实际体会从我这边十几个服务的升级结果来看Spring Boot 3.x 并不是一次伤筋动骨的重写更像是一次技术栈换底。最耗时的是第三方依赖适配而不是 Spring 本身。虚拟线程对 IO 型服务的效果最直接配置简单收益明显原生镜像是好东西但构建复杂度和维护成本不适合所有团队CDS 可以作为过渡方案CGLIB 带来的影响比想象中小只要不随便写 final 类就没有太大感觉。如果你现在还在 2.7 徘徊我的建议是尽早把升级排进迭代越晚第三方生态适配的压力越大。升级时养成看自动配置报告和依赖树的习惯比对着报错盲目改代码高效得多。Spring Boot 3.x 的新特性本质上都在围绕两个方向走把云原生部署做到位把高并发场景下的开发者体验做到位。理解了这条主线其他细节都只是时间问题。
