Kiến Trúc Spring MVC: DispatcherServlet và Những Người Bạn

Endpoint có @RestController vẫn 404, @ControllerAdvice không bắt được lỗi từ filter, Callable trả về response rỗng. Ba triệu chứng, một đường ống. Hiểu DispatcherServlet gọi ai, theo thứ tự nào và trên luồng nào sẽ chỉ ra đúng chặng cần sửa.

Cập nhật 2026

  • Boot 4.1.2 trên Framework 7.0.10, Tomcat 11.0.x, Servlet 6.1, baseline Jakarta EE 11; javax.servlet đã bị loại bỏ, chỉ còn jakarta.servlet.
  • Framework 7 thêm API versioning ở tầng mapping; version được resolve trước khi handler được chọn.
  • Java 25 LTS và spring.threads.virtual.enabled=true làm virtual thread khả dụng, nhưng hợp đồng async của Servlet không đổi.

DispatcherServlet: một servlet cho toàn bộ ứng dụng

Spring MVC tạo đúng một DispatcherServlet — kế thừa FrameworkServlet, kế thừa HttpServlet — và Boot map nó vào /, default servlet mapping của container. Mọi request không khớp mapping cụ thể hơn đều vào đây: API, HTML, ảnh tĩnh, Actuator, và cả lần dispatch sau lỗi.

Hai tầng trách nhiệm: FrameworkServlet override các doXxx và dồn vào processRequest, khởi tạo context, publish event; DispatcherServlet làm MVC trong doService → doDispatch — tìm handler, chạy interceptor, gọi adapter, xử lý exception, render.

Nó không biết controller nào xử lý GET /users/42; nó chỉ hỏi các cộng sự và ghép câu trả lời. Vì vậy thay HandlerMapping, HandlerAdapter hay ViewResolver không cần sửa servlet, và lỗi “404 dù có controller” thường nằm ở chặng hỏi.

Browser -> Tomcat 11 -> Filter chain (DispatcherType.REQUEST)
  |
  v
DispatcherServlet (mapped "/")
  +- getHandler ----------> HandlerMapping -> HandlerExecutionChain
  +- applyPreHandle ------> interceptor.preHandle (theo thu tu)
  +- getHandlerAdapter ---> HandlerAdapter.supports(handler)
  +- handle --------------> argument resolvers -> controller
  |                         +- return value handler
  +- applyPostHandle -----> interceptor.postHandle (nguoc thu tu)
  +- processDispatchResult
  |    +- exception ------> HandlerExceptionResolver(s)
  |    +- ModelAndView ---> ViewResolver -> View.render
  |    +- @ResponseBody --> HttpMessageConverter
  +- triggerAfterCompletion -> interceptor.afterCompletion (nguoc)

Mỗi mũi tên là một điểm cắm logic, với dữ liệu khác nhau: filter không thấy handler, interceptor thấy HandlerMethod, converter chỉ chạy sau khi method trả về.

DispatcherServlet và doDispatch: thứ tự thật

doDispatch biến kiến trúc thành thứ tự gọi; mỗi bước là một interface bạn có thể thay hoặc quan sát.

  1. checkMultipart wrap request multipart và đánh dấu cleanup.
  2. getHandler duyệt HandlerMapping theo Ordered; chain đầu tiên khớp thắng; không có thì 404, hoặc exception nếu bạn cấu hình.
  3. applyPreHandle gọi interceptor theo thứ tự; trả false thì triggerAfterCompletion chạy và dispatch dừng.
  4. getHandlerAdapter chọn adapter đầu tiên supports(handler); không có adapter là lỗi cấu hình, thường 500.
  5. handle resolve tham số, convert, validate, gọi method, xử lý return value; trả ModelAndView hoặc null nếu response đã ghi.
  6. applyPostHandle chạy ngược thứ tự; bỏ qua nếu async đã bắt đầu hoặc handle ném exception.
  7. processDispatchResult xử lý exception, render view, và return ngay khi async đang chạy.
  8. triggerAfterCompletion chạy ngược, kể cả khi có exception — nơi đóng resource, clear MDC, ghi log kết thúc.

