迁移至SpringBoot 3.0.4后WebFlux应用无法启动问题求助

问题描述 #

将应用迁移至spring-boot-starter-webflux 3.0.3及3.0.4版本后，启动时抛出异常无法启动响应式Web服务器，核心错误栈如下：

Caused by: java.lang.NoSuchFieldError: DECODE_SLASH
    at org.springframework.boot.autoconfigure.web.embedded.UndertowWebServerFactoryCustomizer.mapSlashProperties(UndertowWebServerFactoryCustomizer.java:121)

此前使用3.0.2版本时应用可正常运行，Gradle核心依赖配置如下：

ext {
    mockServerVersion = '5.15.0'
    springBootVersion = '3.0.4'
    junitJupiterVersion = '5.9.2'
    projectreactorVersion = '3.5.3'
    reactorKotlinVersion = '1.2.1'
    junitJupiterVersion = '5.9.2'
}

dependencies {
    implementation group: 'org.springframework.boot', name: 'spring-boot-starter-actuator', version: springBootVersion
    implementation group: 'org.springframework.boot', name: 'spring-boot-starter-validation', version: springBootVersion
    implementation group: 'org.springframework.boot', name: 'spring-boot-starter-webflux', version: springBootVersion
    implementation group: 'io.micrometer', name: 'micrometer-tracing-bridge-brave', version: '1.0.2'
    implementation group: 'org.jetbrains.kotlin', name: 'kotlin-reflect', version: kotlinVersion
    implementation group: 'io.projectreactor.kotlin', name: 'reactor-kotlin-extensions', version: reactorKotlinVersion
    implementation group: 'io.springfox', name: 'springfox-boot-starter', version: swaggerSpringfoxVersion
    implementation group: 'io.projectreactor', name: 'reactor-tools', version: projectreactorVersion

    testImplementation group: 'org.springframework.boot', name: 'spring-boot-starter-test', version: springBootVersion
    testImplementation group: 'org.junit.jupiter', name: 'junit-jupiter-params', version: junitJupiterVersion
    testImplementation group: 'org.mock-server', name: 'mockserver-spring-test-listener', version: mockServerVersion
    testImplementation group: 'io.mockk', name: 'mockk', version: mockkVersion
    testRuntimeOnly group: 'org.junit.jupiter', name: 'junit-jupiter-engine', version: junitJupiterVersion
    testImplementation group: 'io.projectreactor', name: 'reactor-test', version: projectreactorVersion
    testImplementation group: 'org.awaitility', name: 'awaitility', version: awaitilityVersion
}

问题根源 #

这个错误是因为Undertow版本与Spring Boot 3.0.3/3.0.4不兼容：Spring Boot 3.0.3开始升级了Undertow依赖版本，旧版本Undertow中的DECODE_SLASH字段已被移除或调整，但项目依赖中混入了旧版本的Undertow（大概率是第三方依赖如Springfox引入），导致自动配置类找不到该字段。

解决方案 #

方案1：强制统一Undertow版本 #

在Gradle配置中添加依赖强制规则，指定与Spring Boot 3.0.4匹配的Undertow版本（Spring Boot 3.0.4对应的Undertow版本为2.2.24.Final）：

configurations.all {
    resolutionStrategy.force 'io.undertow:undertow-core:2.2.24.Final'
    resolutionStrategy.force 'io.undertow:undertow-servlet:2.2.24.Final'
}

方案2：排除冲突的Undertow依赖 #

1. 执行gradle dependencies查看项目依赖树，定位引入旧版本Undertow的第三方依赖（例如Springfox）。
2. 在对应依赖中排除Undertow相关模块：

implementation group: 'io.springfox', name: 'springfox-boot-starter', version: swaggerSpringfoxVersion, {
    exclude group: 'io.undertow'
}

方案3：改用WebFlux默认的Netty服务器 #

如果不需要Undertow服务器，直接排除Undertow依赖，让WebFlux使用默认的Netty：

implementation group: 'org.springframework.boot', name: 'spring-boot-starter-webflux', version: springBootVersion, {
    exclude group: 'io.undertow'
}

内容的提问来源于stack exchange，提问作者Michał Sikora