升级Spring Boot至WebFlux后控制器获取Mono<Principal>失败排查

我来帮你捋捋这个问题——你碰到的Failed to obtain Mono<Principal>异常，本质是Spring WebFlux的安全上下文里没正确初始化认证信息的传递，导致控制器没法正常注入Mono<Principal>。结合你用@SpringBootApplication替代手动创建Netty的场景，大概率是这几个环节没做好：

1. 确认Reactive Spring Security依赖是否正确引入 #

如果是从传统Servlet版Spring Boot升级到WebFlux，很容易残留Servlet版的Security依赖，导致上下文冲突。你需要确保依赖清单里是WebFlux+Reactive Security的组合：

Maven 配置示例：

<!-- WebFlux核心依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
<!-- Reactive Security依赖（Spring Boot会自动关联spring-security-webflux） -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

如果之前有Servlet版Security的残留，记得排除掉：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.security</groupId>
            <artifactId>spring-security-web</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Gradle 配置示例：

implementation 'org.springframework.boot:spring-boot-starter-webflux'
implementation 'org.springframework.boot:spring-boot-starter-security'

2. 必须配置Reactive Security上下文 #

WebFlux的Security配置和Servlet版完全不同，你需要通过@EnableWebFluxSecurity和SecurityWebFilterChain来初始化安全上下文——这是让Mono<Principal>能被正确注入的核心。

写一个最基础的配置类测试：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.reactive.EnableWebFluxSecurity;
import org.springframework.security.config.web.server.ServerHttpSecurity;
import org.springframework.security.web.server.SecurityWebFilterChain;

@Configuration
@EnableWebFluxSecurity // 关键：启用WebFlux专属的安全机制
public class ReactiveSecurityConfig {

    @Bean
    public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
        return http
                .authorizeExchange(exchanges -> exchanges
                        .anyExchange().authenticated() // 所有请求需要认证，也可以放开特定路径
                )
                .httpBasic() // 启用基础认证，方便快速测试
                .and()
                .build();
    }
}

如果没有这个配置，Spring Security的Reactive上下文不会初始化，自然没法传递认证信息到控制器。

3. 检查控制器方法的参数声明 #

WebFlux是异步非阻塞环境，不能直接注入Principal对象，必须用Mono<Principal>来包装。确保你的控制器写法是正确的：

@RestController
public class TestController {

    // 正确写法：用Mono<Principal>接收认证信息
    @GetMapping("/api/hello")
    public Mono<String> hello(Mono<Principal> principalMono) {
        return principalMono
                .map(Principal::getName)
                .map(name -> "Hello, authenticated user: " + name);
    }
}

如果写成Principal principal，Spring会尝试同步实例化这个对象，但Reactive环境下没有同步的认证上下文，就会抛出你看到的“Failed to instantiate Mono”异常。

4. 排除Servlet相关的自动配置（可选但重要） #

如果是从Servlet项目升级而来，Spring Boot可能默认启用了Servlet的自动配置，导致Servlet和WebFlux上下文混合冲突。可以在@SpringBootApplication上排除这些配置：

@SpringBootApplication(exclude = {
        ServletWebServerFactoryAutoConfiguration.class,
        SpringMvcAutoConfiguration.class
})
public class WebFluxUpgradeApplication {
    public static void main(String[] args) {
        SpringApplication.run(WebFluxUpgradeApplication.class, args);
    }
}

这能确保应用完全运行在Reactive的WebFlux环境中，避免上下文混乱。

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