Spring Boot 2.x =＞ 3.x 升级指南

注意：升级前务必全面测试，特别是涉及序列化/反序列化的组件（Jackson/Druid等）。

1. Swagger 替换

新地址

http://localhost:8080/swagger-ui/index.html

依赖调整

移除其他 Swagger 依赖，仅添加：

xml 复制代码

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

配置修改

java 复制代码

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI csimpOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("title")
                .description("接口说明")
                .termsOfService("http://localhost:8080/")
                .version("1.0.0")
                .license(new License()
                    .name("Apache 2.0")
                    .url("http://localhost:8080/")));
    }
}

application.yml 配置（可选）

yaml 复制代码

springdoc:
  swagger-ui:
    path: /swagger-ui.html
  api-docs:
    enabled: true

注解替换对照表

旧注解	新注解	属性说明
`@ApiOperation`	`@Operation`	`value → summary`，`notes → description`
`@Api`	`@Tag`	`tags → name`， `value → description`
`@ApiModelProperty`	`@Schema`	`value/name → description`
`@ApiImplicitParams`	`@Parameters`	使用 `@Parameter` + `ParameterIn.HEADER`
`@ApiResponse`	`@ApiResponse`	使用 `@ApiResponses` 包装

示例：

java 复制代码

// 原注解
@ApiOperation(value = "我是value", notes = "我是notes")
@Api(tags = "我是tags")

// 新注解
@Operation(summary = "我是value", description = "我是描述")
@Tag(name = "我是tags", description = "我是描述")

2. Javax → Jakarta 迁移

升级 Java 17 后需替换包名：

diff 复制代码

- javax.annotation.Resource
+ jakarta.annotation.Resource

- javax.validation.Valid
+ jakarta.validation.Valid

- jakarta.servlet.ServletRequest  // 保持 jakarta
+ jakarta.servlet.ServletRequest

// 其他类似替换...

完整替换清单：

javax.annotation.* → jakarta.annotation.*
javax.validation.* → jakarta.validation.*
javax.servlet.* → jakarta.servlet.*

3. RestTemplate 配置变更

Spring Boot 3.x 推荐 WebClient，RestTemplate 需调整：

java 复制代码

import org.apache.hc.client5.http.classic.CloseableHttpClient;
import org.apache.hc.client5.http.config.RequestConfig;
import org.apache.hc.client5.http.impl.classic.HttpClients;
import org.apache.hc.core5.util.Timeout;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
import org.springframework.web.client.RestTemplate;

@Configuration
public class RestTemplateConfig {
    @Bean
    public RestTemplate restTemplate() {
        int connectTimeOut = 5000;
        int readTimeout = 10000;

        RequestConfig requestConfig = RequestConfig.custom()
            .setResponseTimeout(Timeout.ofSeconds(readTimeout))
            .build();
        
        CloseableHttpClient httpClient = HttpClients.custom()
            .setDefaultRequestConfig(requestConfig)
            .build();
        
        HttpComponentsClientHttpRequestFactory factory = 
            new HttpComponentsClientHttpRequestFactory(httpClient);
        factory.setConnectTimeout(connectTimeOut);
        
        return new RestTemplate(factory);
    }
}

4. 依赖版本升级清单

Hibernate Validator

移除手动版本号，使用 Spring Boot 管理版本：

xml 复制代码

<!-- 删除此行 -->
<!-- <hibernate-validator.version>6.1.7.Final</hibernate-validator.version> -->

Logback

移除手动版本号：

xml 复制代码

<!-- 删除此行 -->
<!-- <logback.version>1.2.9</logback.version> -->

Lombok

升级版本：

xml 复制代码

<lombok.version>1.18.32</lombok.version>

MyBatis Plus

升级版本：

xml 复制代码

<mybatis-plus.version>3.5.5</mybatis-plus.version>
<mybatis-plus-generator.version>3.5.5</mybatis-plus-generator.version>
<mybatis.version>3.5.13</mybatis.version>
<mybatis-spring.version>3.0.3</mybatis-spring.version>
<mysql-connector.version>8.0.33</mysql-connector.version>

MapStruct

升级版本：

xml 复制代码

<mapstruct.version>1.5.5.Final</mapstruct.version>

Guava

升级版本：

xml 复制代码

<guava.version>32.1.3-jre</guava.version>

SnakeYAML

指定版本：

xml 复制代码

<snakeyaml.version>2.2</snakeyaml.version>
<dependency>
    <groupId>org.yaml</groupId>
    <artifactId>snakeyaml</artifactId>
    <version>${snakeyaml.version}</version>
</dependency>

Jackson

显式管理版本：

xml 复制代码

<jackson.version>2.15.4</jackson.version>
<!-- 添加 Jackson 组件 -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>${jackson.version}</version>
</dependency>
<!-- 其他 Jackson 模块... -->

Druid

升级版本：

xml 复制代码

<druid.version>1.2.20</druid.version>

5. 其他关键变更

Hystrix 替换

xml 复制代码

<!-- 移除 -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-hystrix</artifactId>
</dependency>

<!-- 替换为 Resilience4j -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-circuitbreaker-resilience4j</artifactId>
</dependency>

跨域配置更新

java 复制代码

@Bean
public WebMvcConfigurer corsConfigurer() {
    return new WebMvcConfigurer() {
        @Override
        public void addCorsMappings(CorsRegistry registry) {
            registry.addMapping("/**")
                .allowedOriginPatterns("*")  // 替换 allowedOrigins
                .allowCredentials(true)
                .allowedMethods("GET", "POST", "PUT", "DELETE")
                .maxAge(3600);
        }
    };
}

循环依赖处理

Spring Boot 3.x 加强循环依赖检测，需重构代码消除循环调用。

一键三连，让我的信心像气球一样膨胀！