Filters, Interceptors and AOP: Order and Practice

Set aside the names Filter, Interceptor and AOP for a moment. All you need to remember is this: an HTTP request is a passenger walking from the terminal entrance to the gate, and it passes several completely different checkpoints along the way — each able to see a wildly different amount of information.

After this article you should be able to answer three questions:

• A Filter, an Interceptor and an aspect all look like they can "intercept" a request. Which one can see the method name, and why does that single fact decide everything?
• The controller throws an exception. Which hooks still run, which are skipped, and where does the exception actually go?
• I need a login check that returns a uniform JSON error body and can whitelist /login. Which layer, and why is the obvious alternative worse?

"Should the login check live in a Filter or an Interceptor?" "Should request timing use an interceptor or AOP?" Almost every Spring newcomer hits the same fork: all three mechanisms seem able to "intercept" a request before the business code runs, so you pick one at random — until the day you discover "the interceptor can't see the method name" or "the aspect can't catch static resources" and go back to study.

Define the roles first; the choice then follows naturally:

Flatten one normal request and the order is:

What if the controller throws? The exception path is: Filter before-code → preHandle → controller throws → postHandle is skipped → afterCompletion (reverse order, exception passed as the argument) → the exception is handed to HandlerExceptionResolver → response is written → Filter after-code. Remember one line: postHandle is for success, afterCompletion is for cleanup — one may be skipped, the other always runs.

That line can only be read once. The diagram below unfolds it into nine stations you can click through — when learning an order, what matters is not memorising it but knowing who each station is waiting for:

Filters suit chores that are business-agnostic and apply to every request. Two classics: CORS and access logs.

A CORS filter must run first, or preflight (OPTIONS) requests get blocked by later logic:

A request-timing log demonstrates the "after" code:

A @Component Filter is auto-registered by Spring Boot, but its order is hard to control. For precise ordering use FilterRegistrationBean:

The annotation route exists too, but the app must scan it:

The login check is the Interceptor's home turf: it knows which method will run and can be whitelisted precisely with excludePathPatterns.

Register the interceptor and configure include/exclude patterns:

This is the table to remember — it decides whether the client gets a proper error at all:

The two paths differ by one line of source but by an order of magnitude in outcome. Step through the debugger and watch exactly what gets skipped — pay attention to step 2 (the short circuit) and step 4 (why postHandle never gets a second chance):

Frame ⑤ of that animation is the expensive one: the interceptor that returned false never gets its own afterCompletion. Metrics, ThreadLocal cleanup and auditing written in its completion hook silently miss every request it rejects — which is precisely what the "swap the registration order" exercise in Tier 2 of Section 18 makes you observe.

Many people wonder, on first meeting AOP: "If an aspect can wrap methods, can it intercept the whole request?" The answer is no, and the reason lives in the word "proxy".

• AOP works by creating a proxy for a bean that the Spring container manages; a call must go through the injected proxy for the aspect to fire
• The Servlet container (Tomcat) instantiates and calls Filters directly, bypassing the Spring proxy entirely — no aspect can attach
• Spring MVC calls the registered interceptor object directly; preHandle is not a proxied bean method either, so aspects miss it too
• More fundamentally: AOP wraps a method call, so the request must already be inside the method body. The whole point of preHandle is to reject a request before the method is invoked — AOP simply cannot do that; by the time it steps in, the business method is already running

AOP's real home is inside methods: transactions, caching, timing, idempotency, rate limiting. It has boundaries too, worth knowing before use:

• It applies only to Spring-managed beans; objects you new yourself have no proxy
• Self-invocation inside the same class (this.otherMethod()) bypasses the proxy, so the aspect is skipped — inject the bean into itself or use AopContext.currentProxy()
• private / final methods cannot be overridden by CGLIB, so the aspect is skipped as well

All three can be ordered, but differently; mixing them up is easy. Rather than memorising a table, play a round: the left column is the code you write, the right column is the rule that actually applies — a wrong pick explains itself immediately.

Real tracing needs "one traceId per request", carried from the outermost layer into the logs. This is where the three cooperate: the Filter creates and binds it, and the Interceptor / AOP / business just reuse it.

