DispatcherServlet & Front Controller — một servlet nhận mọi request

TL;DR: DispatcherServlet là Front Controller duy nhất của Spring MVC — nhận mọi HTTP request rồi dispatch đến handler phù hợp. Lý do tồn tại: gom cross-cutting (auth, log, i18n, error) vào một chỗ thay vì lặp trong từng servlet. Bên dưới, nó delegate cho 9 bean infrastructure: HandlerMapping tìm handler, HandlerAdapter invoke, HttpMessageConverter serialize JSON, HandlerExceptionResolver xử lý lỗi,... Boot WebMvcAutoConfiguration + DispatcherServletAutoConfiguration setup tất cả theo pattern @ConditionalOnMissingBean. Pitfall cốt lõi: dùng @EnableWebMvc vô tình disable toàn bộ Boot autoconfig — luôn customize qua WebMvcConfigurer.

DispatcherServlet là bean nằm trong Spring ApplicationContext — context được khởi động qua refresh() 12 bước trước khi servlet sẵn sàng nhận request. Bài này bóc phần servlet biết request đã vào — bài URL routing & request pipeline tiếp tục với HandlerMapping deep dive.

1. Vì sao cần Front Controller — vấn đề của page-controller cũ

Trước Spring MVC, Java EE web app dùng page-controller pattern: mỗi URL map một servlet riêng.

GET /orders         →  OrderListServlet.doGet()
GET /orders/42      →  OrderDetailServlet.doGet()
POST /orders        →  OrderCreateServlet.doPost()
DELETE /orders/42   →  OrderDeleteServlet.doDelete()

Mỗi servlet extends HttpServlet, khai báo trong web.xml. Đây là cách Java EE chuẩn — nhưng đau theo 3 chiều:

Cross-cutting concern lặp lại — auth check, logging, i18n locale, error handling phải viết trong mỗi servlet. App 50 endpoint = 50 chỗ duplicate. Thêm một bước audit log mới? Sửa 50 file.

Boilerplate config — web.xml khai báo từng servlet + URL mapping. 100 endpoint = 200 entry XML. Tất cả phải restart để nhận config mới.

Khó test — servlet bind cứng vào servlet container. Test OrderListServlet phải start Tomcat, không test unit thuần.

Front Controller pattern (Martin Fowler, "Patterns of Enterprise Application Architecture", 2002) giải quyết bằng một điểm vào duy nhất:

flowchart LR
    R["HTTP Request<br/>bat ky URL nao"]
    FC["DispatcherServlet<br/>(Front Controller<br/>1 servlet duy nhat)"]
    H1["OrderController<br/>.getOrder()"]
    H2["UserController<br/>.listUsers()"]
    H3["ProductController<br/>.search()"]

    R --> FC
    FC -->|"route"| H1
    FC -->|"route"| H2
    FC -->|"route"| H3

1 servlet nhận mọi request. Cross-cutting (auth filter, log interceptor, error resolver) chạy trong/quanh servlet đó — viết 1 lần, áp dụng cho mọi request. Handler là method Java thường — không extends servlet, không bind container, test dễ.

