Spring WebFlux 如何处理返回 Mono 的控制器方法？

spring webflux 在控制器方法返回 mono 后，并不会立即执行其内部逻辑，而是将 mono 交由 webflux 基础设施在请求生命周期的后续阶段（如响应写入前）自动订阅；此时真正的异步链才被触发，因此手动调用 `.tofuture().get()` 会因未订阅而返回 null。

在 Spring WebFlux 中，控制器方法返回 Mono 或 Flux 并非表示“立刻获取值”，而是一种声明式契约：你承诺将在某个时刻（通常是响应准备就绪时）提供一个 T 类型的值（或完成信号）。整个响应流程基于 Reactor 的背压与惰性执行模型——所有操作符（如 map、filter、doOnNext）仅在订阅发生后才逐级触发。

以你的示例为例：

@GetMapping("/test")
public Mono test() {
    Mono mono = ReactiveSecurityContextHolder.getContext()
        .map(ctx -> (Jwt) ctx.getAuthentication().getPrincipal());

    // ❌ 错误：强制提前阻塞订阅，但此时 Mono 尚未被 WebFlux 订阅
    Jwt jwtFromMono = mono.toFuture().get(); // 可能为 null 或抛出异常（如 TimeoutException）
    System.out.println("jwt value is " + jwtFromMono); // 输出 null

    return mono; // ✅ 正确：返回未订阅的 Mono，交由 WebFlux 处理
}

此处 mono.toFuture().get() 失败的根本原因在于：

• ReactiveSecurityContextHolder.getContext() 返回的是一个依赖于当前线程绑定的 Mono；
• 在 WebFlux 的非阻塞线程模型中，该上下文仅在 WebFlux 的请求处理线程（如 event loop 线程）中有效且可访问；
• 而 .toFuture().get() 是同步阻塞调用，可能在任意线程（甚至主线程）执行，此时 SecurityContext 尚未传播或已失效，导致 getPrincipal() 返回 null。

✅ 正确做法是完全拥抱响应式编程范式，将副作用（如日志、转换、校验）嵌入到响应式链中：

@GetMapping("/test")
public Mono test() {
    return ReactiveSecurityContextHolder.getContext()
        .switchIfEmpty(Mono.error(new IllegalStateException("Security context is empty")))
        .map(ctx -> {
            Authentication auth = ctx.getAuthentication();
            Object principal = auth != null ? auth.getPrincipal() : null;
            if (!(principal instanceof Jwt)) {
                throw new IllegalArgumentException("Expected Jwt principal, got: " + principal);
            }
            return (Jwt) principal;
        })
        .doOnNext(jwt -> System.out.println("✅ JWT received: " + jwt.getTokenValue()))
        .doOnError(error -> System.err.println("❌ JWT resolution failed: " + error.getMessage()));
}

? WebFlux 背后的关键机制包括：

• 自动订阅：DispatcherHandler 在写出响应体前，对返回的 Mono 调用 subscribe()；
• 线程上下文传播：ReactorContext 与 SecurityContext 通过 Context 与 Hooks 在订阅链中透明传递；
• 错误统一处理：未捕获异常会自动转为 HTTP 500 响应（可通过 @ControllerAdvice 自定义）；
• 序列化委托：最终值交由 HttpMessageWriter（如 Jackson2JsonEncoder）序列化为 JSON。

⚠️ 注意事项：

• 切勿在 WebFlux 控制器中调用 .block()、.toFuture().get() 或其他阻塞 API——这会破坏响应式优势，导致线程饥饿与性能坍塌；
• 若需调试流中值，优先使用 doOnNext()、doOnSubscribe()、log() 等非阻塞钩子；
• 安全上下文访问必须在 Mono 链内完成，不可脱离响应式流提取原始值。

总之，Spring WebFlux 的“幕后工作”本质是：延迟订阅 + 上下文感知执行 + 声明式错误传播。开发者只需返回纯净的 Mono/Flux，其余均由框架在恰当的时机、线程和上下文中安全完成。