Ba hệ quả: exception trong preHandle vẫn qua resolver vì nằm trong khối try; exception trong postHandle cũng qua resolver nhưng response có thể đã commit; async làm doDispatch return ngay sau handle, nên postHandle không chạy và afterCompletion chạy ở dispatch sau.

Trên async redispatch, getHandler và applyPreHandle chạy lại. Interceptor có thể thấy cùng request hai lần nếu không kiểm tra request.isAsyncDispatch().

// File: src/main/java/shop/web/TimingInterceptor.java
public class TimingInterceptor implements HandlerInterceptor {

    private static final Logger log = LoggerFactory.getLogger(TimingInterceptor.class);

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
                             Object handler) {
        if (request.isAsyncDispatch()) {
            return true; // async redispatch: khong lap lai side effect
        }
        request.setAttribute("start", System.nanoTime());
        return true; // false: response do ban ghi, chuoi dung lai
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
                                Object handler, Exception ex) {
        Long start = (Long) request.getAttribute("start");
        if (start != null) {
            log.info("{} {} {} ms", request.getMethod(), request.getRequestURI(),
                    (System.nanoTime() - start) / 1_000_000);
        }
    }
}

Những người bạn của DispatcherServlet

HandlerMapping

HandlerMapping trả về HandlerExecutionChain — handler cộng interceptor — không trả method. Bốn implementation trong app Boot:

  • RequestMappingHandlerMapping: scan @Controller/@RestController, dựng RequestMappingInfo từ URL, method, params, headers, consumes, produces. Mapping dựng lúc khởi động nên mapping trùng fail sớm.
  • SimpleUrlHandlerMapping: pattern → handler tường minh; Boot dùng cho static resource với ResourceHttpRequestHandler.
  • BeanNameUrlHandlerMapping: bean có tên bắt đầu /, legacy nhưng vẫn được đăng ký.
  • RouterFunctionMapping: functional endpoint (RouterFunction).

Chúng sắp theo Ordered; một pattern quá rộng tự thêm vào có thể nuốt request trước RequestMappingHandlerMapping.

Framework 7 đưa version vào RequestMappingInfo: ApiVersionResolver đọc version từ request theo cấu hình spring.mvc.apiversion.*, ApiVersionParser chuẩn hóa, ApiVersionDeprecationHandler báo deprecated. Việc chọn version xảy ra trong getHandler, trước controller; interceptor và exception resolver không cần biết.

HandlerExecutionChain và HandlerInterceptor

Chain giữ handler và interceptor. preHandle chạy theo thứ tự đăng ký, postHandle/afterCompletion ngược lại, nên interceptor đầu mở resource thì interceptor cuối đóng resource. AsyncHandlerInterceptor.afterConcurrentHandlingStarted chạy trên luồng ban đầu khi async bắt đầu, thay cho postHandle.

HandlerAdapter

Adapter tồn tại vì handler có nhiều kiểu: RequestMappingHandlerAdapter cho annotation, HttpRequestHandlerAdapter cho ResourceHttpRequestHandler, SimpleControllerHandlerAdapter cho interface Controller cũ. supports(handler) chỉ kiểm tra kiểu; việc chọn URL đã xong ở mapping.

Magic nằm ở hai danh sách resolver. HandlerMethodArgumentResolver biến request thành tham số: @PathVariable, @RequestParam, @ModelAttribute, @RequestBody qua converter, @Valid qua binder. HandlerMethodReturnValueHandler biến return thành response: view, body qua converter, hoặc async.

HandlerExceptionResolver

Exception thoát khỏi handler hoặc interceptor được processDispatchResult đưa qua resolver theo thứ tự:

  • ExceptionHandlerExceptionResolver: tìm @ExceptionHandler trong controller rồi @ControllerAdvice; đây là đường của @RestControllerAdvice và ProblemDetail.
  • ResponseStatusExceptionResolver: xử lý @ResponseStatus và ResponseStatusException.
  • DefaultHandlerExceptionResolver: exception framework — 405, 415, 400, 503 async timeout.

Không resolver nào nhận thì exception được ném lại cho container. Nếu response đã commit, không còn ghi được body lỗi: resolver vẫn chạy nhưng exception đi ra ngoài, và client thấy status đã gửi trước đó.