Reference %X{traceId} in the log pattern to print it automatically:

That relay — generate once, reuse everywhere, clean up at the end — deserves its own walkthrough, because the classic beginner failure here is doing the first two steps and forgetting the third. When traceIds in production logs belong to the wrong request, eight times out of ten the remove call in finally was skipped:

The demo below turns the DispatcherServlet dispatch flow into switchable paths. Switch between /users/42, /users and /nope, and watch the order of argument resolution and controller execution — preHandle happens before both, which is exactly why an interceptor can reject a request early.

The first ten sections were talking. This one is running. The demo below turns the five things people argue about most in this chapter into switchable parameters — work through order → pre → ex → cors → scope in that order, and each cell maps onto a real ticket.

The same need, placed on the wrong layer, simply loses its powers — which is exactly what that diagram catalogues:

What each of the five parameters is supposed to show you:

• order: the complete line — container filters (forward) → DispatcherServlet → preHandle (forward) → argument resolution and validation → controller → postHandle (reverse) → exception resolution → afterCompletion (reverse) → filter after-code (reverse). Note that afterCompletion runs earlier than the body is actually flushed out
• pre: the moment preHandle returns false, applyPreHandle aborts — later interceptors, argument resolution, the controller and postHandle are all skipped, and only interceptors that already passed receive afterCompletion. That is the number one reason counters silently under-report
• ex: when the controller throws, applyPostHandle is skipped wholesale — even if @RestControllerAdvice later turns the exception into a tidy 400, postHandle is never replayed, while afterCompletion always runs and carries the original exception
• cors: which of the three CORS placements (Filter / addCorsMappings / @CrossOrigin) survives. A preflight carries no credentials, so authorisation ordered ahead of CORS judges a legitimate OPTIONS request as 401
• scope: the hard boundary of what each checkpoint can see — the diagram above, in motion

In the traceId combination of Section 8 you notice a clash as soon as the project pulls in Spring Security: "your own interceptor" and "Security's filters" are competing for the same job. Look at the structure of its chain first — the Security chain is itself a dozen filters, bridged by a DelegatingFilterProxy (a container filter that delegates to Spring beans) into a FilterChainProxy that picks the concrete chain.

Three conclusions to take away from that chain:

• Authentication first, authorisation last: AuthorizationFilter at the tail (formerly FilterSecurityInterceptor) is the only step that decides whether the request passes
• 401 versus 403 depends purely on "who are you": no identity at all → AuthenticationEntryPoint answers 401; identity without the permission → AccessDeniedHandler answers 403
• When you need custom authorisation, extend that chain instead of stacking a second LoginInterceptor on top — otherwise one request is judged twice, and when it goes wrong you cannot tell who blocked it

Section 13 was about who blocked it; this one is about when. The same URL can fail in three different places — handler found but nobody can execute it, parameters that cannot be filled, an exception nobody takes — and each produces a completely different answer. First pin the interceptor onto the dispatch line:

Now match the three paths against what preHandle actually sees:

Then look at where exceptions land. An exception from preHandle, from argument resolution, or from the controller all travel one and the same resolver chain, but they are picked up by different resolvers and end in different status codes:

• Key point: if you want a uniform JSON for "not signed in", the exception has to enter this chain — which is exactly why Section 5 recommends throwing over returning false: a return false request never gets here
• The last parameter, none, is the cell beginners least expect: when all three resolvers return null the exception escapes, Tomcat's error-page mechanism catches it, and the client receives a Whitelabel page instead of your error body

You can also get the interception right and still lose on the shape of the return value: the same return "redirect:/login" is a view name in an @Controller and a JSON string in a @RestController. Click all four cases, missing in particular — that one is the real body of "the browser lands on a blank page after being rejected":

The labs watch the kernel run; the console is you driving it. This is a real container and every line of output is computed by the Java kernel in your browser — use beans to confirm the filters and interceptors were actually registered, then lab to replay each scene above:

If beans does not list your LoginInterceptor, the reason is usually not a missing @Component: the registration method was never called. A WebMvcConfigurer living outside the main class's package means addInterceptors is silently skipped. Commands 3 and 4 are the Section 5 fork intype-it-yourself form: same handler, order gives you all nine stations, pre gives you "everything from here disappears".

