Spring Boot 3 WebFlux中如何启用RFC 7807错误响应格式？

一、spring.webflux.problemdetails.enabled 的实际作用 #

这个配置项确实用于开启 RFC 7807 格式支持，但作用范围仅限控制器处理流程内抛出的异常：

• 当请求进入@Controller/@RestController方法后抛出的异常（比如自定义业务异常、方法内参数校验失败抛出的异常），开启该属性后会被Spring自动配置的ProblemDetailsExceptionHandler捕获，返回标准RFC 7807格式响应。
• 对于网关层的全局未捕获异常（比如404路径不存在、405请求方法不匹配、全局参数校验未通过且未进入控制器方法等），该配置项不会生效——这类错误默认由DefaultErrorWebExceptionHandler处理，依然返回非RFC 7807格式的响应，这就是你配置后看不到效果的核心原因。

二、WebFlux 应用配置 RFC 7807 错误响应的正确方式 #

要让所有错误场景都返回RFC 7807格式，需要根据不同场景组合配置或自定义处理逻辑：

1. 覆盖控制器内异常（简易配置） #

直接开启配置即可：

spring.webflux.problemdetails.enabled=true

该方式无需额外代码，自动处理控制器方法内抛出的异常，返回标准RFC 7807响应。

2. 覆盖所有错误场景（包括网关层） #

仅靠配置无法覆盖全部场景，推荐两种方案：

方案一：使用 @RestControllerAdvice 继承 ResponseEntityExceptionHandler

这就是你测试有效的方案，它能覆盖绝大多数常见异常（包括网关层的HttpRequestMethodNotSupportedException、MethodArgumentNotValidException等），统一返回RFC 7807格式。示例代码：

@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

    // 如需自定义特定异常处理，可重写父类方法
    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(MethodArgumentNotValidException ex,
                                                                  HttpHeaders headers,
                                                                  HttpStatusCode status,
                                                                  WebRequest request) {
        ProblemDetails problemDetails = ProblemDetails.forStatus(status);
        problemDetails.setTitle("参数校验失败");
        problemDetails.setDetail(ex.getBindingResult().getFieldError().getDefaultMessage());
        problemDetails.setInstance(request.getDescription(false));
        return new ResponseEntity<>(problemDetails, headers, status);
    }
}

该方案的优势是无需替换全局错误处理器，Spring会自动将符合条件的异常委托给这个类处理。

方案二：自定义 ErrorWebExceptionHandler 替换默认实现

如果你不想使用Controller Advice，可以自定义全局错误处理器，直接替换DefaultErrorWebExceptionHandler，让所有错误都返回RFC 7807格式：

@Component
public class Rfc7807GlobalErrorHandler extends AbstractErrorWebExceptionHandler {

    public Rfc7807GlobalErrorHandler(ErrorAttributes errorAttributes,
                                     WebProperties.Resources resources,
                                     ApplicationContext applicationContext,
                                     ServerCodecConfigurer codecConfigurer) {
        super(errorAttributes, resources, applicationContext);
        setMessageWriters(codecConfigurer.getWriters());
        setMessageReaders(codecConfigurer.getReaders());
    }

    @Override
    protected RouterFunction<ServerResponse> getRoutingFunction(ErrorAttributes errorAttributes) {
        return RouterFunctions.route(RequestPredicates.all(), this::buildRfc7807Response);
    }

    private Mono<ServerResponse> buildRfc7807Response(ServerRequest request) {
        Map<String, Object> errorAttrs = getErrorAttributes(request, ErrorAttributeOptions.defaults());
        HttpStatus status = HttpStatus.valueOf((Integer) errorAttrs.get("status"));
        
        ProblemDetails problemDetails = ProblemDetails.forStatusAndDetail(status, 
                (String) errorAttrs.get("message"));
        problemDetails.setTitle((String) errorAttrs.get("error"));
        problemDetails.setInstance(request.path());
        
        return ServerResponse.status(status)
                .contentType(MediaType.APPLICATION_PROBLEM_JSON)
                .bodyValue(problemDetails);
    }
}

该方案会接管所有全局未捕获异常的处理，统一输出RFC 7807格式响应。

总结 #

• spring.webflux.problemdetails.enabled仅负责控制器内异常的自动处理，无法覆盖网关层全局错误；
• 要实现全场景的RFC 7807响应，最简便的方式是使用继承ResponseEntityExceptionHandler的@RestControllerAdvice；
• 若需完全自定义全局错误逻辑，可替换默认的ErrorWebExceptionHandler。

内容的提问来源于stack exchange，提问作者Johan Sjöberg