ViewResolver và HttpMessageConverter

ViewResolver chỉ chạy khi handler trả tên view hoặc ModelAndView: nó biến tên logic thành View, rồi View.render trộn model và ghi response. ContentNegotiatingViewResolver chọn theo Accept, ThymeleafViewResolver cho Thymeleaf, InternalResourceViewResolver cho JSP cũ.

@ResponseBody bỏ qua nhánh view: RequestResponseBodyMethodProcessor chọn HttpMessageConverter theo kiểu đích và media type (canRead/canWrite). Không converter nào đọc được là 415; không converter nào ghi được theo Accept là 406. Thêm converter là đủ để trả JSON và XML từ cùng một DTO.

Async: trả servlet thread lại cho container

Request đồng bộ dùng một thread từ filter đến render. Async trả thread về pool trước khi có kết quả; bên dưới là AsyncContext, được Spring bọc trong StandardServletAsyncWebRequest và điều phối bởi WebAsyncManager. Khi kết quả sẵn sàng, AsyncContext.dispatch() đưa request quay lại DispatcherServlet; kết quả được render ở lần dispatch đó, rồi afterCompletion chạy.

  • Callable<T>: submit lên task executor, kết quả xử lý khi container dispatch lại.
  • DeferredResult<T>: thread bất kỳ hoàn tất bằng setResult/setErrorResult; timeout đặt trên đối tượng hoặc qua spring.mvc.async.request-timeout.
  • ResponseBodyEmitter và SseEmitter: ghi nhiều lần, giữ kết nối; SSE thêm text/event-stream; phải complete(), completeWithError() hoặc để timeout đóng.
  • StreamingResponseBody: ghi trực tiếp OutputStream trên luồng async, hợp với file lớn.
// File: src/main/java/shop/report/ReportController.java
@RestController
@RequestMapping("/api/reports")
public class ReportController {

    private static final Logger log = LoggerFactory.getLogger(ReportController.class);

    private final ReportService service;

    public ReportController(ReportService service) {
        this.service = service;
    }

    @GetMapping("/{id}/summary")
    public Callable<Report> summary(@PathVariable Long id) {
        return () -> service.buildSummary(id); // chay tren task executor
    }

    @GetMapping("/{id}/export")
    public DeferredResult<ResponseEntity<Resource>> export(@PathVariable Long id) {
        DeferredResult<ResponseEntity<Resource>> result = new DeferredResult<>(20_000L);
        result.onTimeout(() -> log.warn("export {} timeout", id));
        service.exportAsync(id, result); // setResult(...) hoac setErrorResult(ex)
        return result;
    }