The four columns below are fixed: error fragment / real cause / 30-second fix / where to dig. Copy the error text verbatim into a search engine — engines match fully qualified class names and whole English sentences, not your description of them.

The fourth row — fine in testing, a 500 as soon as somebody opens the homepage — is the best stack to practise reading. It is long, but only one line is guilty:

Half of the failures above are caused by not being able to see the scene: a static resource caught by the chain, a body read empty, a 404 that never reaches an interceptor. Generate the triage-time configuration instead of typing it out by hand:

One thing to check in the generated output: logging.level.org.springframework.web=debug prints the type of the matched handler, which is where the static-resource and error-page handlers from Sections 4 and 15 finally show themselves. Turn it back off before production.

This sandbox computes nothing; it is a job matching exercise. Pick a layer on the left and a requirement on the right, and the output tells you whether the three things that decide it are available: can it get the HandlerMethod (which class, which method), can it get the response body (before it is written), is the transaction already open.

Goal: run "one Filter + two Interceptors + one Advice" end to end and watch three shapes with your own eyes: the ordering, the short circuit, the exception path.

Verify each case with curl after startup — every request takes a different path through the chain:

Expected log order for request 3:

For requests 2 and 4 the expectation is: no postHandle ran line at all, while [METRICS] ... ex=... and [FILTER] still print. That is "postHandle is for success, afterCompletion always runs, the Filter wraps everything" proven on your own console.

Three edits, each one or two lines long; the point is to watch the error text and the response body change:

1. Replace the throw in AuthInterceptor.preHandle with return false, then run request 2. You will see the status is still 200 with an empty body, and the [METRICS] line disappears too — because when the first interceptor short-circuits, the second never even gets a preHandle. This is the interceptor|auth cell of the sandbox in Section 17.
2. Swap the two addInterceptor calls so metrics registers first, then run request 2 again. Now [METRICS] ... ex=IllegalStateException: NOT_LOGIN appears: the metrics interceptor was entered first, so it receives the completion callback. Conclusion: register the metrics interceptor before the auth one, or every rejected request is missing from your counters.
3. Add req.getInputStream().readAllBytes(); before chain.doFilter in TimingFilter, then POST to an endpoint with @RequestBody. You will get HttpMessageNotReadableException: Required request body is missing, and wrapping the request in a ContentCachingRequestWrapper fixes it immediately.

Build a "gatekeeper + bookkeeper" pair: every write operation (POST / PUT / DELETE) must be signed in and carry X-Request-Id, and the app must be able to answer "who was blocked, at which layer".

Requirements:

• A CorsFilter at HIGHEST_PRECEDENCE: answer OPTIONS with 200 without entering the business code; when cookies are involved use allowedOriginPatterns, never *
• An AuditInterceptor: in preHandle test handler instanceof HandlerMethod, then put the class-level @RequestMapping prefix plus the method name into the MDC; in afterCompletion log the elapsed time and flag requests where ex != null
• A RepeatableBodyFilter: cache the body with an HttpServletRequestWrapper so one JSON payload can be read by the filter and still be read by @RequestBody
• A @RestControllerAdvice: turn IllegalStateException("NOT_LOGIN") into {"code":40100,"msg":"please sign in"} with the HTTP status still 401

Acceptance checklist:

• [ ] curl -i -X OPTIONS -H "Origin: http://localhost:5173" -H "Access-Control-Request-Method: POST" localhost:8080/api/orders returns 200 and carries Access-Control-Allow-Origin — proof that CORS runs ahead of auth
• [ ] /api/orders without Authorization answers 401 plus the uniform JSON error body — not an empty 200, not a Whitelabel page
• [ ] The logs contain "Class#method" (proof the interceptor really received the HandlerMethod; move the same logic into CorsFilter and it immediately cannot)
• [ ] POST a valid JSON: the controller receives the object and the filter log prints the raw body (proof the wrapper works)
• [ ] Make the controller throw on purpose and confirm the audit line is still written (proof the bookkeeping lives in afterCompletion, not postHandle)