Spring Boot 3 到 4 迁移完全指南：新特性、废弃功能与实战踩坑经验

<!-- 替代 spring-boot-starter -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-classic</artifactId>
</dependency>

<!-- 替代 spring-boot-starter-test -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test-classic</artifactId>
    <scope>test</scope>
</dependency>

@ConfigurationPropertiesSource("com.example.config")
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    // getters and setters
}

@Configuration
public class TaskConfig {

    @Bean
    public TaskDecorator loggingTaskDecorator() {
        return runnable -> {
            return () -> {
                System.out.println("Task started: " + Thread.currentThread().getName());
                try {
                    runnable.run();
                } finally {
                    System.out.println("Task completed");
                }
            };
        };
    }

    @Bean
    public TaskDecorator mdcTaskDecorator() {
        return runnable -> {
            String traceId = MDC.get("traceId");
            return () -> {
                MDC.put("traceId", traceId);
                try {
                    runnable.run();
                } finally {
                    MDC.clear();
                }
            };
        };
    }
}

// Spring Boot 3.x
import org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration;

// Spring Boot 4.0
import org.springframework.boot.webmvc.autoconfigure.WebMvcAutoConfiguration;

@Configuration
public class WebConfiguration implements WebMvcConfigurer {
    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer.useRequestHeader("API-Version");
        // 或使用其他策略：
        // configurer.useQueryParameter("version");
        // configurer.usePathPattern("/api/{version}");
        // configurer.useMediaType("application/vnd.api.v1+json");
    }
}

spring:
  mvc:
    apiversion:
      use:
        header: API-Version
        # 或使用：
        # query-parameter: version
        # path-pattern: /api/{version}

@RestController
@RequestMapping("/api")
public class UserController {

    @GetMapping(value = "/users", version = "1")
    public List<UserV1> getUsersV1() {
        return userService.getUsersV1();
    }

    @GetMapping(value = "/users", version = "2")
    public List<UserV2> getUsersV2() {
        return userService.getUsersV2();
    }
}

RouterFunction<ServerResponse> route = RouterFunctions.route()
    .GET("/hello-world", version("1.2"),
        request -> ServerResponse.ok().body("Hello World"))
    .build();

import org.jspecify.annotations.Nullable;
import org.jspecify.annotations.NonNull;

public class UserService {

    public @NonNull User getUser(@NonNull String userId) {
        return userRepository.findById(userId)
            .orElseThrow(() -> new UserNotFoundException(userId));
    }

    public @Nullable User findUser(@NonNull String email) {
        return userRepository.findByEmail(email).orElse(null);
    }
}

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(Application.class);
        // 启用异步启动
        app.setApplicationStartup(new BufferingApplicationStartup(1000));
        app.run(args);
    }
}

spring:
  application:
    startup:
      enabled: true

@HttpExchange(url = "/api/users")
public interface UserClient {
    @GetExchange("/{id}")
    User getUser(@PathVariable String id);

    @PostExchange
    User createUser(@RequestBody UserRequest request);
}

// 需要手动配置每个客户端
@Configuration
public class HttpClientConfig {
    @Bean
    public UserClient userClient(RestClient.Builder builder) {
        RestClient restClient = builder.baseUrl("https://api.example.com").build();
        HttpServiceProxyFactory factory = HttpServiceProxyFactory
            .builderFor(RestClientAdapter.create(restClient)).build();
        return factory.createClient(UserClient.class);
    }

    // 如果有多个客户端，需要重复配置。..
}

@HttpExchange(url = "/api/users")
public interface UserClient {
    @GetExchange("/{id}")
    User getUser(@PathVariable String id);

    @PostExchange
    User createUser(@RequestBody UserRequest request);
}

@Configuration
@ImportHttpServices(group = "api", types = {UserClient.class})
public class HttpClientConfig {
}

spring:
  http:
    client:
      service:
        read-timeout: 2s
        group:
          api:
            base-url: https://api.example.com

@Configuration
@ImportHttpServices(group = "api", basePackages = "com.example.client")
public class HttpClientConfig {
}

