基于 Spring Cloud Samples 微服务项目从 Spring Boot 3.x 升级到 4.0.0 的真实踩坑经历，涵盖依赖变更、编译错误、运行时异常的完整排查与修复过程。

背景

Spring Boot 4.0 于 2025 年 11 月正式发布，基于 Spring Framework 7.0 构建，是一次基线换代级别的大版本升级。本次升级的项目技术栈如下：

组件	版本
Spring Boot	4.0.0
Spring Cloud	2025.1.0
Spring Cloud Alibaba	2025.1.0.0
Java	21（LTS）
服务注册发现	Nacos
链路追踪	OpenTelemetry
RPC	Dubbo 3.3.6

---

坑一：spring-boot-starter-web 被拆分

报错现象

升级后编译报错：

Cannot resolve symbol 'client'
import org.springframework.boot.web.client.RestTemplateBuilder;

原因分析

Spring Boot 4.0 进行了模块化拆分，原来的 spring-boot-starter-web 被拆分为多个独立模块：

Spring Boot 3.x	Spring Boot 4.0
spring-boot-starter-web（MVC + RestTemplate）	spring-boot-starter-webmvc（仅 MVC 服务端）
—	spring-boot-starter-restclient（RestTemplate + RestClient）

修复方式

第一步：修改 Maven 依赖

<!-- 旧依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- 新依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-restclient</artifactId>
</dependency>

第二步：修改 Java import 包名

RestTemplateBuilder 的包路径发生了变化：

// 旧包路径（Spring Boot 3.x）
import org.springframework.boot.web.client.RestTemplateBuilder;

// 新包路径（Spring Boot 4.0）
import org.springframework.boot.restclient.RestTemplateBuilder;

排查技巧： 用 jar tf 命令直接查看 jar 包内的类路径确认新包名：

jar tf ~/.m2/repository/.../spring-boot-restclient/4.0.0/spring-boot-restclient-4.0.0.jar | grep RestTemplateBuilder

---

坑二：链路追踪 Tracer Bean 找不到

报错现象

启动时报错：

Parameter 0 of method feignTracingInterceptor required a bean of type
'io.micrometer.tracing.Tracer' that could not be found.

原因分析

Spring Boot 3.x 中，spring-boot-starter-actuator 内置了 MicrometerTracingAutoConfiguration，会自动创建 Tracer Bean。

Spring Boot 4.0 将 tracing 自动配置彻底拆分到独立模块，actuator 不再包含 tracing 功能。

修复方式

直接用 spring-boot-starter-opentelemetry 替换 micrometer-tracing-bridge-otel：

<!-- 旧依赖（Spring Boot 3.x） -->
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>

<!-- 新依赖（Spring Boot 4.0） -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-opentelemetry</artifactId>
</dependency>

spring-boot-starter-opentelemetry 内部包含完整依赖链：

spring-boot-starter-opentelemetry
  ├── spring-boot-opentelemetry                    ← 创建 OpenTelemetry Bean
  ├── spring-boot-micrometer-tracing-opentelemetry ← 创建 Tracer Bean
  ├── micrometer-tracing-bridge-otel               ← OTel 桥接实现
  └── opentelemetry-exporter-otlp                  ← 数据导出器

踩坑提醒： 如果只引入 spring-boot-micrometer-tracing-opentelemetry 而不引入 spring-boot-opentelemetry，会依次报两个错误：

1. required a bean of type 'io.opentelemetry.api.OpenTelemetry' that could not be found
2. required a bean of type 'io.micrometer.tracing.Tracer' that could not be found

---

坑三：OTLP Metrics 持续报 Connection refused

报错现象

应用启动后，控制台周期性刷出异常：

java.lang.Exception: java.net.ConnectException: Connection refused
    at io.micrometer.registry.otlp.OtlpHttpMetricsSender.send(...)
    at io.micrometer.registry.otlp.OtlpMeterRegistry.publish(...)

原因分析

spring-boot-starter-opentelemetry 内置了 micrometer-registry-otlp，默认定期将 metrics 推送到 OTLP Collector（默认地址 http://localhost:4318/v1/metrics）。本地开发环境没有运行 OTLP Collector，因此连接被拒绝。

修复方式

在 application.yml 中禁用 OTLP metrics 导出：

management:
  metrics:
    export:
      otlp:
        enabled: false
  tracing:
    sampling:
      probability: 1.0

生产环境建议： 部署到有 OTLP Collector 的环境时，将 enabled 改回 true，或通过 management.metrics.export.otlp.url 指定正确的地址。

---

升级清单汇总

序号	问题	根因	修复方式
1	Cannot resolve symbol 'client'	starter-web 被拆分	改为 webmvc + restclient
2	RestTemplateBuilder 找不到	包名变更	import 改为 org.springframework.boot.restclient
3	Tracer Bean 找不到	tracing 从 actuator 中移除	使用 spring-boot-starter-opentelemetry
4	OpenTelemetry Bean 找不到	缺少核心模块	同上（starter 已包含）
5	OTLP Metrics Connection refused	默认启用 OTLP 导出	management.metrics.export.otlp.enabled: false

---

其他注意事项

WebFlux / Gateway 模块无需改动

使用 spring-boot-starter-webflux 的响应式模块和 Spring Cloud Gateway 模块无需修改，starter 名称和包结构在 4.0 中保持不变。

Spring Cloud Alibaba 已知 Bug

启动时若出现 nacosGracefulShutdownDelegate 的 BeanCreationNotAllowedException，这是 Spring Cloud Alibaba 的已知 Bug（#4064），属于启动失败后清理阶段产生的二级错误，真正的问题需查看完整日志中第一个报错。

---

结语

Spring Boot 4.0 的模块化拆分是大势所趋，让依赖更精细、启动更快、镜像更小。升级时需要重点排查：

1. Maven 依赖：starter 名称和模块结构的变化
2. Java 包名：类的包路径可能已迁移
3. 自动配置：原来内置的功能可能需要显式引入

建议升级前先通读 Spring Boot 4.0 Migration Guide，并在测试环境充分验证后再上线。

项目地址：https://github.com/javahongxi/spring-cloud-samples