定制Spring Bean Validation错误处理以隐藏敏感拒绝值

问题背景与挑战

在使用spring框架进行web开发时，我们经常利用bean validation（如@valid或@validated）对请求体（request body）或请求参数进行数据校验。当验证失败时，spring默认会生成包含详细错误信息的响应，有时甚至会在日志或响应体中直接暴露“rejected value”（被拒绝的值）。例如，日志中可能会出现类似 [field error in object 'customer' on field 'firstname': rejected value [robert% steve]; 的信息。

这种行为在处理包含个人身份信息（PII）或其他敏感数据的场景下，构成了严重的安全隐患。例如，如果用户输入了包含特殊字符的PII数据，这些数据可能会未经处理地显示在错误信息中，从而导致数据泄露。

尽管开发者通常会尝试使用@ControllerAdvice结合MethodArgumentNotValidException来定制全局异常处理，以提供统一且不暴露敏感数据的错误消息，但在某些情况下，这种方法可能未能如预期般生效。这使得寻找一种可靠的机制来阻止或掩盖这些“拒绝值”成为一个迫切的需求。

根本原因分析

为什么自定义的@ControllerAdvice有时无法捕获MethodArgumentNotValidException并定制其错误消息呢？

Spring框架提供了一个强大的异常处理机制。对于常见的Spring MVC异常，Spring已经提供了一个基础的异常处理器：ResponseEntityExceptionHandler。这个类预设了对多种特定异常的处理逻辑，其中包括MethodArgumentNotValidException。ResponseEntityExceptionHandler内部的handleMethodArgumentNotValid()方法专门用于处理由Bean Validation失败引起的此异常。

当Spring检测到MethodArgumentNotValidException时，它会优先查找并执行最具体的异常处理器。由于ResponseEntityExceptionHandler已经提供了一个针对该异常的默认处理方法，如果你的自定义@ControllerAdvice没有明确地覆盖或比它更具体地处理此异常，那么ResponseEntityExceptionHandler中的默认逻辑就会被执行，导致你的自定义逻辑未能生效。

简而言之，ResponseEntityExceptionHandler充当了一个“默认”的兜底处理器，它比你简单的@ExceptionHandler(MethodArgumentNotValidException.class)方法具有更高的优先级或更早的执行时机，从而拦截了异常。

Figma

Figma 是一款基于云端的 UI 设计工具，可以在线进行产品原型、设计、评审、交付等工作。

下载

解决方案：覆盖默认异常处理

要彻底解决这个问题，并完全控制MethodArgumentNotValidException的错误响应，最可靠的方法是扩展Spring提供的ResponseEntityExceptionHandler，并重写其handleMethodArgumentNotValid()方法。通过这种方式，我们可以替换Spring的默认处理逻辑，插入我们自己的定制化错误响应，从而避免敏感数据泄露。

核心思路：

1. 创建一个新的异常处理类，并使用@RestControllerAdvice注解标记它。
2. 让这个类继承ResponseEntityExceptionHandler。
3. 重写protected ResponseEntity
4. 在该方法内部，构建一个自定义的错误响应，该响应不包含任何敏感的“拒绝值”。

示例代码与解析

以下是实现此解决方案的示例代码：

import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

import java.util.Map;

@RestControllerAdvice
public class CustomValidationExceptionHandler extends ResponseEntityExceptionHandler {

    /**
     * 重写 handleMethodArgumentNotValid 方法，处理请求参数验证失败的异常。
     * 目的：阻止敏感的“rejected value”暴露在错误响应中。
     *
     * @param ex      MethodArgumentNotValidException 异常实例
     * @param headers HTTP 头
     * @param status  HTTP 状态码
     * @param request 当前的 Web 请求
     * @return 包含自定义错误信息的 ResponseEntity
     */
    @Override
    protected ResponseEntity