A Comprehensive Guide to Spring Boot Interceptors: How to Use Them

When building RESTful services or web applications using Spring Boot, there are times when you need to perform certain actions before or after a request is handled by a controller. For example, you may want to log requests, authenticate users, or modify the response. This is where Spring Boot Interceptors come into play.

In this blog, we’ll explore what Spring Boot Interceptors are, their use cases, and how to implement them in your Spring Boot project.

What are Spring Boot Interceptors?

In simple terms, an Interceptor in Spring Boot is a mechanism that allows you to intercept HTTP requests and responses. It acts as a filter that sits between the client and the controller, enabling you to inspect, modify, or reject requests before they reach the controller or after the controller processes them.

Think of interceptors as middleware in other frameworks like Express.js or Django. They can be incredibly useful in cross-cutting concerns such as logging, authentication, authorization, and metrics.

Interceptors provide the following three key methods:

1. preHandle(): Invoked before the request is passed to the controller. You can use it to perform tasks such as logging, authentication, or request validation.
2. postHandle(): Executed after the controller processes the request, but before the response is sent to the client.
3. afterCompletion(): Called after the complete request is finished. You can use it for cleanup actions or logging after request completion.

When to Use Interceptors

Here are some scenarios where Spring Boot Interceptors can be helpful:

• Logging requests and responses: Capture every incoming request and outgoing response for debugging or analytics.
• Security: Check if a user is authenticated or authorized before allowing access to a specific resource.
• Performance metrics: Measure the time taken to handle a request by tracking when the request enters and leaves your application.
• Global error handling: Catch and process errors globally for consistency.

Setting Up a Spring Boot Interceptor

Let’s understand how to implement an interceptor in a Spring Boot application.

Step 1: Create an Interceptor

You start by creating a class that implements the HandlerInterceptor interface. This class will define the logic that you want to execute at different stages of request processing.

import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@Component
public class RequestInterceptor implements HandlerInterceptor {

    // Executes before the request reaches the controller
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        System.out.println("Pre-handle logic: Intercepting request URL - " + request.getRequestURI());
        return true; // If false, the request will not reach the controller
    }

    // Executes after the controller processes the request but before the response is sent
    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, @Nullable ModelAndView modelAndView) throws Exception {
        System.out.println("Post-handle logic: Executing after controller logic");
        
        // Example: You can modify response headers here
        response.setHeader("X-Custom-Header", "Interceptor added this");
        System.out.println("Post-handle logic: Added custom header to the response");
    }

    // Executes after the entire request is completed
    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, @Nullable Exception exception) throws Exception {
        System.out.println("After completion logic: Cleaning up after request");
    }
}

Step 2: Register the Interceptor

Next, you need to register the interceptor with Spring. You do this by configuring the interceptor in a WebMvcConfigurer implementation.

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Autowired
    private RequestInterceptor requestInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // Register the interceptor and apply it to all endpoints
        registry.addInterceptor(requestInterceptor).addPathPatterns("/api/**");
    }
}

In the above example, the interceptor is applied to all endpoints that start with /api/**. You can also exclude certain paths or specify different patterns based on your requirements.

Understanding the Methods in the Interceptor

1. preHandle()

This method is invoked before the request reaches the controller. You can use it for tasks like:

• Logging: Log the request details like URL, headers, etc.
• Authentication: Verify if the user is logged in and has the required permissions.
• Rate-limiting: Block requests if they exceed the allowed limit for a certain user or IP address.

If preHandle() returns false, the request will be terminated, and it won’t reach the controller.

2. postHandle()

The postHandle method in the HandlerInterceptor interface is executed after the controller method has been invoked but before the response is committed to the client.

It allows modification of response headers, logging, or handling cross-cutting concerns like auditing and metrics.

3. afterCompletion()

Finally, after the entire request has completed and the view is rendered, afterCompletion() is called. This method is usually used for cleanup actions like:

• Freeing up resources: Closing any open connections, or files, or releasing locks.
• Error handling: You can log any exceptions that occurred during the request handling process.

Advanced Use Cases: Applying Multiple Interceptors

You can also access the articles related to Interceptors from the links below:

Logging Requests and Responses in Spring Boot Using Interceptors

Spring Boot also supports applying multiple interceptors to different parts of the application. To do this, you can register multiple interceptors in the WebConfig class.

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Autowired
    private FirstInterceptor firstInterceptor;

    @Autowired
    private SecondInterceptor secondInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(firstInterceptor).addPathPatterns("/api/**");
        registry.addInterceptor(secondInterceptor).addPathPatterns("/admin/**");
    }
}

Each interceptor will be applied in the order you register them, allowing you to create layered middleware for various parts of your application.

Conclusion

Spring Boot Interceptors are powerful tools for handling cross-cutting concerns like logging, authentication, and performance metrics. They allow you to interact with HTTP requests and responses without modifying your core business logic. With just a few lines of code, you can set up interceptors and easily extend their functionality as your application grows.

If you found this story helpful, don’t forget to give it a 👏! Follow me for more insights on Spring Boot and Java development.

Happy coding! 🎉