SpringBoot Controller如何解决请求参数校验后统一返回自定义错误信息？

Question

在SpringBoot项目中，如何通过@ControllerAdvice和@ExceptionHandler实现请求参数校验失败后统一返回自定义错误信息？当Controller接收到非法参数时，系统默认会抛出MethodArgumentNotValidException异常。此时，如何捕获该异常并以统一的JSON格式（如{code:xxx, message:xxx}）返回给前端，同时确保不同环境（开发、测试、生产）下返回信息的安全性和可读性？此外，如何结合BindingResult动态定制错误提示内容，避免直接暴露框架内部信息？

Answer 1

1. 初步理解@ControllerAdvice和@ExceptionHandler

在Spring Boot项目中，异常处理是一个非常重要的功能。通过@ControllerAdvice注解，我们可以定义一个全局的异常处理器，用于捕获所有Controller层抛出的异常。而@ExceptionHandler注解则可以针对特定类型的异常进行处理。

例如，当请求参数校验失败时，系统会自动抛出MethodArgumentNotValidException异常。我们可以通过结合这两个注解，实现对这种异常的统一处理，并返回自定义的JSON格式响应。

示例代码：

    @ControllerAdvice
    public class GlobalExceptionHandler {

        @ExceptionHandler(MethodArgumentNotValidException.class)
        public ResponseEntity<ErrorResponse> handleValidationExceptions(MethodArgumentNotValidException ex) {
            ErrorResponse errorResponse = new ErrorResponse();
            errorResponse.setCode("400");
            errorResponse.setMessage("Invalid request parameters.");
            return new ResponseEntity<>(errorResponse, HttpStatus.BAD_REQUEST);
        }
    }
    

2. 深入分析：如何动态定制错误提示内容

在实际项目中，仅仅返回固定的错误信息是不够的。我们通常需要根据具体的错误字段和原因，动态生成更详细的错误提示。这可以通过BindingResult对象来实现，它包含了所有的校验错误信息。

以下是具体步骤：

1. 捕获MethodArgumentNotValidException异常。
2. 从异常对象中提取BindingResult实例。
3. 遍历BindingResult中的FieldError列表，构建详细的错误描述。

改进后的代码：

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationExceptions(MethodArgumentNotValidException ex) {
        BindingResult bindingResult = ex.getBindingResult();
        List<String> errors = bindingResult.getFieldErrors().stream()
                .map(fieldError -> fieldError.getField() + ": " + fieldError.getDefaultMessage())
                .collect(Collectors.toList());
        
        ErrorResponse errorResponse = new ErrorResponse();
        errorResponse.setCode("400");
        errorResponse.setMessage(String.join(", ", errors));
        return new ResponseEntity<>(errorResponse, HttpStatus.BAD_REQUEST);
    }
    

3. 环境差异化处理

不同环境（如开发、测试、生产）下，错误信息的安全性和可读性要求不同。开发环境下，可以返回详细的错误堆栈信息；而在生产环境下，则应避免暴露过多的内部细节，仅返回友好的错误提示。

为实现这一点，可以通过Spring Profiles机制，根据不同环境加载不同的配置文件。

环境	错误信息内容
开发	详细错误信息及堆栈跟踪
测试	简化版错误信息
生产	用户友好的错误提示

4. 流程图：异常处理流程

sequenceDiagram
            participant Controller
            participant ExceptionHandler
            participant Response
            Controller->>ExceptionHandler: Throw MethodArgumentNotValidException
            ExceptionHandler->>ExceptionHandler: Extract BindingResult
            ExceptionHandler->>ExceptionHandler: Build Custom Error Message
            ExceptionHandler->>Response: Return JSON Response