SpringDoc OpenAPI 配置
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 2.x | SpringDoc OpenAPI 3.x |
|---|---|
| @Api | @Tag |
| @ApiOperation | @Operation |
| @ApiParam | @Parameter |
| @ApiModel | @Schema |
| @ApiModelProperty | @Schema |
访问地址变更
原 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 尾斜杠匹配策略变更
行为变化
| 版本 | 行为 |
|---|---|
| Spring Boot 2.x | /api/user/get 和 /api/user/get/ 视为同一接口 |
| Spring Boot 3.x | /api/user/get 和 /api/user/get/ 视为不同接口 |
常见导致尾斜杠的情况
- 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>
**** 检查方式
- IDEA Endpoints 工具窗口：查看所有端点
- 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 后已标记为废弃，后续版本将删除。建议逐步修正所有端点，去除尾斜杠。
根本解决方案
- 修正所有 Controller 的路径映射
- 通知前端团队同步修改调用路径
- 如果有硬编码的 URL，全局搜索并修正
- 使用测试确保前后端调用正常
问题六：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 参数配置（默认隐藏）：