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.
Mục lục
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ònjakarta.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=truelà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.
checkMultipartwrap request multipart và đánh dấu cleanup.getHandlerduyệtHandlerMappingtheoOrdered; chain đầu tiên khớp thắng; không có thì 404, hoặc exception nếu bạn cấu hình.applyPreHandlegọi interceptor theo thứ tự; trảfalsethìtriggerAfterCompletionchạy và dispatch dừng.getHandlerAdapterchọn adapter đầu tiênsupports(handler); không có adapter là lỗi cấu hình, thường 500.handleresolve tham số, convert, validate, gọi method, xử lý return value; trảModelAndViewhoặcnullnếu response đã ghi.applyPostHandlechạy ngược thứ tự; bỏ qua nếu async đã bắt đầu hoặchandleném exception.processDispatchResultxử lý exception, render view, và return ngay khi async đang chạy.triggerAfterCompletionchạ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ựngRequestMappingInfotừ 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ớiResourceHttpRequestHandler.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@ExceptionHandlertrong controller rồi@ControllerAdvice; đây là đường của@RestControllerAdvicevàProblemDetail.ResponseStatusExceptionResolver: xử lý@ResponseStatusvà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ằngsetResult/setErrorResult; timeout đặt trên đối tượng hoặc quaspring.mvc.async.request-timeout.ResponseBodyEmittervàSseEmitter: ghi nhiều lần, giữ kết nối; SSE thêmtext/event-stream; phảicomplete(),completeWithError()hoặc để timeout đóng.StreamingResponseBody: ghi trực tiếpOutputStreamtrê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,SseEmittervà async request; test client chậm và client ngắt kết nối. - Nếu filter đọc body, dùng
ContentCachingRequestWrappervà đọc cache sau khi chain chạy xong.
Đọc tiếp
- Servlets là gì? Nền tảng vô hình giúp Spring MVC vận hành — phần servlet API mà bài này dựa lên.
- Spring MVC Giải Mã: Xây dựng ứng dụng web đầu tiên của bạn — dựng lại project trước khi đọc kiến trúc.
- Các thành phần thiết yếu của một ứng dụng web Spring MVC — bức tranh tổng thể quanh dispatcher.
- Cách Spring hoạt động: khám phá kiến trúc cốt lõi — đường ống khởi động, để đặt đường ống request vào đúng chỗ.