@Configuration
@ImportHttpServices(group = "github", basePackages = "com.example.client.github")
@ImportHttpServices(group = "stackoverflow", basePackages = "com.example.client.stackoverflow")
public class HttpClientConfig {
}

spring:
  http:
    client:
      service:
        group:
          github:
            base-url: https://api.github.com
            read-timeout: 5s
          stackoverflow:
            base-url: https://api.stackexchange.com
            read-timeout: 10s

@Configuration
@ImportHttpServices(
    group = "api",
    basePackages = "com.example.client",
    clientType = ClientType.WEB_CLIENT
)
public class HttpClientConfig {
}

@Service
public class UserService {
    private final UserClient userClient;  // 直接注入，无需手动配置

    public UserService(UserClient userClient) {
        this.userClient = userClient;
    }

    public User getUser(String id) {
        return userClient.getUser(id);  // 直接使用
    }
}

@Configuration
@EnableResilientMethods
public class ApplicationConfig {
}

@Service
public class PaymentService {

    @Retryable(
        maxAttempts = 3,
        backoff = @Retryable.Backoff(delay = 2000, multiplier = 2.0)
    )
    @ConcurrencyLimit(value = 2)  // 只允许 2 个并发调用
    public void processPayment(String paymentId) {
        // 处理支付逻辑
    }
}

@Service
public class MessageService {

    private final JmsClient jmsClient;

    public MessageService(JmsClient jmsClient) {
        this.jmsClient = jmsClient;
    }

    public void sendMessage(String destination, String message) {
        jmsClient.create()
            .queue(destination)
            .body(message)
            .send();
    }

    public String receiveMessage(String destination) {
        return jmsClient.create()
            .queue(destination)
            .receive(String.class);
    }
}

// 旧方式（仍然支持）
@PersistenceContext
private EntityManager entityManager;

// 新方式（Spring Framework 7 / JPA 3.2）
@Autowired
private EntityManager entityManager;

// 多个持久化单元时使用限定符
@Autowired
@Qualifier("primaryEntityManager")
private EntityManager primaryEntityManager;

// Jackson 2.x
@JsonInclude(JsonInclude.Include.NON_NULL)
public class User {
    private String name;
    // ...
}

// Jackson 3.x （同样的语法，但内部行为可能不同）
@JsonInclude(JsonInclude.Include.NON_NULL)
public class User {
    private String name;
    // ...
}

@Value("#{userService.findUser('123')?.name ?: 'Unknown'}")
private String userName;

import org.springframework.context.bean.BeanRegistrar;
import org.springframework.context.bean.BeanRegistry;

public class QuoteProviderRegistrar implements BeanRegistrar {
    @Override
    public void register(BeanRegistry registry, Environment env) {
        registry.registerBean("quoteProviderDb", QuoteProviderDb.class);
        registry.registerBean("quoteProviderFallback",
                QuoteProviderFallback.class,
                spec -> {
                    spec.fallback();
                    spec.order(1);
                });
    }
}

import org.springframework.context.bean.BeanRegistrarDsl

class QuoteProviderRegistrar : BeanRegistrarDsl({
    registerBean<QuoteProviderDb>("quoteProviderDb")
    registerBean<QuoteProviderFallback>(
        name = "quoteProviderFallback",
        fallback = true,
        order = 1
    )
})

spring:
  threads:
    virtual:
      enabled: true

// Spring Boot 3.x （已废弃，4.0 移除）
@SpringBootTest
class UserServiceTest {
    @MockBean
    private UserRepository userRepository;
}

// Spring Boot 4.0 （使用 Spring 官方支持）
@SpringBootTest
class UserServiceTest {
    @MockitoBean
    private UserRepository userRepository;
}

