Spring Boot 4 Microservices & REST APIs · 课时

@ControllerAdvice 和 @ExceptionHandler

全局处理异常

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

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

The Problem with Scattered Try/Catch

Handling errors with try/catch in every controller duplicates code and produces inconsistent responses. Spring MVC offers a centralized model: exception handlers that turn exceptions into clean HTTP responses.

Local @ExceptionHandler

A method annotated @ExceptionHandler inside a controller handles the listed exception types for that controller. It maps an exception to a response.

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

Going Global with @ControllerAdvice

@ControllerAdvice (or @RestControllerAdvice) hosts exception handlers that apply across all controllers. This centralizes error handling in one class.

@RestControllerAdvice
public class GlobalExceptionHandler {
    // handlers shared by every controller
}

Handling a Domain Exception

Define handlers for your own exceptions, returning the right status and a structured body. The same logic now serves every endpoint.

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(ResourceNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ApiError notFound(ResourceNotFoundException ex) {
        return new ApiError("NOT_FOUND", ex.getMessage());
    }
}

A Consistent Error DTO

Return a uniform error shape so clients can parse failures predictably. Include a code, a human message, and optionally a timestamp and field details.

public record ApiError(
        String code,
        String message,
        Instant timestamp) {
    public ApiError(String code, String message) {
        this(code, message, Instant.now());
    }
}

Handling Validation Errors

Catch MethodArgumentNotValidException to convert Bean Validation failures into a clear, field-by-field response instead of Spring’s default body.

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

A Catch-All Handler

Add a handler for Exception as a safety net, returning 500 with a generic message. Crucially, log the real exception but never leak stack traces to clients.

@ExceptionHandler(Exception.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public ApiError handleUnexpected(Exception ex) {
    log.error("Unhandled error", ex);
    return new ApiError("INTERNAL_ERROR", "Something went wrong");
}

Handler Selection Order

Spring picks the handler whose exception type most closely matches the thrown exception. A handler for OrderNotFoundException beats one for its superclass, so specific handlers take priority.

Scoping the Advice

You can narrow a @ControllerAdvice to specific packages, annotations, or controller types, allowing different error policies for, say, public vs internal APIs.

@RestControllerAdvice(basePackages = "com.example.api.publicapi")
public class PublicApiExceptionHandler { }

Accessing the Request

Handler methods can accept extra parameters like WebRequest or HttpServletRequest to enrich responses with the path or a correlation id.

@ExceptionHandler(ResourceNotFoundException.class)
public ApiError notFound(ResourceNotFoundException ex, HttpServletRequest req) {
    return new ApiError("NOT_FOUND", ex.getMessage() + " at " + req.getRequestURI());
}

Security: Do Not Over-Share

Error responses are a common information-leak vector. Return enough for clients to act, but never expose internal class names, SQL, or stack traces. Log details server-side instead.

Quick Check

Test your understanding of centralized handling.

Recap

Centralize error handling.

@ExceptionHandler maps exceptions to responses
@ControllerAdvice applies handlers across all controllers
Return a consistent error DTO
Handle validation, domain, and catch-all cases
Most specific handler wins; never leak internals to clients

常见问题解答

「@ControllerAdvice 和 @ExceptionHandler」课时是免费的吗？

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

「@ControllerAdvice 和 @ExceptionHandler」这节课中我会学到什么？

全局处理异常你通过在浏览器中直接运行的动手代码来练习 Spring Boot 4 Microservices & REST APIs，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Spring Boot 4 Microservices & REST APIs 需要有经验吗？

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

「@ControllerAdvice 和 @ExceptionHandler」课时需要多长时间？

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

我能在这节 Spring Boot 4 Microservices & REST APIs 课中编写并运行代码吗？

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

此课程中的所有课时

← 返回 Spring Boot 4 Microservices & REST APIs