    @GetMapping(value = "/{id}/events", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public SseEmitter events(@PathVariable Long id) {
        SseEmitter emitter = new SseEmitter(Long.MAX_VALUE);
        service.streamProgress(id, emitter); // send(...) roi complete()
        return emitter;
    }
}

Timeout không xử lý thành AsyncRequestTimeoutException và resolver mặc định trả 503. Đặt timeout tường minh cho từng loại tác vụ; job dài nên chuyển sang message queue thay vì giữ kết nối HTTP.

Virtual thread đổi chi phí, không đổi hợp đồng: spring.threads.virtual.enabled=true cho task executor của ứng dụng chạy trên virtual thread, và các HTTP client auto-config dùng JDK HttpClient cũng vậy, nên việc chờ rẻ hơn nhiều. Nhưng AsyncContext vẫn giữ kết nối, connection pool và CPU vẫn hữu hạn; blocking 30 giây trong Callable vẫn giữ một kết nối DB.

Lỗi đi đâu và ai bắt được

Exception từ handler, binding, converter, preHandle/postHandle đều vào resolver chain: @ExceptionHandler trong controller trước, rồi @ControllerAdvice. Không ai xử lý thì exception được ném lại, container error dispatch tới /error, nơi Boot đăng ký BasicErrorController: JSON hoặc HTML theo Accept, với timestamp, status, error, path; message mặc định ẩn vì server.error.include-message=never.

Filter nằm ngoài DispatcherServlet: exception trong filter — trước chain.doFilter hoặc sau khi response đã commit — không đi qua HandlerExceptionResolver, nên @ControllerAdvice không thấy. Hãy bắt exception ngay trong filter và ghi ProblemDetail, hoặc chuyển logic đó vào interceptor.

Tiêu chí Filter HandlerInterceptor
Vị trí Ngoài DispatcherServlet, quanh servlet chain Trong DispatcherServlet, sau getHandler
Dữ liệu Có request/response, không biết handler Có HandlerMethod và annotation; không nên đọc body
Exception Không qua @ControllerAdvice Qua resolver chain, trừ khi response đã commit
Async/error Mặc định chỉ REQUEST; phải khai báo thêm ASYNC/ERROR Async: preHandle chạy lại, postHandle bị bỏ, afterCompletion ở cuối
Phù hợp Auth thô, CORS, rate limit theo IP, logging body Authz theo method, metrics theo handler, locale

Đừng dùng interceptor làm lớp bảo vệ duy nhất: request không khớp handler, do servlet khác phục vụ, hoặc error dispatch có thể không đi qua pattern của bạn. Spring Security đặt filter ở đúng tầng đó và đăng ký cho cả ASYNC, ERROR, REQUEST.

Những lỗi cấu hình hay gặp

Đổi servlet path mà quên phần còn lại

spring.mvc.servlet.path mặc định là /. Đổi thành một prefix như /api không chỉ đổi URL controller: static resource không còn được phục vụ ở root, còn error page /error không còn đi qua DispatcherServlet nên BasicErrorController mất tác dụng. Nếu chỉ cần prefix, dùng server.servlet.context-path; nếu thật sự tách servlet, kiểm tra health check, ảnh tĩnh và error response trước khi deploy.

Interceptor không phải lớp chặn toàn cục

Interceptor chỉ chạy khi getHandler trả về chain. Với Boot mặc định, ảnh tĩnh qua ResourceHttpRequestHandler vẫn có chain nên interceptor vẫn chạy; nó chỉ không chạy khi request không có handler (404 không mapping nào khớp), khi resource do servlet hoặc mapping khác phục vụ, hoặc khi path không khớp addPathPatterns. Đừng đặt rate limit hay kiểm tra token ở đây nếu logic phải chạy cả trên đường error và static ngoài mapping.

Exception trong filter bỏ qua ControllerAdvice

Filter chạy trước khi DispatcherServlet xuất hiện trong đường đi, nên không có handler và không có resolver. Cần body lỗi thống nhất thì bắt ngay trong filter và dùng response.sendError hoặc tự ghi ProblemDetail.

Blocking trong luồng async

Async không biến code blocking thành non-blocking. Callable gọi HTTP client đồng bộ vẫn giữ thread executor và connection client; DeferredResult không bao giờ được set vẫn treo đến timeout. Giới hạn executor, đặt timeout, đóng SseEmitter khi client disconnect — virtual thread không tăng kích thước connection pool.

Đọc request body hai lần

@RequestBody đọc InputStream một lần. Nếu filter hoặc interceptor đọc trước, controller nhận body rỗng và ném HttpMessageNotReadableException; với form-urlencoded, gọi getParameter cũng có thể tiêu thụ body. Dùng ContentCachingRequestWrapper trong filter, cho controller đọc qua wrapper, và chỉ đọc getContentAsByteArray() sau chain.doFilter để logging.

Checklist trước khi chỉnh pipeline

  • Giữ spring.mvc.servlet.path=/ trừ khi thật sự muốn tách toàn bộ MVC sang prefix; kiểm tra Actuator, static và error sau khi đổi.
  • Bật logging.level.org.springframework.web.servlet.DispatcherServlet=DEBUG để xem handler nào được chọn.
  • Đặt auth, CORS, logging body ở filter; authz theo method, metrics và locale ở interceptor.
  • Đặt timeout tường minh cho DeferredResult, SseEmitter và async request; test client chậm và client ngắt kết nối.
  • Nếu filter đọc body, dùng ContentCachingRequestWrapper và đọc cache sau khi chain chạy xong.

Đọc tiếp