SpringDoc与Spring Boot 3.4.0版本兼容性问题分析

问题背景

SpringDoc是一个流行的开源库，用于为Spring Boot应用程序自动生成OpenAPI 3.0文档。近期有开发者反馈，在将项目升级到Spring Boot 3.4.0版本后，与SpringDoc的集成出现了兼容性问题。

问题现象

当项目同时使用以下依赖时会出现启动失败：

• org.springframework.boot:spring-boot-starter-validation:3.4.0
• org.springdoc:springdoc-openapi-starter-webmvc-ui:2.7.0

错误信息表明Spring框架中某个类的方法调用失败，具体是org.springdoc.webmvc.ui.SwaggerWelcomeCommon类在初始化时尝试调用不存在的方法。

根本原因

经过分析，这个问题源于Spring Framework 6.2.0版本中的一个变更。该版本引入了一个新的类结构，导致SpringDoc在初始化时无法找到预期的方法签名。

解决方案

目前有以下几种解决方式：

1. 等待官方修复：Spring团队已经在6.2.1-SNAPSHOT版本中修复了这个问题，该修复将包含在Spring Boot 3.4.1的正式发布中。

2. 临时使用快照版本：可以通过在构建配置中显式指定Spring Framework的快照版本：

   repositories {
       maven { url "https://repo.spring.io/snapshot" }
   }
   
   ext["spring-framework.version"] = "6.2.1-SNAPSHOT"
   

3. 版本降级：暂时回退到Spring Boot 3.3.5和SpringDoc 2.6.0版本组合。

注意事项

开发者需要注意，这个问题与另一个常见的依赖版本不匹配问题是不同的。后者通常表现为同时使用了不同版本的SpringDoc starter组件（如同时使用springdoc-openapi-starter-common 2.6.0和springdoc-openapi-starter-webmvc-ui 2.7.0）。这种情况下，应该统一所有SpringDoc相关依赖的版本号。

最佳实践建议

1. 在升级Spring Boot版本时，建议先查看SpringDoc的官方兼容性说明
2. 使用依赖管理工具确保所有相关依赖版本一致
3. 在CI/CD流程中加入版本兼容性检查
4. 考虑使用BOM(物料清单)来管理相关依赖版本

结论

Spring生态系统的组件间依赖关系复杂，版本升级时需要特别注意兼容性问题。当前SpringDoc与Spring Boot 3.4.0的兼容性问题已有明确的解决方案，开发者可以根据项目实际情况选择合适的应对策略。