@ControllerAdvice vs. @RestControllerAdvice in Spring

By Atul Rai | Last Updated: October 30, 2023 Previous       Next

Spring Boot is a popular framework for building robust and scalable web applications and RESTful services. When developing such applications, handling exceptions and managing global behavior is essential. This is where the @ControllerAdvice and @RestControllerAdvice annotations come into play. In this blog, we’ll explore these annotations and discuss when to use each of them in Spring Boot applications.

What are @ControllerAdvice and @RestControllerAdvice?

Both @ControllerAdvice and @RestControllerAdvice are Spring annotations used to handle exceptions and define global behavior in Spring Boot applications. They are used to centralize exception handling and other concerns to keep the codebase clean and organized.

1. @ControllerAdvice

• @ControllerAdvice is used for handling exceptions in traditional Spring MVC applications where you primarily return HTML views.
• It can be used to define global exception handlers for controllers, offering flexibility in handling exceptions across various controllers.

2. @RestControllerAdvice

• @RestControllerAdvice is an extension of @ControllerAdvice and is primarily used in Spring Boot applications that serve RESTful services.
• It’s designed for situations where you need to handle exceptions and return JSON responses, as it assumes that your controllers return data directly, not views.

1. When to use @ControllerAdvice

Use @ControllerAdvice when you are working with Spring MVC applications that return HTML views. This is ideal for traditional web applications where you need to handle exceptions and potentially redirect users to error pages. Here are some scenarios in which you might choose @ControllerAdvice:

1. Custom Error Pages: If your application uses custom error pages (e.g., for 404 or 500 errors) and you want to centralize the logic for rendering these pages.
2. Global Error Handling: When you need to apply consistent error handling logic across multiple controllers, such as logging errors or performing custom actions.
3. View Resolvers: If your application relies on view resolvers to render HTML templates, you can use @ControllerAdvice to customize error handling without affecting RESTful endpoints.

2. When to use @RestControllerAdvice

On the other hand, @RestControllerAdvice is more suitable for Spring Boot applications serving RESTful services where the controllers return data in the form of JSON or other serialization formats. Here’s when you should opt for @RestControllerAdvice:

1. API Endpoints: When building RESTful APIs, use @RestControllerAdvice to handle exceptions and return JSON responses. This is crucial for providing meaningful error details to API consumers.
2. Consistent JSON Error Responses: If you want to ensure that all exceptions in your API endpoints produce consistent, well-structured JSON error responses, @RestControllerAdvice is the way to go.
3. RESTful Exception Handling: For global exception handling in RESTful services, @RestControllerAdvice simplifies the process by directly returning JSON responses instead of relying on views.

Let’s illustrate the usage of both annotations with simple code examples:

@ControllerAdvice Example:

@ControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(Exception.class)
    public String handleGlobalException(Model model, Exception ex) {
        model.addAttribute("errorMessage", "An error occurred: " + ex.getMessage());
        return "error";
    }
}

In this @ControllerAdvice example, we handle exceptions by returning an HTML view.

@RestControllerAdvice Example:

@RestControllerAdvice
public class RestExceptionHandler {
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiResponse> handleGlobalException(Exception ex) {
        ApiResponse errorResponse = new ApiResponse("An error occurred: " + ex.getMessage());
        return new ResponseEntity<>(errorResponse, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

In this @RestControllerAdvice example, we return a JSON response containing error details, suitable for RESTful services.

Related Posts:

1. Global Exception Handling in Spring Boot
2. Spring @RestControllerAdvice Annotation Example

3. Summary

In summary, the choice between @ControllerAdvice and @RestControllerAdvice in Spring Boot applications depends on the nature of your application and the type of content you return from your controllers. Use @ControllerAdvice for traditional Spring MVC applications that return HTML views, and opt for @RestControllerAdvice when building RESTful services that return JSON responses.

4. References

1. Annotation Interface RestControllerAdvice- SpringDoc
2. nnotation Interface ControllerAdvice- SpringDoc