如何用@ControllerAdvice处理请求参数中的无效枚举值问题

问题原因 #

当请求传入无效枚举值时，Spring MVC在参数绑定阶段会抛出IllegalArgumentException，但由于你的Filter类使用了@Builder，或者Spring默认的异常处理逻辑未将该异常传递到全局处理器，导致异常被静默处理，接口返回空响应且无法被@ControllerAdvice捕获。

解决方案 #

方法一：自定义枚举转换器，主动抛出可捕获的异常 #

通过自定义字符串到枚举的转换器，在转换失败时抛出自定义异常，让@ControllerAdvice可以直接捕获并处理。

1. 定义自定义异常

public class InvalidEnumValueException extends RuntimeException {
    public InvalidEnumValueException(String message) {
        super(message);
    }
}

2. 实现枚举转换器

@Component
public class TypeEnumConverter implements Converter<String, Type> {
    @Override
    public Type convert(String source) {
        try {
            // 根据实际枚举的命名规则调整（比如大小写）
            return Type.valueOf(source.trim().toUpperCase());
        } catch (IllegalArgumentException e) {
            String allowedValues = Arrays.toString(Type.values());
            throw new InvalidEnumValueException("无效的枚举值: " + source + "，允许的值为: " + allowedValues);
        }
    }
}

3. 注册转换器（可选，Spring Boot中@Component会自动注册）
   如果需要手动配置，可添加WebMvc配置类：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(new TypeEnumConverter());
    }
}

4. 在@ControllerAdvice中捕获异常

@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(InvalidEnumValueException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ResponseBody
    public Map<String, Object> handleInvalidEnumException(InvalidEnumValueException e) {
        Map<String, Object> response = new HashMap<>();
        response.put("code", HttpStatus.BAD_REQUEST.value());
        response.put("message", e.getMessage());
        return response;
    }
}

方法二：直接捕获Spring内置的类型不匹配异常 #

Spring在枚举转换失败时，也会抛出MethodArgumentTypeMismatchException，可以直接在全局处理器中捕获该异常并处理枚举场景：

@ControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ResponseBody
    public Map<String, Object> handleTypeMismatchException(MethodArgumentTypeMismatchException e) {
        Map<String, Object> response = new HashMap<>();
        // 判断是否为枚举类型转换失败
        if (e.getRequiredType() != null && e.getRequiredType().isEnum()) {
            String allowedValues = Arrays.toString(e.getRequiredType().getEnumConstants());
            response.put("code", HttpStatus.BAD_REQUEST.value());
            response.put("message", String.format("无效的参数值: %s，允许的值为: %s", e.getValue(), allowedValues));
        } else {
            response.put("code", HttpStatus.BAD_REQUEST.value());
            response.put("message", "参数类型不匹配");
        }
        return response;
    }
}

注意事项 #

• 如果Filter类使用@Builder，确保Spring MVC可以正确通过Builder实例化对象（Spring Boot 2.x+默认支持@Builder类的参数绑定）。
• 自定义转换器时，要匹配枚举的实际命名规则（比如枚举值是大写还是小写），避免不必要的转换失败。

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