Swagger → SpringDoc 迁移

<span style="color:#000000"><span style="background-color:#fefef2"><code class="language-java">	<!-- 移除旧的 Swagger 依赖 -->
    <!--
    <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
    </dependency>
    -->
    <!-- 添加新的 SpringDoc 依赖 -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version><span style="color:#b75501">2.3</span><span style="color:#b75501">.0</span></version>
    </dependency>
</code></span></span>

配置示例

<span style="color:#000000"><span style="background-color:#fefef2"><code class="language-java"><span style="color:#015692">@Configuration</span>
<span style="color:#015692">@OpenAPIDefinition</span>
<span style="color:#015692">public</span> <span style="color:#015692">class</span> <span style="color:#b75501">SwaggerConfig</span> {
    <span style="color:#015692">@Bean</span>
    <span style="color:#015692">public</span> OpenAPI <span style="color:#b75501">openAPI</span>() {
        <span style="color:#b75501">OpenAPI</span> <span style="color:#54790d">openAPI</span> <span style="color:#ab5656">=</span> <span style="color:#015692">new</span> <span style="color:#b75501">OpenAPI</span>();
        openAPI.info(<span style="color:#015692">new</span> <span style="color:#b75501">Info</span>().title(<span style="color:#54790d">"API 文档"</span>).version(<span style="color:#54790d">"1.0"</span>));
        <span style="color:#656e77">// 配置 Authorization 登录鉴权</span>
        Map<String, SecurityScheme> map = Map.of(<span style="color:#54790d">"Authorization"</span>,
                <span style="color:#015692">new</span> <span style="color:#b75501">SecurityScheme</span>()
                        .type(SecurityScheme.Type.APIKEY)
                        .in(SecurityScheme.In.HEADER)
                        .name(<span style="color:#54790d">"Authorization"</span>));
        openAPI.components(<span style="color:#015692">new</span> <span style="color:#b75501">Components</span>().securitySchemes(map));
        map.keySet().forEach(key -> openAPI.addSecurityItem(<span style="color:#015692">new</span> <span style="color:#b75501">SecurityRequirement</span>().addList(key)));
        <span style="color:#015692">return</span> openAPI;
    }
}
</code></span></span>

注解对应关系

访问地址变更

原 Swagger UI 地址： http://localhost:8080/swagger-ui.html
新 SpringDoc 地址： http://localhost:8080/swagger-ui/index.html

问题四：依赖冲突与安全漏洞修复

检测工具

使用 IDEA 自带的依赖分析工具：

必须升级的依赖（存在高危漏洞）

推荐使用 OWASP Dependency-Check 或 Snyk 扫描：

<span style="color:#000000"><span style="background-color:#fefef2"><code class="language-shell">mvn dependency-check:check
</code></span></span>

解决依赖冲突的技巧

问题：Maven 依赖解析采用"最短路径优先"和"第一声明优先"原则，可能导致旧版本覆盖新版本。

解决方案：显式声明期望的版本

<span style="color:#000000"><span style="background-color:#fefef2"><code class="language-java"><dependencies>
    <!-- 显式声明 Spring Framework 版本，避免被传递依赖覆盖 -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-core</artifactId>
        <version><span style="color:#b75501">6.1</span><span style="color:#b75501">.3</span></version>
    </dependency>
</dependencies>
</code></span></span>

快速检测技巧：

在 IDEA 的 Maven 依赖树中搜索 RELEASE ，Spring 新版本已不使用 RELEASE 后缀，搜索到的基本都是旧版本。

问题五：URL 尾斜杠匹配策略变更

行为变化

常见导致尾斜杠的情况

• Case 1：类注解带尾斜杠

<span style="color:#000000"><span style="background-color:#fefef2"><code class="language-java"><span style="color:#015692">@RequestMapping("/api/user/")</span>
<span style="color:#015692">public</span> <span style="color:#015692">class</span> <span style="color:#b75501">UserController</span> {
 <span style="color:#015692">@PostMapping("login")</span> <span style="color:#656e77">// 实际路径：/api/user/login</span>
}
</code></span></span>

Case 2：空字符串映射

