Spring Boot自定义校验注解的错误处理与ProblemDetail集成问询

不必逐个处理异常：统一抽象错误提取逻辑 #

你完全不需要分别编写两个异常的处理方法，可以把两种校验异常的错误信息提取逻辑抽象出来，用一个全局异常处理器统一处理。

核心思路是：HandlerMethodValidationException（对应GET请求参数校验）和MethodArgumentNotValidException（对应POST/PUT请求体字段校验）都能提供校验错误的消息集合，我们只需要写一个通用方法提取这些消息，再统一封装成ProblemDetail。

示例代码：

@RestControllerAdvice
public class GlobalValidationExceptionHandler {

    private final ProblemDetailFactory problemDetailFactory;

    // 注入Spring原生的ProblemDetail工厂，统一响应结构规范
    public GlobalValidationExceptionHandler(ProblemDetailFactory problemDetailFactory) {
        this.problemDetailFactory = problemDetailFactory;
    }

    // 同时处理两种校验异常类型
    @ExceptionHandler({HandlerMethodValidationException.class, MethodArgumentNotValidException.class})
    public ProblemDetail handleValidationErrors(Exception ex) {
        String errorDetail = extractValidationMessage(ex);
        ProblemDetail problemDetail = problemDetailFactory.create(HttpStatus.BAD_REQUEST);
        problemDetail.setDetail(errorDetail);
        // 可按需添加固定标识字段，方便客户端识别错误类型
        problemDetail.setTitle("税号格式校验失败");
        problemDetail.setType(URI.create("/errors/invalid-fiscal-code"));
        return problemDetail;
    }

    // 抽象错误消息提取逻辑，后续新增异常类型只需扩展此处
    private String extractValidationMessage(Exception ex) {
        if (ex instanceof HandlerMethodValidationException paramEx) {
            return paramEx.getAllErrors().stream()
                    .map(ObjectError::getDefaultMessage)
                    .findFirst()
                    .orElse("请求参数校验失败");
        } else if (ex instanceof MethodArgumentNotValidException bodyEx) {
            return bodyEx.getBindingResult().getAllErrors().stream()
                    .map(ObjectError::getDefaultMessage)
                    .findFirst()
                    .orElse("请求体字段校验失败");
        }
        return "校验规则未通过";
    }
}

与约束管理集成：利用Spring扩展点实现深度解耦 #

如果想进一步和JSR-380约束管理体系集成，可以通过以下两种方式：

1. 扩展ErrorResponseExceptionHandler #

Spring的ErrorResponseExceptionHandler是处理所有标准错误响应的基础类，继承它并重写createProblemDetail方法，可统一覆盖所有校验异常的响应内容：

@RestControllerAdvice
public class CustomErrorResponseHandler extends ErrorResponseExceptionHandler {

    @Override
    protected ProblemDetail createProblemDetail(Exception ex, HttpHeaders headers, HttpStatusCode statusCode, String defaultDetail, Map<String, Object> body, WebRequest request) {
        ProblemDetail problemDetail = super.createProblemDetail(ex, headers, statusCode, defaultDetail, body, request);
        // 仅提取税号校验相关的错误消息，覆盖默认detail
        String customDetail = extractFiscalCodeValidationMessage(ex);
        if (customDetail != null) {
            problemDetail.setDetail(customDetail);
            problemDetail.setTitle("税号校验失败");
        }
        return problemDetail;
    }

    private String extractFiscalCodeValidationMessage(Exception ex) {
        // 过滤出税号自定义校验的错误消息
        if (ex instanceof HandlerMethodValidationException paramEx) {
            return paramEx.getAllErrors().stream()
                    .filter(error -> error.getCode().equals("FiscalCode"))
                    .map(ObjectError::getDefaultMessage)
                    .findFirst()
                    .orElse(null);
        } else if (ex instanceof MethodArgumentNotValidException bodyEx) {
            return bodyEx.getBindingResult().getAllErrors().stream()
                    .filter(error -> error.getCode().equals("FiscalCode"))
                    .map(ObjectError::getDefaultMessage)
                    .findFirst()
                    .orElse(null);
        }
        return null;
    }
}

这种方式可统一处理所有Spring抛出的错误异常，不仅限于校验场景，适合全局统一响应格式的需求。

2. 自定义ConstraintViolationException处理（适配Spring 5及以下） #

如果使用Spring 5版本，GET参数校验会抛出ConstraintViolationException，可以统一处理该异常和MethodArgumentNotValidException，复用相同的消息提取逻辑即可。

最佳实践总结 #

1. 抽象核心逻辑：把错误消息提取、ProblemDetail封装的核心逻辑抽离成工具方法或类，避免重复代码，降低维护成本。
2. 依赖Spring原生组件：优先使用Spring提供的ProblemDetailFactory、ErrorResponseExceptionHandler等扩展点，不要自定义拦截器或过滤器处理校验异常，避免破坏Spring的校验生命周期。
3. 统一响应元数据：除了detail字段，建议固定title、type等元数据字段，让客户端能快速识别错误类型（比如税号校验错误的type设为固定URI）。
4. 动态消息与国际化：如果需要多语言支持，在FiscalCodeValidator中通过MessageSource获取本地化消息，异常处理时直接复用这些消息，避免硬编码。
5. 日志辅助排查：在异常处理方法中记录校验失败的上下文信息（如字段值、错误代码），便于后续问题排查。

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