DispatcherServlet Internals: A Request's Full Journey

Type http://localhost:8080/users/42 into the address bar and press Enter; a lot happens in a few hundred milliseconds. The request first reaches Tomcat, which parses the HTTP message and wraps the method, path, headers and body into an HttpServletRequest.

Then comes an interesting question: Tomcat only understands the Servlet interface — service(request, response). But we write plain methods in a @Controller, a method annotated with @GetMapping("/users/{id}"), and Tomcat knows nothing about it. So who translates "a Servlet call" into "a call to the method you wrote"?

The answer is DispatcherServlet — the front controller of Spring MVC. It is itself a Servlet registered on every request path (mapped to /), so every HTTP request lands in its hands first and is then dispatched to a specific handler. That is the front-controller pattern: one entry point, centralized dispatching.

In Spring Boot you do not even see the registration code, because auto-configuration does it:

Walking up DispatcherServlet's inheritance chain, the logic is spread across several layers:

The key is that at startup it calls initStrategies(), initializing nine "helper components":

• The nine components are strategies: DispatcherServlet only dispatches, delegating "how to match", "how to invoke" and "how to render"
• HandlerMapping and HandlerAdapter are the stars of the main flow, covered in later sections
• To customize any link, just register your own bean in the container; initStrategies() prefers the container's implementation

The whole dispatch skeleton lives in doDispatch. Stripped of details, the core structure is:

That animation is the "reading" version. Reading and being able to debug differ by exactly one thing: whether you can name the line you are on. So here is the same skeleton as a step-through bench — eight lines of doDispatch on the left, live variables and a call stack on the right. Press next and watch mappedHandler and dispatchException; step ⑦ (the exception is only stashed) is where most readers get it backwards.

getHandler iterates over all HandlerMappings and uses the first one that returns non-null. The most common is RequestMappingHandlerMapping, which extends AbstractHandlerMethodMapping and whose core is a "request → method" registry:

A natural question: DispatcherServlet already has "the method to call", so why another layer, HandlerAdapter?

Because "handlers" can be implemented in very different ways:

• A @Controller method (HandlerMethod) needs argument resolution + reflective invocation + return-value handling
• A bean implementing HttpRequestHandler only needs handleRequest(request, response)
• A plain Controller interface implementation (old-style Spring MVC) has yet another signature

DispatcherServlet cannot write an if-else for each handler. The adapter pattern exists precisely for this: DispatcherServlet only says "I need an adapter that can run this handler" and lets the adapter handle the concrete invocation.

Inside getMethodArgumentValues lives a "library of argument resolvers". Whatever annotation an argument carries, the matching resolver fetches the value from the request and converts the type:

The table above has nine rows, but what a table cannot show is order: the resolvers are a chain, and every argument is asked down it from the front. Tap through it — especially node ⑤, which is the source of the most confusing English sentence beginners meet:

After the method runs, its return value still has to be "translated" into an HTTP response. A set of HandlerMethodReturnValueHandlers plus HttpMessageConverters does this together:

Two demos cover this section, and both are about watching a fork happen in real time. First, the way out: how a return value becomes bytes. Tap the four arguments in order — accept explains negotiation, fail is the birth scene of a 406:

Then back to that "one String, two fates" trap. The same return statement, only the class-level annotation swapped, and the exit is somewhere else entirely:

doDispatch stashes the exception in a catch, and processDispatchResult handles it. It consults a set of HandlerExceptionResolvers in order, and the first to return non-null owns it:

This relay has six steps and deserves its own animation — step 2 (stash, do not handle) and step 6 (nobody caught it) are what tell you which line to fix:

Mapping errors onto the main flow removes all guesswork when troubleshooting. A table cannot teach this, though — six codes, six positions, so play it: click a status code, then the stop you think it died at, and a wrong pair tells you on the spot what you mixed up.

The demo below turns the doDispatch main flow into switchable paths. Try /users/42, /users and /nope in turn, and watch which component is working at each step and when the 404 appears:

Set the jargon aside for a moment. Picture walking into a public hospital knowing nothing about the process — yet never getting lost, because every counter revolves around one central service desk.

Every role on this chain does exactly one job, so you can always locate a problem with a single question: "which stop did my request die at?"

When you finish this article you should answer three questions without looking anything up:

• Why can Spring MVC take over the whole site with a single Servlet? (It is mapped to /, the only entry point)
• A 404 versus a 405 — which stop does each one blame? (Registration desk versus triage desk)
• Why can't a Filter tell you "which Controller method is executing"? (getHandler has not run yet)

