HandlerInterceptor for Cross-Cutting Concerns

Your learning outcome for this lesson:

Implement request interceptors using HandlerInterceptor for cross-cutting concerns.

1. Understanding the Interception Point

Before we write any code, let's understand where an interceptor fits into the Spring MVC request lifecycle. When a client sends an HTTP request to your application, it doesn't go straight to your @RestController. It first goes through a central component called the DispatcherServlet, which then routes it to the appropriate controller method.

A HandlerInterceptor allows us to hook into this process at critical moments.

For our rate limiter, the most important point of interception is before the controller is executed. This allows us to decide if the request should proceed or be rejected immediately, saving valuable server resources.

To get a solid conceptual foundation, please read the first section of this excellent article from Baeldung.

2. The HandlerInterceptor Interface

To create an interceptor, you implement the HandlerInterceptor interface. This interface defines three primary methods, each corresponding to a different stage in the request lifecycle.

Let's summarize the key methods and their relevance to our goal:

• boolean preHandle(...):

  • When: Executed before the controller handler method.
  • Purpose: This is our main workhorse. We will use it to check if a request is within its allowed rate limit.
  • Return Value: Critically, it returns a boolean.
    • true: The request continues to the next interceptor or the controller itself.
    • false: The request processing stops here. The controller method is never called. This is exactly what we need to reject an over-the-limit request.

• void postHandle(...):

  • When: Executed after the controller method returns, but before the response is sent to the client.
  • Purpose: Useful for modifying the model or response headers before the view is rendered. We won't use this for our core rate-limiting logic, but it's good to know.

• void afterCompletion(...):

  • When: Executed after the complete request has finished and the response has been sent.
  • Purpose: Ideal for cleanup tasks, such as logging request duration or releasing resources. It will always be called, even if an exception occurred.

3. Implementing and Registering Your First Interceptor

Now, let's get hands-on. We'll create a simple logging interceptor to see the execution flow in action. This will serve as the blueprint for our rate-limiting interceptor later.

Exercise: Create a Logging Interceptor

Follow along with the video to implement and register an interceptor that logs messages at each stage of the request lifecycle. This will involve two steps:

1. Creating the interceptor class.
2. Creating a configuration class to register it.

After completing this exercise, your console output for a single request should look something like this, confirming the execution order:

preHandle request URI is /greeting
Request is reached to controller
postHandle executed for request URI /greeting
afterCompletion request completed

4. Advanced Configuration for Real-World Use

Instantiating the interceptor with new LoggingInterceptor() inside the configuration works, but it's not ideal. For our rate limiter, the interceptor will need access to other services (like configuration properties or a Redis connection). To enable this, we should let Spring manage the interceptor as a bean.

Furthermore, we rarely want an interceptor to apply to every single endpoint. For example, you wouldn't rate-limit a /health check endpoint. We need to selectively apply our interceptor.

This is where the true power of the InterceptorRegistry comes in.

Exercise 2: Refine Your Interceptor Configuration

Let's apply these advanced concepts to your project.

1. Make your interceptor a Spring Bean:

   • Add the @Component annotation to your LoggingInterceptor class.

   // In LoggingInterceptor.java
   import org.springframework.stereotype.Component;
   
   @Component // <-- Add this
   public class LoggingInterceptor implements HandlerInterceptor { ... }
   

2. Inject the bean into your WebConfig:

   • Modify your WebConfig to inject the LoggingInterceptor bean via its constructor instead of creating a new instance.

   // In WebConfig.java
   @Configuration
   public class WebConfig implements WebMvcConfigurer {
   
       private final LoggingInterceptor loggingInterceptor;
   
       // Inject the bean via constructor
       public WebConfig(LoggingInterceptor loggingInterceptor) {
           this.loggingInterceptor = loggingInterceptor;
       }
   
       @Override
       public void addInterceptors(InterceptorRegistry registry) {
           // Use the injected bean
           registry.addInterceptor(loggingInterceptor);
       }
   }
   

3. Apply Path Matching:

   • Let's configure the interceptor to only apply to our /greeting endpoint. Modify the addInterceptors method.

   @Override
   public void addInterceptors(InterceptorRegistry registry) {
       registry.addInterceptor(loggingInterceptor)
               .addPathPatterns("/greeting"); // <-- Add this line
   }
   

4. Test your changes:

   • Re-run your application.
   • A request to http://localhost:8080/greeting should still produce the log messages.
   • If you had another endpoint (e.g., one provided by Spring Boot Actuator like http://localhost:8080/actuator/health), you would notice that the interceptor logs do not appear for it. You have successfully limited the scope of your interceptor.

This pattern of creating an interceptor as a managed @Component and then registering it with specific addPathPatterns is precisely the architecture we will use to build our flexible, rule-based rate limiter.

Key Takeaways

• Cross-Cutting Concerns: Interceptors are Spring's primary mechanism for handling logic that applies across multiple endpoints, such as rate limiting, logging, or authentication.
• HandlerInterceptor: This is the core interface with three methods: preHandle, postHandle, and afterCompletion, which hook into different stages of the request lifecycle.
• preHandle is Key: For validation and access control like rate limiting, preHandle is the most important method. Returning false from it efficiently stops the request from being processed further.
• Registration is Mandatory: An interceptor must be registered using a class that implements WebMvcConfigurer and overrides the addInterceptors method.
• Scope Control: Use addPathPatterns() and excludePathPatterns() to precisely control which API endpoints your interceptor applies to.

Next Steps

With this lesson, you have completed the foundational module on Spring Boot! You now have a working, configurable API service and, most importantly, the architectural hook—the HandlerInterceptor—where our rate-limiting logic will reside.

In the next module, we will shift our focus from the "how" of Spring Boot to the "what" of rate limiting. The next lesson begins our journey into Rate Limiting Principles and Architectural Design, where we will start by exploring the fundamental need for rate limiting and then dive into the details of the first algorithm: the Fixed Window Counter.