<span style="color:#000000"><span style="background-color:#fefef2"><code class="language-java"><span style="color:#015692">@RequestMapping("/api/user")</span>
<span style="color:#015692">public</span> <span style="color:#015692">class</span> <span style="color:#b75501">UserController</span> {
 <span style="color:#015692">@PostMapping("")</span> <span style="color:#656e77">// 实际路径：/api/user/（带尾斜杠！）</span>
}
</code></span></span>

Case 3：根路径映射

<span style="color:#000000"><span style="background-color:#fefef2"><code class="language-java"><span style="color:#015692">@PostMapping("/")</span> <span style="color:#656e77">// 实际路径：/（带尾斜杠）</span>
</code></span></span>

**** 检查方式

1. IDEA Endpoints 工具窗口：查看所有端点
2. SpringDoc UI：访问 Swagger 页面检查

临时解决方案（不推荐长期使用）

<span style="color:#000000"><span style="background-color:#fefef2"><code class="language-java"><span style="color:#015692">import</span> org.springframework.context.annotation.Configuration;
<span style="color:#015692">import</span> org.springframework.web.servlet.config.annotation.PathMatchConfigurer;
<span style="color:#015692">import</span> org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

<span style="color:#015692">@Configuration</span>
<span style="color:#015692">public</span> <span style="color:#015692">class</span> <span style="color:#b75501">WebConfiguration</span> <span style="color:#015692">implements</span> <span style="color:#b75501">WebMvcConfigurer</span> {
    <span style="color:#015692">@Override</span>
    <span style="color:#015692">public</span> <span style="color:#015692">void</span> <span style="color:#b75501">configurePathMatch</span>(PathMatchConfigurer configurer) {        
        <span style="color:#656e77">// 设 置 为  true 以 忽 略 尾 斜 杠 ， 恢 复 旧 版 本 行 为</span>
        configurer.setUseTrailingSlashMatch(<span style="color:#b75501">true</span>);
    }
}
</code></span></span>

注意__： ·setUseTrailingSlashMatch 在 Spring 6.x 后已标记为废弃，后续版本将删除。建议逐步修正所有端点，去除尾斜杠。

根本解决方案

1. 修正所有 Controller 的路径映射
2. 通知前端团队同步修改调用路径
3. 如果有硬编码的 URL，全局搜索并修正
4. 使用测试确保前后端调用正常

问题六：Apache POI / EasyExcel 升级

背景

Apache POI 旧版本（< 5.0）存在多个 CVE 安全漏洞，必须升级。

推荐方案

对于新项目：直接使用 FastExcel

<span style="color:#000000"><span style="background-color:#fefef2"><code class="language-java"><dependency>
     <groupId>cn.idev.excel</groupId>
     <artifactId>fastexcel</artifactId>
     <version><span style="color:#b75501">1.0</span><span style="color:#b75501">.0</span></version>
</dependency>
</code></span></span>

对于使用 EasyExcel 的旧项目：

<span style="color:#000000"><span style="background-color:#fefef2"><code class="language-java"><dependency>
     <groupId>com.alibaba</groupId>
     <artifactId>easyexcel</artifactId>
     <version><span style="color:#b75501">4.0</span><span style="color:#b75501">.3</span></version>
</dependency>
</code></span></span>

说明：EasyExcel 已不再维护，FastExcel 是社区维护的替代方案，API 基本兼容。

迁移注意事项

EasyExcel 跨大版本升级（2.x → 4.x）API 变化较大，主要改动：

1. 监听器接口方法签名调整

2. 部分工具类包路径变更

3. 自定义转换器需要适配新接口

建议参考官方迁移文档：EasyExcel官方文档 - 基于Java的Excel处理工具 | Easy Excel 官网

问题七：JDK 模块化限制（--add-opens）

问题现象

某些依赖库使用反射访问 JDK 内部 API，在 JDK 9+ 模块化系统下会报错：

<span style="color:#000000"><span style="background-color:#fefef2"><code class="language-java">InaccessibleObjectException: Unable to make field accessible:
<span style="color:#015692">module</span> java.base does not <span style="color:#54790d">"opens java.net"</span> to unnamed <span style="color:#015692">module</span>
</code></span></span>

解决方案

在 IDEA 运行配置中添加 VM 参数：

开启 VM 参数配置（默认隐藏）：