Java Academy · 课时

使用 @ControllerAdvice 进行全局异常处理

Q: 「使用 @ControllerAdvice 进行全局异常处理」这节课中我会学到什么？

使用 @ExceptionHandler 和 @ControllerAdvice，集中处理所有控制器中的异常 你通过在浏览器中直接运行的动手代码来练习 Java Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

使用 @ExceptionHandler 和 @ControllerAdvice，集中处理所有控制器中的异常

使用 @ControllerAdvice 进行全局异常处理 是 CoddyKit 上的免费 Java Academy 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Java Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Java Academy 课程共包含 4 节课。

没有全局处理时的问题

没有全局异常处理时，每个控制器方法都需要 try-catch 代码块，错误响应的构建逻辑会重复，而且异常详细信息可能泄露给客户端。

@ControllerAdvice 与 @RestControllerAdvice

@ControllerAdvice 定义全局异常处理器类。@RestControllerAdvice 添加 @ResponseBody，使所有处理器方法自动返回 JSON。

@RestControllerAdvice
public class GlobalExceptionHandler {
    // @ExceptionHandler methods go here
}

@ExceptionHandler 方法

使用 @ExceptionHandler(ExceptionType.class) 为方法添加注解。Spring 会将该类型及其子类的异常路由到此方法。返回带有适当状态的 ResponseEntity。

@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
    return ResponseEntity.status(HttpStatus.NOT_FOUND)
        .body(new ErrorResponse("NOT_FOUND", ex.getMessage()));
}

处理多种异常类型

可以在一个处理器中列出多个异常类型，也可以使用公共基类。Spring 会选择当前可用的最具体处理器。

@ExceptionHandler({IllegalArgumentException.class, IllegalStateException.class})
public ResponseEntity<ErrorResponse> handleBadRequest(RuntimeException ex) {
    return ResponseEntity.badRequest()
        .body(new ErrorResponse("BAD_REQUEST", ex.getMessage()));
}

处理验证错误

捕获 MethodArgumentNotValidException，从经过 @Valid 验证的请求体中提取字段级错误。

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<Map<String, Object>> handleValidation(MethodArgumentNotValidException ex) {
    Map<String, String> fieldErrors = new LinkedHashMap<>();
    ex.getBindingResult().getFieldErrors().forEach(e ->
        fieldErrors.put(e.getField(), e.getDefaultMessage()));
    return ResponseEntity.badRequest()
        .body(Map.of("errors", fieldErrors, "status", 400));
}

处理约束违规

在服务层使用 @Validated 验证方法参数时，会抛出 ConstraintViolationException。请将其与 MVC 验证错误分开处理。

@ExceptionHandler(ConstraintViolationException.class)
public ResponseEntity<Map<String, String>> handleConstraint(ConstraintViolationException ex) {
    Map<String, String> errors = new LinkedHashMap<>();
    ex.getConstraintViolations().forEach(v ->
        errors.put(v.getPropertyPath().toString(), v.getMessage()));
    return ResponseEntity.badRequest().body(errors);
}

访问 HttpServletRequest

将 HttpServletRequest 添加为参数，以获取请求详细信息（网址、方法和请求头），用于记录日志或将其包含在错误响应中。

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleAll(Exception ex, HttpServletRequest req) {
    log.error("Unhandled error on {} {}", req.getMethod(), req.getRequestURI(), ex);
    return ResponseEntity.internalServerError()
        .body(new ErrorResponse("INTERNAL_ERROR", "Unexpected error"));
}

在异常类上使用 @ResponseStatus

为自定义异常类添加 @ResponseStatus，无需处理器方法即可自动设置 HTTP 状态；对于简单场景，这种方式更简洁。

@ResponseStatus(HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String msg) { super(msg); }
}

限定 @ControllerAdvice 的作用范围

使用 @ControllerAdvice 上的属性，将该建议限制在特定的包、注解或基类范围内。

@RestControllerAdvice(basePackages = "com.example.api")
public class ApiExceptionHandler { ... }
@RestControllerAdvice(assignableTypes = {UserController.class, OrderController.class})
public class SpecificHandler { ... }

异常处理器中的日志记录

请在适当的级别记录异常：用户错误（4xx）使用 WARN，意外错误（5xx）使用 ERROR，并记录完整的堆栈跟踪。

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleAll(Exception ex, HttpServletRequest req) {
    if (ex instanceof BusinessException) log.warn("Business error: {}", ex.getMessage());
    else log.error("Unexpected error on {}", req.getRequestURI(), ex);
    return ...
}

异常处理器优先级

Spring 会选择最具体的处理器。如果 ResourceNotFoundException extends RuntimeException，那么针对 ResourceNotFoundException 的处理器优先级高于针对 RuntimeException 的处理器。

快速检查

哪个注解用于标记一个方法，以便在全局范围内处理特定类型的异常？

回顾

使用 @RestControllerAdvice + @ExceptionHandler 集中处理错误。返回包含统一错误结构的 ResponseEntity。分别处理验证异常（MethodArgumentNotValidException）和约束异常（ConstraintViolationException）。将 4xx 记录为 WARN，将 5xx 记录为 ERROR。

常见问题解答

「使用 @ControllerAdvice 进行全局异常处理」课时是免费的吗？

是的 — 「使用 @ControllerAdvice 进行全局异常处理」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Java Academy 课程的其余内容，请升级到 CoddyKit PRO。 Java Academy 课程共包含 4 节课。

「使用 @ControllerAdvice 进行全局异常处理」这节课中我会学到什么？

使用 @ExceptionHandler 和 @ControllerAdvice，集中处理所有控制器中的异常你通过在浏览器中直接运行的动手代码来练习 Java Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Java Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Java Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「使用 @ControllerAdvice 进行全局异常处理」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Java Academy 课中编写并运行代码吗？

能。每节 Java Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Java Academy