Section 11 walked the trunk with dispatch, but doDispatch hides two more "ask everyone in turn" chains that confuse beginners most: one on the way in (who fills my method arguments) and one on the way out (who turns my exception into a response). Both follow the same script — ask in order; the first one that says "that's mine" wins; if all say no, you get an error.

The argument side first. Inside ha.handle(), every single parameter of your method signature runs down the resolver chain:

Now the exception side. The chain inside processDispatchResult is the same string of ifs:

The two demos below turn each chain into a switchable scene. Click through every parameter button in order, especially the last one, "no resolver" — that is precisely the error sitting in your own project:

Section 9 pinned status codes onto stops, but real incidents ask a different set of questions: the log line printed but the traceId did not propagate, CORS broke, postHandle never ran. All of that lives in the few metres of corridor between the service desk and the front door.

One sentence each, so the two never blur together:

• Filter: part of the Servlet spec, not of Spring. It runs before DispatcherServlet, so it cannot even know which method this request will call
• Interceptor: part of Spring MVC, registered inside the HandlerExecutionChain, travelling with one specific handler chain — and therefore able to see the HandlerMethod

The three differences people forget, easiest to remember alongside the animation:

Open all five parameters of the demo below one by one; pay special attention to "preHandle returns false", "does postHandle run on error" and "CORS preflight" — they map onto three real ticket categories:

Once you have clicked through the demos, switch to a command line. This console talks to the same kernel inside your browser and every reply is computed, not scripted — run boot first, then type the six claims of this article one by one:

The four columns are fixed: "error snippet / real cause / thirty-second fix / where to dig deeper". Copy the error verbatim into a search engine — do not paraphrase. Search understands fully-qualified class names; it does not understand your description.

The row about "POST returns 405" is the one that sends beginners hunting in the wrong file. Here is that stack for real — do not read the analysis first; click the line you think is guilty:

Last step: tick the handful of configuration lines this article actually uses. Do not copy somebody else's yml — every checkbox maps onto a symptom described above: logging produces the registered-mapping list Section 15 told you to read, server produces context-path (the number-one source of 404s), upload corresponds to the checkMultipart call on the first line of doDispatch, and profile lets dev and prod use different prefixes without a code change:

This sandbox computes nothing — it performs incident reconstruction: disabling one component simulates one real production shape. Pick a combination and the output gives you "symptom + where to look first".

Goal: run "one request through nine stops" from scratch, and watch four different status codes come out of four different stops.

Verification commands (paste each curl into a terminal):

Expected response (command 1):

For command 3 expect the status line HTTP/1.1 405 and — importantly — no No mapping in the console: the mapping was found, only the verb was refused. For command 4 expect HTTP/1.1 404 plus one log line No mapping for GET /nope. For command 5 expect HTTP/1.1 400 plus the fully-qualified org.springframework.web.method.annotation.MethodArgumentTypeMismatchException.

Three small edits, each one or two lines. The point is to watch the error text change:

1. Delete the class-level @RequestMapping("/api/users") and rerun command 1 → you observe a 404 whose log now reads No mapping for GET /api/users/42: a URL is the class prefix concatenated with the method path, and half of it matches nothing
2. Change @RestController to @Controller, touch nothing else → you observe javax.servlet.ServletException: Circular view path [get] (or a template 404), because the returned UserVO is no longer serialized but interpreted as view information — exactly the two fates described in Section 7
3. Change @GetMapping("/{id}") to @GetMapping("/{id:\\d+}") and rerun command 5 → you observe the status change from 400 to 404: the regex constraint rejects /abc at the registration desk, so type conversion never even gets a turn. Trading "fail later" for "fail cleaner" is a design decision, not a syntax trick

Build a "request journey recorder": for any endpoint, print which stops it passed and how long each took.

Requirements:

• A TraceIdFilter (extending OncePerRequestFilter) that mints a traceId into MDC and logs total cost in a finally
• A JourneyInterceptor (implementing HandlerInterceptor) whose preHandle records the entry time and stores the HandlerMethod's "Class#method" as a request attribute
• A @RestControllerAdvice that maps MethodArgumentTypeMismatchException to {"code":40000,...} while keeping HTTP 400

Acceptance checklist:

• [ ] curl -i localhost:8080/api/users/42 shows an X-Trace-Id response header (proof the filter is alive)
• [ ] The log also contains the matched controller method name (proof the interceptor saw the HandlerMethod, which a filter cannot)
• [ ] /api/users/abc returns 400 with your unified error body, not the Whitelabel page
• [ ] Flip the interceptor's preHandle to return false, rerun the same command and confirm the response becomes "empty body + 200" — reproducing Section 16's first trap with your own hands
• [ ] Comment out @Component on the filter and confirm the timing log disappears while endpoints keep working: the outer ring is removable, the inner one is not