ControllerAdvice未捕获UUID解析抛出的IllegalArgumentException问题排查

我来帮你梳理清楚这个问题的核心原因：

当你向/v1/highlights传入无效UUID字符串时，Spring并不会直接抛出你预期的IllegalArgumentException，实际的执行流程是这样的：

1. StringToUUIDConverter尝试转换无效字符串时，确实会抛出IllegalArgumentException；
2. 但Spring的参数绑定机制会把这个底层异常包装成MethodArgumentTypeMismatchException——这是Spring自己定义的、用于表示请求参数类型不匹配的异常，它属于RuntimeException的子类；
3. 因为你的全局异常处理器中，handleRuntimeException方法负责捕获所有RuntimeException及其子类，而MethodArgumentTypeMismatchException没有被专门的处理器匹配，所以就被这个兜底的处理器接手了。

验证方式 #

你可以临时在handleRuntimeException方法里加一行日志，打印异常的实际类型：

log.error("Handled: Runtime exception, actual type: {}", ex.getClass().getName(), ex);

运行后你会看到输出的是org.springframework.web.method.annotation.MethodArgumentTypeMismatchException，而不是java.lang.IllegalArgumentException。

解决办法 #

你有两种常见的修复方式：

1. 专门处理MethodArgumentTypeMismatchException

添加一个针对该异常的处理器方法，在里面判断底层原因是否是UUID转换失败的IllegalArgumentException，然后返回对应的错误响应：

@ExceptionHandler(value = MethodArgumentTypeMismatchException.class)
public ResponseEntity<Object> handleMethodArgumentTypeMismatch(MethodArgumentTypeMismatchException ex) {
    log.info("Handled: MethodArgumentTypeMismatchException", ex);
    Throwable rootCause = ex.getCause();
    
    // 针对UUID转换失败的情况做特殊处理
    if (rootCause instanceof IllegalArgumentException && 
        UUID.class.isAssignableFrom(ex.getRequiredType())) {
        return buildResponseEntity(new ApiErrorResponse(
                HttpStatus.BAD_REQUEST,
                "Incorrect Request: Invalid UUID format",
                rootCause
        ));
    }
    
    // 处理其他类型的参数类型不匹配问题
    return buildResponseEntity(new ApiErrorResponse(
            HttpStatus.BAD_REQUEST,
            "Invalid parameter type for argument: " + ex.getName(),
            ex
    ));
}

2. 让IllegalArgumentException处理器捕获包装后的异常（Spring 5.3+）

如果你更希望复用现有的handleIllegalArgumentException方法，可以利用Spring 5.3新增的@ExceptionHandler的rootCause属性，让它捕获作为根异常的IllegalArgumentException：

@ExceptionHandler(value = IllegalArgumentException.class, rootCause = true)
public ResponseEntity<Object> handleIllegalArgumentException(IllegalArgumentException ex) {
    log.info("Handled: IllegalArgumentException", ex);
    return buildResponseEntity(new ApiErrorResponse(
            HttpStatus.BAD_REQUEST,
            "Incorrect Request",
            ex
    ));
}

这样即使异常被包装在MethodArgumentTypeMismatchException里，只要根异常是IllegalArgumentException，就会被这个方法处理。

内容的提问来源于stack exchange，提问作者woj.sierak