DispatcherServlet

The DispatcherServlet is Spring MVC's front controller: a single jakarta.servlet.Servlet, normally mapped to /, that receives every request for the application and coordinates its handling. It does not contain business logic or routing decisions itself. For each request it asks HandlerMapping beans which handler applies, uses a HandlerAdapter to invoke it, lets HandlerExceptionResolvers turn exceptions into responses, and uses ViewResolvers when a view must be rendered. All these strategies are beans from the Spring context, which is why annotated controllers, functional endpoints and static resources can coexist behind one servlet. In Spring Boot it is created by DispatcherServletAutoConfiguration and registered with the embedded server; you rarely declare it yourself.

A HandlerMapping finds the handler, and for annotated controllers it is RequestMappingHandlerMapping. At start-up it scans beans annotated with @Controller, reads each @RequestMapping, @GetMapping or similar annotation and registers a RequestMappingInfo combining the path pattern, HTTP method, parameters, headers, consumes and produces media types and, in Framework 7, the API version. At request time it collects every mapping whose conditions match, chooses the most specific one and returns a HandlerExecutionChain holding the HandlerMethod plus the applicable interceptors. If two mappings are equally specific, start-up fails with an ambiguous-mapping error. The DispatcherServlet asks all HandlerMappings in order, so functional routes and static resources are found by other mappings.

Because the DispatcherServlet must invoke handlers of very different types without knowing any of them. A handler might be a HandlerMethod on an annotated controller, a HandlerFunction from a RouterFunction, a legacy Controller implementation or an HttpRequestHandler serving resources. For each handler, the dispatcher asks its HandlerAdapters which one supports it, then calls adapter.handle(). RequestMappingHandlerAdapter does the heavy lifting for annotated controllers: resolving arguments such as @PathVariable and @RequestBody, data binding and validation, invoking the method and processing the return value through message converters. This is the adapter pattern applied to dispatching, and it is why a new programming model like functional endpoints could be added without changing the DispatcherServlet itself.

A servlet filter is part of the servlet container's chain and runs before the DispatcherServlet, for every request matching its URL pattern, including static resources and requests that will never reach a controller. It works only with the raw request and response, can wrap them, and can stop the chain entirely. Spring Security, CORS, character encoding and request-id propagation belong there. A HandlerInterceptor runs inside Spring MVC, after the handler has been selected, so it knows which controller method will be invoked, can inspect its annotations, and has preHandle, postHandle and afterCompletion callbacks. Choose a filter for protocol-level or security concerns, and an interceptor for logic that depends on the handler.

doDispatch() is the core algorithm. It first checks for a multipart request and wraps it if needed. It then calls getHandler(), iterating the HandlerMappings until one returns a HandlerExecutionChain; if none does, it produces a 404. Next it finds a HandlerAdapter that supports the handler, performs the Last-Modified check for GET and HEAD, and runs each interceptor's preHandle, stopping if any returns false. It invokes ha.handle(), returns early if async processing started, applies a default view name and runs postHandle. processDispatchResult() then either resolves an exception through the HandlerExceptionResolvers or renders the view. Finally afterCompletion runs for the interceptors, and multipart resources are cleaned up.

@EnableWebMvc imports DelegatingWebMvcConfiguration, which registers a WebMvcConfigurationSupport bean, and Boot's WebMvcAutoConfiguration is conditional on that bean being missing, so it backs off completely. The application still works, but Boot's customisations disappear: message converters configured from Boot's ObjectMapper and properties, static resource handling from classpath:/static, the welcome page, spring.mvc properties, format settings and parts of the error-handling integration. Symptoms appear as changed JSON date formats, missing static files or ignored properties after someone copies an @EnableWebMvc class from a non-Boot tutorial. To customise MVC in Boot, implement WebMvcConfigurer in a normal @Configuration class without @EnableWebMvc; use the annotation only when you deliberately want to own all MVC configuration.

It depends on what the check needs. If the tenant comes from the authenticated principal, such as a JWT claim, and requests without a valid tenant must be rejected before any application code runs, implement it in the security layer: an AuthorizationManager rule or a filter added to the API SecurityFilterChain after authentication. That covers every path, including static and error dispatches. If the check depends on the handler, for example only controllers annotated with @TenantScoped, use a HandlerInterceptor registered for /api paths through WebMvcConfigurer, which can read the handler method's annotations. Either way, keep the resolved tenant in a request-scoped holder, clear it after the request, and return a consistent Problem Detail on failure.

Because it lets the framework, and the platforms built on it, evolve without breaking applications. The DispatcherServlet holds a stable algorithm, while every decision is delegated to strategy interfaces: HandlerMapping, HandlerAdapter, HandlerExceptionResolver, ViewResolver and others. Spring has used this to add annotated controllers, async request processing, functional endpoints and, in Framework 7, API versioning, all as new strategies, while code written against older models kept working. Platform teams can do the same: contribute interceptors, exception resolvers, argument resolvers or configurers through internal starters, rather than subclassing or wrapping the servlet. Extensions written that way survive framework upgrades, can be overridden per service, and keep applications on the documented, supported extension surface.