// Spring Boot 2.x/3.x （已废弃）
@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/public/**").permitAll()
            .anyRequest().authenticated();
    }
}

// Spring Boot 4.0
@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/public/**").permitAll()
                .anyRequest().authenticated()
            )
            .build();
    }
}

<!-- Spring Boot 4.0 不再支持 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-undertow</artifactId>
</dependency>

<!-- 如果需要持久化元数据，显式添加 JDBC 支持 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-batch-jdbc</artifactId>
</dependency>

// 旧代码（Spring Framework 6.x）
HttpHeaders headers = new HttpHeaders();
headers.add("Content-Type", "application/json");
String contentType = headers.getFirst("Content-Type");

// 新代码（Spring Framework 7.0）
HttpHeaders headers = new HttpHeaders();
headers.add("Content-Type", "application/json");
String contentType = headers.getFirst("Content-Type"); // 仍然可用
// 或使用
boolean hasContentType = headers.contains("Content-Type"); // 大小写不敏感

// 推荐：使用标准格式
headers.add("Content-Type", "application/json");
headers.add("Authorization", "Bearer token");
headers.add("X-Custom-Header", "value");

// 问题代码：直接字符串比较可能失败
Enumeration<String> headerNames = request.getHeaderNames();
while (headerNames.hasMoreElements()) {
    String name = headerNames.nextElement();
    if (name.equals("content-type")) { // 可能失败，name 可能是 "Content-Type"
        // ...
    }
}

// 推荐：使用大小写不敏感比较
if (name.equalsIgnoreCase("content-type")) {
    // ...
}

// MockHttpServletRequest 的行为已更新
MockHttpServletRequest request = new MockHttpServletRequest();
request.addHeader("Content-Type", "application/json");

// 以下都能正常工作（大小写不敏感）
assertThat(request.getHeader("Content-Type")).isNotNull();
assertThat(request.getHeader("content-type")).isNotNull();
assertThat(request.getHeader("CONTENT-TYPE")).isNotNull();

// 但遍历时需要注意原始大小写
Enumeration<String> names = request.getHeaderNames();
while (names.hasMoreElements()) {
    String name = names.nextElement();
    // name 可能是 "Content-Type" 而不是 "content-type"
    assertThat(name).isEqualTo("Content-Type"); // 使用原始大小写
}

error: [nullness] incompatible types in return.
  required: @NonNull String
  found:    @Nullable String

// Kotlin 中处理可空类型
val user: User? = userService.findUser("123")
val name: String = user?.name ?: "Unknown"

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <compilerArgs>
            <arg>-Xlint:-nullness</arg>
        </compilerArgs>
    </configuration>
</plugin>

@Configuration
public class JacksonConfig {

    @Bean
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        // 恢复 Jackson 2.x 的兼容性行为
        mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
        mapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false);
        mapper.registerModule(new JavaTimeModule());
        return mapper;
    }
}

<dependency>
    <groupId>com.example</groupId>
    <artifactId>legacy-library</artifactId>
    <version>1.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>org.springframework</groupId>
            <artifactId>*</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-batch-jdbc</artifactId>
</dependency>

spring:
  batch:
    jdbc:
      initialize-schema: always

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <!-- 默认使用 Tomcat，无需额外配置 -->
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jetty</artifactId>
</dependency>

# 优化数据库连接池
spring:
  datasource:
    hikari:
      maximum-pool-size: 50  # 虚拟线程环境可适当增加
      minimum-idle: 10

# 确保启用虚拟线程
spring:
  threads:
    virtual:
      enabled: true

@SpringBootTest
@TestPropertySource(properties = {
    "spring.test.context.cache.maxSize=10"
})
class MyTest {
    // ...
}

<build>
    <plugins>
        <plugin>
            <groupId>org.openrewrite.maven</groupId>
            <artifactId>rewrite-maven-plugin</artifactId>
            <version>5.40.0</version>
            <configuration>
                <activeRecipes>
                    <recipe>org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0</recipe>
                </activeRecipes>
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>org.openrewrite.recipe</groupId>
                    <artifactId>rewrite-spring</artifactId>
                    <version>5.22.0</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

plugins {
    id 'org.openrewrite.rewrite' version '6.25.0'
}

rewrite {
    activeRecipe('org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0')
}

dependencies {
    rewrite 'org.openrewrite.recipe:rewrite-spring:5.22.0'
}

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests().anyRequest().authenticated();
    }
}

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http.authorizeHttpRequests(auth ->
            auth.anyRequest().authenticated()
        ).build();
    }
}