SpringBoot 3 WebFlux中ErrorWebExceptionHandler失效问题求助

SpringBoot 3（基于Spring 6）对WebFlux的异常处理链路做了调整，导致原来SpringBoot 2下的ErrorWebExceptionHandler实现迁移后失效，核心原因和修复方案如下：

核心问题点 #

1. 默认异常处理器优先级变更：SpringBoot 3中DefaultErrorWebExceptionHandler的@Order改为-1，虽然你的处理器@Order(-2)优先级更高，但未正确处理响应状态、响应头及响应完成逻辑，导致默认逻辑仍会介入。
2. 响应未正确标记为已处理：原代码仅写入响应体，但未设置状态码、ContentType，也未确保响应流完成，Spring会认为响应未处理，触发默认异常流程。

修复后的完整代码 #

@Component
@Order(-2) // 优先级高于默认的DefaultErrorWebExceptionHandler(-1)
class RestExceptionHandler(private val objectMapper: ObjectMapper) : ErrorWebExceptionHandler {

    private val log = logger()

    override fun handle(exchange: ServerWebExchange, ex: Throwable): Mono<Void> {
        // 解析异常，生成错误码和消息（根据你的业务逻辑调整）
        val (errorCode, errorMsg) = when (ex) {
            is IllegalArgumentException -> 400 to "参数非法：${ex.message ?: "未提供具体原因"}"
            is NullPointerException -> 500 to "空指针异常：${ex.message ?: "未提供具体原因"}"
            else -> 500 to "服务器内部错误"
        }

        // 设置响应状态码
        exchange.response.statusCode = HttpStatus.valueOf(errorCode)
        // 设置响应内容类型为JSON
        exchange.response.headers.contentType = MediaType.APPLICATION_JSON

        // 序列化错误响应体
        val errorItem = ErrorItem(errorCode, errorMsg)
        val responseBytes = objectMapper.writeValueAsBytes(errorItem)

        // 写入响应并确保流完成
        return exchange.response.writeWith(
            Mono.just(exchange.response.bufferFactory().wrap(responseBytes))
        ).doOnError { log.error("写入错误响应失败", it) }
            .then() // 标记响应处理完成
    }
}

// 你的错误响应DTO
data class ErrorItem(val code: Int, val message: String)

关键调整说明 #

• 强制设置响应状态和ContentType：明确告诉Spring响应已按业务逻辑处理，避免默认异常处理器覆盖结果。
• 确保响应流完成：通过then()方法确保响应写入后完成整个请求链路，防止请求挂起或后续逻辑介入。
• 异常解析逻辑显性化：把异常判断逻辑抽出来，便于后续扩展不同异常的处理规则。
• 增加错误日志：捕获响应写入时的异常，方便排查问题。

可选优化方案（函数式风格） #

如果更倾向于WebFlux的函数式编程风格，可以用ServerResponse构建响应：

@Component
@Order(-2)
class RestExceptionHandler(private val objectMapper: ObjectMapper) : ErrorWebExceptionHandler {

    private val log = logger()

    override fun handle(exchange: ServerWebExchange, ex: Throwable): Mono<Void> {
        val (errorCode, errorMsg) = resolveErrorInfo(ex)
        val status = HttpStatus.valueOf(errorCode)
        val errorItem = ErrorItem(errorCode, errorMsg)

        return ServerResponse.status(status)
            .contentType(MediaType.APPLICATION_JSON)
            .bodyValue(objectMapper.writeValueAsString(errorItem))
            .flatMap { it.writeTo(exchange, EmptyServerResponseContext()) }
    }

    private fun resolveErrorInfo(ex: Throwable): Pair<Int, String> {
        // 这里统一处理异常解析逻辑
        return when (ex) {
            is IllegalArgumentException -> 400 to "参数错误：${ex.message ?: ""}"
            is RuntimeException -> 500 to "服务异常：${ex.message ?: ""}"
            else -> 500 to "未知错误"
        }
    }
}

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