Vì sao thiết kế này tồn tại, không phải alternative? Alternative là middleware chain (Express.js style) — cũng valid, nhưng Java Servlet spec đã có sẵn single-entry-point qua URL pattern /*. Front Controller tận dụng pattern đó, không phá vỡ spec. Struts 2, JAX-RS Jersey, Spring MVC đều chọn Front Controller vì lý do này.

2. DispatcherServlet là gì bên dưới

DispatcherServlet extends FrameworkServlet extends HttpServletBean extends HttpServlet. Nó là một servlet Java EE thật — Tomcat không biết gì đặc biệt về nó.

flowchart TB
    DS["DispatcherServlet"]
    FS["FrameworkServlet"]
    HSB["HttpServletBean"]
    HS["javax.servlet.http.HttpServlet"]

    DS -->|extends| FS
    FS -->|extends| HSB
    HSB -->|extends| HS

Khi request vào, Tomcat gọi service(req, res) — đây là servlet API chuẩn. FrameworkServlet.service() route tới doGet()/doPost()/... rồi tất cả hội tụ về DispatcherServlet.doDispatch(request, response) — đây là method cốt lõi (~80 dòng) thực hiện toàn bộ flow dispatch.

Cơ chế bên dưới — luồng doDispatch

sequenceDiagram
    participant Tomcat
    participant DS as DispatcherServlet
    participant HM as HandlerMapping
    participant HA as HandlerAdapter
    participant IC as Interceptors
    participant Ctrl as Controller method
    participant MC as MessageConverter

    Tomcat->>DS: service(request, response)
    DS->>HM: getHandler(request)
    HM-->>DS: HandlerExecutionChain<br/>(method + interceptor list)
    DS->>HA: getHandlerAdapter(handler)
    HA-->>DS: RequestMappingHandlerAdapter
    DS->>IC: preHandle() x N
    DS->>HA: handle(request, response, handler)
    HA->>Ctrl: getOrder(42L)
    Ctrl-->>HA: ResponseEntity
    HA->>MC: write JSON to response
    DS->>IC: postHandle() + afterCompletion()

9 bước theo thứ tự:

1. Tomcat nhận request, dispatch đến DispatcherServlet.doDispatch().
2. getHandler(request) hỏi danh sách HandlerMapping — tìm handler match URL + HTTP method.
3. Trả về HandlerExecutionChain — wrapper chứa handler method + list interceptor áp dụng.
4. getHandlerAdapter(handler) chọn adapter tương thích loại handler.
5. Chạy preHandle() trên mỗi interceptor theo thứ tự. Interceptor nào trả false sẽ short-circuit flow — request dừng tại đó, không bao giờ đến controller.
6. Adapter invoke handler — resolve argument từ request, gọi method controller.
7. Controller return Object hoặc ResponseEntity.
8. Adapter dùng HttpMessageConverter serialize return value thành HTTP response body.
9. Chạy postHandle() + afterCompletion() trên interceptor theo thứ tự ngược.

Vì sao biết flow này quan trọng? Khi request "không đến controller" — bug ở bước 2 (không match URL), 3 (interceptor reject), hoặc 5 (adapter không tìm được). Không biết flow, debug mù.

3. 9 bean infrastructure

DispatcherServlet không tự làm hết — nó delegate cho 9 loại bean. Đây là Dependency Inversion: servlet chỉ gọi interface, implementation thay được mà không sửa servlet.

Với REST API (trọng tâm module này), 4 bean quan trọng nhất là HandlerMapping, HandlerAdapter, HttpMessageConverter, và HandlerExceptionResolver. ViewResolver ít dùng vì REST trả JSON không render view.

3.1 HandlerMapping — tìm handler từ request

RequestMappingHandlerMapping đọc tất cả @RequestMapping / @GetMapping / @PostMapping trên class + method lúc khởi động, build bảng routing:

GET  /api/orders/{id}   →  OrderController.getOrder(Long)
GET  /api/orders        →  OrderController.listOrders()
POST /api/orders        →  OrderController.createOrder(OrderRequest)

Khi request đến, mapper so URL + HTTP method với bảng routing rồi trả về HandlerExecutionChain. Nếu không entry nào match, Spring throw NoHandlerFoundException và Boot trả 404 mặc định.

Bài URL routing & request pipeline đào sâu PathPattern syntax ({id}, **, regex), ambiguous mapping, và cách Boot resolve conflict.

3.2 HandlerAdapter — invoke đúng cách

Spring hỗ trợ nhiều loại handler: method @RequestMapping, Servlet, HttpRequestHandler, WebFlux handler. Adapter pattern cho phép DispatcherServlet không biết loại handler — nó hỏi từng adapter supports(handler)?, adapter biết cách invoke.

RequestMappingHandlerAdapter xử lý method @RequestMapping:

1. Resolve từng argument: @PathVariable từ URL, @RequestParam từ query string, @RequestBody qua MessageConverter.
2. Invoke method.
3. Convert return value: nếu method có @ResponseBody hoặc return ResponseEntity, adapter dùng MessageConverter để ghi body.

3.3 HttpMessageConverter — body ↔ object

HttpMessageConverter là bridge giữa HTTP byte stream và Java object:

• Đọc (@RequestBody): với POST /orders body {"total": 150}, converter parse JSON thành OrderRequest object trước khi method chạy.
• Ghi (@ResponseBody / ResponseEntity): controller return OrderDto, converter serialize object đó thành JSON response body.

Boot register converter theo classpath. Chọn converter bằng content negotiation:

• Client gửi Content-Type: application/json thì Spring đọc body bằng JSON converter.
• Client gửi Accept: application/xml thì Spring ghi body bằng XML converter (nếu có jackson-dataformat-xml).
• Khi không converter nào phù hợp, Spring trả 415 Unsupported Media Type (chiều đọc) hoặc 406 Not Acceptable (chiều ghi).

3.4 HandlerExceptionResolver — convert exception thành response

Khi controller throw exception, DispatcherServlet catch rồi iterate qua list HandlerExceptionResolver theo @Order:

flowchart TB
    Ex["Controller throws Exception"]
    DS["DispatcherServlet catch"]
    R1["ExceptionHandlerExceptionResolver<br/>@ExceptionHandler method"]
    R2["ResponseStatusExceptionResolver<br/>@ResponseStatus annotation"]
    R3["DefaultHandlerExceptionResolver<br/>Spring built-in exception"]
    R500["500 error page (fallback)"]

    DS --> R1
    R1 -->|"khong match"| R2
    R2 -->|"khong match"| R3
    R3 -->|"khong match"| R500

Bài exception handling & advice đào sâu @ControllerAdvice + Problem Details RFC 9457.

4. Boot tự setup thế nào

Không có Spring Boot, bạn phải register DispatcherServlet thủ công trong web.xml hoặc WebApplicationInitializer. Boot tự làm qua hai auto-configuration class:

DispatcherServletAutoConfiguration — register DispatcherServlet bean và đăng ký nó với Tomcat:

// Rut gon — spring-boot-autoconfigure
@AutoConfiguration
@ConditionalOnWebApplication(type = SERVLET)
@ConditionalOnClass(DispatcherServlet.class)
public class DispatcherServletAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public DispatcherServlet dispatcherServlet(WebMvcProperties props) {
        DispatcherServlet ds = new DispatcherServlet();
        ds.setDispatchOptionsRequest(props.isDispatchOptionsRequest());
        // ... apply properties
        return ds;
    }

    @Bean
    @ConditionalOnMissingBean
    public DispatcherServletRegistrationBean dispatcherServletRegistration(
            DispatcherServlet ds, WebMvcProperties props) {
        // Register voi Tomcat, URL pattern "/"
        return new DispatcherServletRegistrationBean(ds, props.getServlet().getPath());
    }
}

WebMvcAutoConfiguration — register 9 bean infrastructure:

@AutoConfiguration(after = DispatcherServletAutoConfiguration.class)
@ConditionalOnWebApplication(type = SERVLET)
@ConditionalOnClass({ Servlet.class, DispatcherServlet.class, WebMvcConfigurer.class })
@ConditionalOnMissingBean(WebMvcConfigurationSupport.class)   // <-- KEY: disable neu @EnableWebMvc
public class WebMvcAutoConfiguration {

    @Bean
    public RequestMappingHandlerMapping requestMappingHandlerMapping(...) { ... }

    @Bean
    public RequestMappingHandlerAdapter requestMappingHandlerAdapter(...) { ... }

    // ... 7 bean khac
}

Dòng @ConditionalOnMissingBean(WebMvcConfigurationSupport.class) là then chốt: khi bạn thêm @EnableWebMvc, nó import DelegatingWebMvcConfiguration extends WebMvcConfigurationSupport — condition này lập tức fail, kéo theo WebMvcAutoConfiguration bị skip hoàn toàn.

Customize mà không phá defaults — WebMvcConfigurer

Boot collect tất cả bean implement WebMvcConfigurer, gọi mỗi method để merge customization vào defaults:

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new TimingInterceptor())
                .addPathPatterns("/api/**");
    }

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins("https://olhub.vn");
    }

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        // Them converter tuy chinh — KHONG replace default list
        converters.add(new ProtobufHttpMessageConverter());
    }
}

Khác biệt cốt lõi: WebMvcConfigurer contribute (thêm vào), @EnableWebMvc replace (xóa defaults rồi bắt bạn config từ đầu).

5. Filter vs Interceptor — chạy ở đâu trong flow

Cả hai intercept request — nhưng ở tầng khác nhau:

flowchart LR
    Client["Client"] --> F["Filter Chain<br/>(Servlet API)"]
    F --> DS["DispatcherServlet"]
    DS --> IC["Interceptor preHandle<br/>(Spring MVC)"]
    IC --> Ctrl["Controller method"]
    Ctrl --> IC2["Interceptor postHandle<br/>+ afterCompletion"]
    IC2 --> F2["Filter (response phase)"]
    F2 --> Client

Vì sao Filter phù hợp auth? Vì auth phải chạy trước routing — reject request trước khi DispatcherServlet thậm chí tìm handler. Spring Security implement toàn bộ qua filter chain cho lý do này.

Vì sao Interceptor phù hợp audit? Vì interceptor biết HandlerMethod — biết class controller, tên method, annotation trên method. Audit log "user X gọi OrderController.delete()" không thể làm từ filter (filter không biết handler).

6. Pitfall thực tế

❌ Nhầm 1 — @EnableWebMvc để "cấu hình MVC":

@Configuration
@EnableWebMvc           // SAI — tat het Boot autoconfig
public class WebConfig implements WebMvcConfigurer {
    // Moi thu khac mat: Jackson, static resource, error mapping...
}

✅ Bỏ @EnableWebMvc. Implement WebMvcConfigurer không cần annotation đó — Boot pick up tự động.

❌ Nhầm 2 — Tưởng DispatcherServlet là singleton toàn JVM:

✅ DispatcherServlet là bean trong WebApplicationContext — nó là singleton trong phạm vi context đó. Cơ chế giống singleton bean: một entry trong singletonObjects map của context. Mỗi request Tomcat dùng cùng instance servlet, nhưng mỗi request có HttpServletRequest/HttpServletResponse riêng — thread-safe vì không có state trên field servlet.

❌ Nhầm 3 — Tưởng interceptor chạy như filter:

// Interceptor trong WebConfig
@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(new JwtInterceptor());  // CHUA DU cho auth
}

✅ Interceptor chạy SAU routing — nếu không match URL nào, NoHandlerFoundException xảy ra trước interceptor. Dùng filter nếu cần intercept mọi request kể cả 404. Dùng interceptor nếu chỉ cần intercept request đã match handler.

❌ Nhầm 4 — configureMessageConverters thay thế mặc định:

@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    converters.add(new ProtobufHttpMessageConverter());
    // Jackson BIEN MAT -- list ban dau empty, boot default khong inject
}

✅ Dùng extendMessageConverters thay — list đã có default, method này chỉ thêm:

@Override
public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
    converters.add(0, new ProtobufHttpMessageConverter()); // them vao dau
}

7. Deep Dive

Liên hệ các bài khác

• refresh() 12 bước khởi tạo container: DispatcherServlet là một bean trong WebApplicationContext — context phải refresh() xong trước khi servlet sẵn sàng nhận request. Biết 12 bước đó giúp hiểu vì sao lỗi cấu hình lộ ra lúc startup, không phải lúc request đầu tiên.
• Bài 02 — URL routing & request pipeline: deep dive HandlerMapping — PathPattern syntax, ambiguous mapping, header/param matching, và cách RequestMappingHandlerAdapter resolve argument từ request.
• Singleton bean & scopes: DispatcherServlet singleton trong context — cùng cơ chế singletonObjects map. Giải thích vì sao không có state trên field servlet mà nhiều request vẫn an toàn.

Tóm tắt

• Front Controller pattern: 1 servlet duy nhất nhận mọi request → cross-cutting (auth, log, i18n) tập trung 1 chỗ, handler là method Java thường không phải servlet.
• DispatcherServlet là HttpServlet thật, đăng ký với Tomcat URL pattern "/". Method cốt lõi: doDispatch().
• 9 bước dispatch: Tomcat → HandlerMapping → HandlerExecutionChain → HandlerAdapter → Interceptor preHandle → Controller → MessageConverter → Interceptor afterCompletion.
• 9 bean infrastructure: HandlerMapping, HandlerAdapter, HandlerInterceptor, HttpMessageConverter, HandlerExceptionResolver, ViewResolver, LocaleResolver, MultipartResolver, ThemeResolver.
• Boot setup qua DispatcherServletAutoConfiguration (register servlet) + WebMvcAutoConfiguration (register 9 bean) — cả 2 dùng @ConditionalOnMissingBean.
• Customize qua WebMvcConfigurer (contribute, giữ defaults). Không dùng @EnableWebMvc (replace, phá defaults).
• Filter chạy trước DispatcherServlet (auth, CORS). Interceptor chạy sau routing, biết handler (audit, timing).

Tự kiểm tra

@Component
public class TimingInterceptor implements HandlerInterceptor {

  @Override
  public boolean preHandle(HttpServletRequest req, HttpServletResponse res, Object handler) {
      req.setAttribute("startTime", System.currentTimeMillis());
      return true; // tiep tuc xu ly
  }

  @Override
  public void afterCompletion(HttpServletRequest req, HttpServletResponse res,
                              Object handler, Exception ex) {
      long elapsed = System.currentTimeMillis() - (long) req.getAttribute("startTime");
      if (handler instanceof HandlerMethod hm) {
          String ctrl = hm.getBeanType().getSimpleName();
          String method = hm.getMethod().getName();
          // log: "OrderController.getOrder took 42ms"
      }
  }
}

@Configuration
public class WebConfig implements WebMvcConfigurer {
  @Autowired private TimingInterceptor timingInterceptor;

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

Bài tiếp theo: URL routing & request pipeline