0Pricing
Spring Boot 4 Complete Guide · 课时

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

使用 @ExceptionHandler 和 @ControllerAdvice，将异常转换集中处理为简洁的 HTTP 响应。

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

本课时的部分内容尚未翻译，以英文显示。

Why Centralize Exception Handling?

When something goes wrong in a Spring Boot REST API, the client should receive a clean, predictable HTTP response, not a raw stack trace.

Without a strategy, you end up scattering try/catch blocks across every controller method, repeating the same JSON-building logic over and over.

  • Inconsistent status codes for the same error type
  • Duplicated error-response shaping
  • Leaked internal details (stack traces, SQL) to clients

Global exception handling solves this by translating exceptions into HTTP responses in one place.

The @ExceptionHandler Building Block

The core annotation is @ExceptionHandler. It marks a method that handles a specific exception type thrown during request processing.

Placed inside a controller, it only catches exceptions thrown by that controller's handler methods.

The method's parameter declares which exception it handles, and its return value becomes the HTTP response.

@RestController
public class ProductController {

    @GetMapping("/products/{id}")
    public Product getProduct(@PathVariable Long id) {
        throw new ProductNotFoundException(id);
    }

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<String> handleNotFound(ProductNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

From Local to Global with @ControllerAdvice

A local @ExceptionHandler only covers one controller. To share handlers across the whole application, move them into a class annotated with @ControllerAdvice.

@ControllerAdvice is a specialization of @Component. Spring registers its @ExceptionHandler methods globally, so any controller that throws a matching exception is handled here.

For REST APIs, prefer @RestControllerAdvice, which combines @ControllerAdvice with @ResponseBody so return values are serialized to JSON automatically.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<String> handleNotFound(ProductNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

A Consistent Error Response Body

Returning a raw string is rarely enough. Clients want a structured, predictable JSON body they can parse.

Define a small error response record that every handler returns. This is plain Java, no framework needed, so it is fully standalone.

Spring serializes this record to JSON when returned from a @RestControllerAdvice method.

import java.time.Instant;

public record ApiError(
        Instant timestamp,
        int status,
        String error,
        String message,
        String path) {
}

public class Demo {
    public static void main(String[] args) {
        ApiError err = new ApiError(
                Instant.parse("2026-01-01T10:15:30Z"),
                404,
                "Not Found",
                "Product 42 not found",
                "/products/42");
        System.out.println(err);
    }
}

Returning Structured Errors with ResponseEntity

Now combine the ApiError record with your global handler. Build a ResponseEntity that carries both the correct status code and the structured body.

Use the injected HttpServletRequest to capture the request path, which is helpful for debugging on the client side.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<ApiError> handleNotFound(
            ProductNotFoundException ex, HttpServletRequest request) {

        ApiError error = new ApiError(
                Instant.now(),
                HttpStatus.NOT_FOUND.value(),
                HttpStatus.NOT_FOUND.getReasonPhrase(),
                ex.getMessage(),
                request.getRequestURI());

        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
}

Mapping Status with @ResponseStatus

If a handler always returns the same status and you do not need custom headers, you can skip ResponseEntity entirely.

Annotate the handler method with @ResponseStatus(...) and return the body directly. Spring applies the status code for you.

This keeps simple handlers concise, but reach for ResponseEntity when you need dynamic status codes or headers.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ApiError handleNotFound(ProductNotFoundException ex, HttpServletRequest req) {
        return new ApiError(Instant.now(), 404, "Not Found",
                ex.getMessage(), req.getRequestURI());
    }
}

Handling Validation Errors

When a @Valid request body fails Bean Validation, Spring throws MethodArgumentNotValidException. By default the JSON response is verbose and noisy.

Override it in your advice to return a clean map of field errors. Each FieldError carries the offending field name and the validation message.

@ExceptionHandler(MethodArgumentNotValidException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
public Map<String, String> handleValidation(MethodArgumentNotValidException ex) {
    Map<String, String> errors = new HashMap<>();
    for (FieldError fieldError : ex.getBindingResult().getFieldErrors()) {
        errors.put(fieldError.getField(), fieldError.getDefaultMessage());
    }
    return errors;
}

One Handler for Many Exceptions

@ExceptionHandler accepts an array of exception classes, so a single method can handle several related types that map to the same status.

This avoids duplicate code when, say, several distinct "bad input" exceptions should all become 400 Bad Request.

@ExceptionHandler({
        IllegalArgumentException.class,
        IllegalStateException.class,
        ConstraintViolationException.class
})
@ResponseStatus(HttpStatus.BAD_REQUEST)
public ApiError handleBadRequest(RuntimeException ex, HttpServletRequest req) {
    return new ApiError(Instant.now(), 400, "Bad Request",
            ex.getMessage(), req.getRequestURI());
}

Exception Resolution Order

When an exception is thrown, Spring picks the most specific matching @ExceptionHandler.

  • An exact-type handler wins over a handler for its superclass.
  • Local handlers in the controller take precedence over global ones in @ControllerAdvice.
  • If two handlers are equally specific, Spring raises an ambiguity error at startup.

This ordering lets you provide a broad fallback while still overriding specific cases.

A Safe Catch-All Fallback

Always provide a last-resort handler for Exception.class. It catches anything you did not explicitly map and prevents internal details from leaking.

Return a generic 500 Internal Server Error with a safe message, and log the real exception server-side for investigation.

Never put the raw exception message or stack trace into the client response for unexpected errors.

@ExceptionHandler(Exception.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public ApiError handleAny(Exception ex, HttpServletRequest req) {
    log.error("Unhandled exception at {}", req.getRequestURI(), ex);
    return new ApiError(Instant.now(), 500, "Internal Server Error",
            "An unexpected error occurred", req.getRequestURI());
}

Scoping and Extending the Framework Base

You can scope an advice to a subset of controllers using attributes like @RestControllerAdvice(basePackages = "com.shop.api") or assignableTypes = {...}. Unscoped advice applies everywhere.

For full control over Spring MVC's built-in exceptions (missing parameters, unreadable bodies, unsupported media types), extend ResponseEntityExceptionHandler and override its protected methods. It already declares handlers for the standard MVC exceptions.

@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<ApiError> handleNotFound(
            ProductNotFoundException ex, HttpServletRequest req) {
        ApiError error = new ApiError(Instant.now(), 404, "Not Found",
                ex.getMessage(), req.getRequestURI());
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
}

Quick Check

You have a REST API. You want validation errors and not-found errors to produce consistent JSON bodies and correct status codes across every controller, in one place. What is the idiomatic Spring Boot approach?

Recap

You learned how to centralize exception handling in Spring Boot:

  • @ExceptionHandler maps an exception type to an HTTP response; alone it is controller-local.
  • @RestControllerAdvice registers handlers globally and serializes return values to JSON.
  • Return a consistent error record (status, message, path, timestamp) for predictable clients.
  • Use ResponseEntity for dynamic status/headers, or @ResponseStatus for fixed ones.
  • Handle MethodArgumentNotValidException for clean validation errors, group related exceptions, and always add an Exception.class catch-all that hides internals.

The result is consistent, secure, and maintainable error responses across your whole API.

常见问题解答

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

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

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

使用 @ExceptionHandler 和 @ControllerAdvice，将异常转换集中处理为简洁的 HTTP 响应。 你通过在浏览器中直接运行的动手代码来练习 Spring Boot 4 Complete Guide，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Spring Boot 4 Complete Guide 需要有经验吗？

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

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

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

我能在这节 Spring Boot 4 Complete Guide 课中编写并运行代码吗？

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

此课程中的所有课时

  1. Bean Validation 约束与约束分组
  2. 构建自定义约束注解
  3. 使用 @ControllerAdvice 进行全局异常处理
  4. RFC 7807 Problem Detail 响应
← 返回 Spring Boot 4 Complete Guide