本文旨在解决在Spring Web MVC项目中集成`springdoc-openapi-ui`时，因依赖版本冲突导致的类找不到问题，特别是`AbstractExcelView`等Spring Framework核心类。文章将深入分析冲突原因，提供诊断依赖冲突的方法，并给出通过排除依赖、统一版本管理等策略来有效解决此类问题的专业指导，确保OpenAPI文档生成工具能顺利集成。
理解依赖冲突的本质
在Spring Web MVC项目中集成新的库，如用于生成OpenAPI文档的springdoc-openapi-ui时，可能会遇到现有类（例如org.springframework.web.servlet.view.document.AbstractExcelView）突然无法导入的问题。这并非springdoc-openapi-ui直接删除了这些类，而是由于其引入了与项目当前使用的Spring Framework版本不兼容的传递性依赖。
springdoc-openapi-ui自身依赖于特定版本的Spring Framework组件（如spring-webmvc、spring-context等）。当您将其添加到项目中时，构建工具（如Gradle或Maven）会尝试解析所有依赖并选择一个版本。如果springdoc-openapi-ui所依赖的Spring Framework版本与您项目显式声明或通过其他依赖引入的Spring Framework版本不一致，就会发生冲突。构建工具通常会采用“最近依赖原则”或特定策略来解决版本冲突，但这可能导致项目最终使用的Spring Framework版本与预期不符，从而使得某些类（如AbstractExcelView在某些Spring版本中可能被移除、重命名或移动到不同包）无法找到。
诊断依赖冲突
定位冲突是解决问题的第一步。您可以使用构建工具提供的命令来查看项目的完整依赖树，从而找出哪些依赖引入了冲突的Spring Framework版本。
使用Gradle诊断
在项目根目录下执行以下命令：
gradle dependencies --configuration runtimeClasspath
或者，如果想查看特定模块的依赖：
gradle :your-module-name:dependencies --configuration runtimeClasspath
此命令会输出详细的依赖树，其中会显示每个依赖项及其版本，以及哪些版本被解决策略覆盖。您需要仔细检查org.springframework组下的所有依赖，特别是spring-core、spring-web、spring-webmvc等，看是否存在多个版本被引入。
使用Maven诊断
在项目根目录下执行以下命令：
mvn dependency:tree
Maven也会输出类似的依赖树，帮助您识别冲突。
通过分析依赖树，您会发现springdoc-openapi-ui（或其某个传递性依赖）引入了与您项目其他部分不一致的Spring Framework版本。例如，您的项目可能正在使用Spring 5.2.x，而springdoc-openapi-ui:1.5.2可能依赖Spring 5.3.x，或者更早的版本。
解决依赖冲突的策略
一旦确定了冲突的根源，就可以采取以下策略来解决：
1. 排除传递性依赖
这是最常见且推荐的方法。您可以显式地从springdoc-openapi-ui依赖中排除其传递性引入的Spring Framework组件，从而强制项目使用您自己定义的Spring Framework版本。
Gradle示例：
dependencies {
implementation 'org.springdoc:springdoc-openapi-ui:1.5.2' {
// 排除springdoc-openapi-ui引入的spring-webmvc及其相关依赖
exclude group: 'org.springframework', module: 'spring-webmvc'
exclude group: 'org.springframework', module: 'spring-web'
exclude group: 'org.springframework', module: 'spring-context'
// 根据实际冲突情况，可能需要排除更多spring组件
}
// 确保您的项目显式声明了所有Spring Framework依赖，并且版本一致
implementation 'org.springframework:spring-webmvc:5.2.x.RELEASE' // 替换为您的项目实际版本
implementation 'org.springframework:spring-context:5.2.x.RELEASE'
// ... 其他Spring Framework依赖
}Maven示例：
org.springdoc springdoc-openapi-ui 1.5.2 org.springframework spring-webmvc org.springframework spring-web org.springframework spring-context org.springframework spring-webmvc 5.2.x.RELEASE org.springframework spring-context 5.2.x.RELEASE
注意事项：
- 排除时需谨慎，只排除那些导致冲突的Spring Framework核心组件。
- 确保您的项目显式声明了所需的所有Spring Framework依赖，并保持版本一致性。
2. 统一Spring Framework版本
如果您的项目没有使用Spring Boot，而是纯粹的Spring Web MVC，那么统一所有Spring Framework依赖的版本至关重要。
Gradle示例：
ext {
springVersion = '5.2.x.RELEASE' // 替换为您项目实际使用的Spring版本
}
dependencies {
implementation "org.springframework:spring-core:$springVersion"
implementation "org.springframework:spring-web:$springVersion"
implementation "org.springframework:spring-webmvc:$springVersion"
implementation "org.springframework:spring-context:$springVersion"
// ... 其他Spring Framework依赖
implementation 'org.springdoc:springdoc-openapi-ui:1.5.2'
// 如果排除无效，可能需要尝试更高或更低的springdoc版本以匹配您的Spring版本
}Maven示例：
5.2.x.RELEASE org.springframework spring-framework-bom ${spring.version} pom import org.springframework spring-core org.springframework spring-webmvc org.springdoc springdoc-openapi-ui 1.5.2
使用spring-framework-bom可以确保所有Spring Framework组件都使用同一个版本。
3. 调整springdoc-openapi-ui版本
springdoc-openapi-ui的不同版本可能兼容不同范围的Spring Framework版本。如果排除和统一版本策略未能奏效，您可以尝试升级或降级springdoc-openapi-ui的版本，以找到一个与您项目当前Spring Framework版本兼容的版本。查阅springdoc-openapi-ui的官方文档或其GitHub仓库，了解其版本与Spring Framework版本的兼容性矩阵。
4. 强制依赖版本（不推荐，但有时有效）
在某些极端情况下，如果上述方法都无效，您可以通过构建工具强制指定某个依赖的版本。这种方法应谨慎使用，因为它可能引入其他不兼容性。
Gradle示例：
configurations.all {
resolutionStrategy {
// 强制使用特定版本的spring-webmvc
force 'org.springframework:spring-webmvc:5.2.x.RELEASE'
// 强制使用特定版本的spring-context
force 'org.springframework:spring-context:5.2.x.RELEASE'
// ...
}
}Maven示例：
org.springframework spring-webmvc 5.2.x.RELEASE compile
总结与最佳实践
解决springdoc-openapi-ui集成中出现的类找不到问题，核心在于管理好项目的依赖版本。当引入新库时，务必：
- 审查依赖树： 养成习惯，在添加新依赖后立即检查依赖树，以发现潜在的冲突。
- 优先排除： 首选通过排除传递性依赖来解决冲突，这能让您更好地控制项目使用的版本。
- 统一版本： 对于Spring Framework这样的核心库，确保所有相关组件都使用统一的版本，尤其是在非Spring Boot项目中，使用BOM（Bill of Materials）是最佳实践。
- 查阅文档： 了解所集成库（如springdoc-openapi-ui）与其核心依赖（如Spring Framework）之间的兼容性要求。
- 逐步测试： 每次修改依赖后，都应彻底清理构建缓存并重新构建项目，然后进行功能测试，确保没有引入新的问题。
通过上述方法，您可以有效地解决在Spring Web MVC项目中集成springdoc-openapi-ui时遇到的依赖冲突问题，从而顺利生成OpenAPI文档。
