Spring Boot 2.7 STOMP WebSocket配置遇ClassNotFoundException异常

启动基于Java 17、Gradle构建的Spring Boot 2.7 STOMP WebSocket应用时，出现如下异常：

Caused by: java.lang.ClassNotFoundException: org.springframework.beans.factory.annotation.RequiredAnnotationBeanPostProcessor
at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:641) ~[na:na]
at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:188) ~[na:na]
at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:520) ~[na:na]
... 16 common frames omitted

相关代码 #

WebSocket配置类 #

@EnableWebSocketMessageBroker
@Configuration
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

  @Override
  public void configureMessageBroker(MessageBrokerRegistry config) {
    config.enableSimpleBroker("/user");
    config.setApplicationDestinationPrefixes("/app");
    config.setUserDestinationPrefix("/user");
  }

  @Override
  public void registerStompEndpoints(StompEndpointRegistry registry) {
    registry.addEndpoint("/ws").setAllowedOrigins("*").withSockJS();
    registry.addEndpoint("/ws");
  }

  @Override
  public boolean configureMessageConverters(List<MessageConverter> messageConverters) {
    DefaultContentTypeResolver resolver = new DefaultContentTypeResolver();
    resolver.setDefaultMimeType(MimeTypeUtils.APPLICATION_JSON);
    MappingJackson2MessageConverter converter = new MappingJackson2MessageConverter();
    converter.setObjectMapper(new ObjectMapper());
    converter.setContentTypeResolver(resolver);
    messageConverters.add(converter);
    return false;
  }
}

主启动类 #

@SpringBootApplication
public class ClientPortalApplication {

  public static void main(String[] args) {
    SpringApplication.run(ClientPortalApplication.class, args);
  }

}

Gradle依赖配置 #

plugins {
    java
    application
    `maven-publish`
    id("org.springframework.boot")
}

dependencies {
    implementation(project(":commons"))
    implementation("org.springframework.boot:spring-boot-starter-web:2.7.5")
    implementation("dev.morphia.morphia:core:1.6.1")
    implementation("org.springframework.boot:spring-boot-starter-data-mongodb-reactive:2.7.5")
    implementation("org.mongodb:mongodb-driver-sync:4.6.1")
    implementation("org.springframework.boot:spring-boot-starter-oauth2-client:2.7.5")
    implementation("org.springframework.boot:spring-boot-starter-thymeleaf:2.7.5")
    implementation("org.thymeleaf.extras:thymeleaf-extras-springsecurity5:3.0.4.RELEASE")
    implementation("commons-beanutils:commons-beanutils:1.9.4")
    implementation("com.stripe:stripe-java:21.5.0")
    implementation("org.apache.commons:commons-lang3:3.12.0")
    implementation("org.springframework.boot:spring-boot-starter-security:2.7.5")
    implementation("org.springframework.boot:spring-boot-starter-actuator:2.7.5")
    implementation("com.mashape.unirest:unirest-java:1.4.9")
    compileOnly("org.projectlombok:lombok:1.18.24")
    annotationProcessor("org.projectlombok:lombok:1.18.24")
    implementation("org.springframework.boot:spring-boot-starter-websocket:2.7.0")
    testImplementation("junit:junit:4.13.2")
}

group = "com.project"
version = "0.0.1-SNAPSHOT"
description = "service"
java.sourceCompatibility = JavaVersion.VERSION_17

publishing {
    publications.create<MavenPublication>("maven") {
        from(components["java"])
    }
}

tasks.withType<JavaCompile>() {
    options.encoding = "UTF-8"
}

application {
    mainClass.set("com.project.clientportal.ClientPortalApplication")
}

问题原因及解决办法 #

核心原因 #

org.springframework.beans.factory.annotation.RequiredAnnotationBeanPostProcessor在Spring Framework 5.1+已被标记为废弃，Spring Boot 2.7依赖的Spring Framework版本中已完全移除该类。异常出现的关键原因是：

1. Spring Boot Starter版本不统一：大部分starter用2.7.5，但websocket starter用2.7.0，导致依赖冲突。
2. 老旧依赖引入无效API：commons-beanutils:1.9.4版本过旧，内部依赖了Spring旧API，间接引用了已被移除的类。

修复步骤 #

1. 统一Spring Boot版本：将websocket starter的版本改为2.7.5，与其他starter保持一致：

   implementation("org.springframework.boot:spring-boot-starter-websocket:2.7.5")
   

2. 处理老旧依赖：升级commons-beanutils至最新兼容版本，或直接移除该依赖（若业务逻辑允许）。
3. 清理依赖缓存：执行Gradle命令清理缓存并重新构建：

   ./gradlew clean build --refresh-dependencies
   

验证 #

修改完成后重新启动应用，ClassNotFoundException异常即可消除。

内容的提问来源于stack exchange，提问作者Amit Pal