Java Spring Roadmap: Các Thành Phần Thiết Yếu Của Một Ứng Dụng Web Spring MVC

Bạn đổi produces sang application/json, client gửi Accept: application/xml, và endpoint trả 406 dù thân method chưa hề chạy. Hoặc bạn thêm một converter để xuất CSV, và mọi API khác bắt đầu trả JSON sai. Cả hai lỗi đều không nằm trong controller: chúng nằm ở tầng hạ tầng mà Spring MVC dựng sẵn.

Spring MVC không phải một router cộng vài annotation. Mỗi request đi qua một chuỗi thành phần cố định, mỗi thành phần đưa ra một quyết định riêng, và mọi thứ bạn cấu hình qua WebMvcConfigurer đều là chèn thêm vào chuỗi đó. Bài này đi qua từng thành phần ở mức runtime, chỉ rõ Boot 4.1.2 tự cấu hình cái gì, rồi đi hết một request GET /api/orders/42, trên Boot 4.1.2 / Framework 7.0.10 / Java 25 LTS.

Cập nhật 2026

  • Auto-configuration đổi package. Trong Boot 4.1.2, WebMvcAutoConfiguration nằm ở org.springframework.boot.webmvc.autoconfigure, trong module spring-boot-webmvc. spring-boot-starter-web vẫn chạy, nhưng POM của nó ghi rõ deprecated in favor of spring-boot-starter-webmvc.
  • API converter đổi. configureMessageConverters(List) và extendMessageConverters(List) bị deprecate từ Framework 7.0; thay bằng configureMessageConverters(HttpMessageConverters.ServerBuilder).
  • JSON mặc định là Jackson 3. Boot 4.1.2 kéo tools.jackson.core:jackson-databind 3.1.7, converter mặc định là JacksonJsonHttpMessageConverter. Tutorial cũ nhắc MappingJackson2HttpMessageConverter đang nói về Jackson 2.
  • Theme bị bỏ, versioning vào mapping. Framework 7.0 loại bỏ theme support nên ThemeResolver không còn trong spring-webmvc; @GetMapping(version = "1") và configureApiVersioning đưa API versioning vào tầng mapping. RestTemplate đã deprecate ở phía client.

Spring MVC runtime: mỗi thành phần trả lời một câu hỏi

Đọc bảng từ trên xuống là bạn có mental model của DispatcherServlet.doDispatch(); cột cuối cho biết Boot dựng sẵn thành phần nào.

Thành phần Quyết định gì trong request Ai cấu hình
DispatcherServlet Nhận request, gọi mapping, điều phối phần còn lại Boot đăng ký tại spring.mvc.servlet.path
HandlerMapping Request khớp handler nào, kèm interceptor nào Auto-config, thêm qua @RequestMapping
HandlerAdapter Gọi handler bằng cơ chế nào Auto-config, hiếm khi đổi
HttpMessageConverter Body đọc và ghi bằng format nào Auto-config, sửa qua WebMvcConfigurer
ViewResolver Tên view logic thành template vật lý nào Auto-config, sửa qua configureViewResolvers
HandlerExceptionResolver Exception thành response nào Auto-config, thêm bằng @ControllerAdvice
MultipartResolver Request có phải multipart và parse phần nào Auto-config
LocaleResolver Locale của request lấy từ đâu Auto-config, thay bằng bean
ThemeResolver Theme nào được chọn (đã bỏ ở 7.0) Không còn
FlashMapManager Flash attribute sống qua redirect thế nào Auto-config
HandlerInterceptor Logic gì chạy trước và sau handler Chỉ qua addInterceptors

Ba thành phần đầu chạy cho mọi request. Converter chỉ tham gia khi có body cần đọc hoặc ghi; ViewResolver chỉ chạy khi handler trả về tên view. Interceptor không phải strategy của DispatcherServlet: nó gắn vào HandlerMapping và chỉ tồn tại khi một handler đã khớp.

DispatcherServlet: một servlet, tám strategy

Boot đăng ký một DispatcherServlet tại / (đổi bằng spring.mvc.servlet.path) và đặt load-on-startup = -1, nên strategy chỉ được khởi tạo ở request đầu tiên. Trong initStrategies(), servlet tìm bean theo type rồi theo tên; không thấy thì dựng default. Trước 7.0 có chín nhóm strategy, trong đó có theme; theme bị bỏ nên còn tám.

Điều đáng nhớ: DispatcherServlet không tự quyết định format, status hay view; nó chỉ gọi đúng thành phần cho từng câu hỏi. Muốn đổi hành vi thì sửa thành phần tương ứng, không sửa servlet.

HandlerMapping: khớp điều kiện, không chỉ khớp path

RequestMappingHandlerMapping đọc toàn bộ @RequestMapping và biến chúng thành RequestMappingInfo, gồm path pattern, HTTP method, params, headers, consumes, produces và version. Hai method cùng path nhưng khác HTTP method hoặc khác version là hai mapping hợp lệ. Cùng path và cùng HTTP method là lỗi khởi động, không phải lỗi runtime.

Thứ tự mapping có ý nghĩa. RequestMappingHandlerMapping đứng trước SimpleUrlHandlerMapping mà Boot dùng cho static resources, nên controller thắng khi cả hai cùng khớp. Nhưng nếu không có controller nào khớp, resource handler mặc định /** sẽ thử tìm file trong các static location của Boot và có thể trả 200 cho một URL API lẽ ra phải 404.

Khi không mapping nào khớp, handleNoMatch phân biệt ba trường hợp: path không tồn tại là 404, path có nhưng produces không thỏa Accept là 406, consumes không thỏa Content-Type là 415. Vì vậy 406/415 có thể xuất hiện trước khi code của bạn chạy một dòng nào.

HandlerAdapter: biến handler thành lời gọi

Mapping trả về một handler, nhưng handler có nhiều hình dạng: method có annotation, HttpRequestHandler của static resources, hay class implements Controller. HandlerAdapter là lớp biết cách gọi từng loại. Với controller thường, RequestMappingHandlerAdapter phân tích chữ ký method, dùng HandlerMethodArgumentResolver để dựng tham số (@PathVariable, @RequestParam, @ModelAttribute, @RequestBody) và HandlerMethodReturnValueHandler để xử lý kết quả trả về.

Annotation của bạn được đọc ở đây: @Valid trong argument resolver, @ResponseBody trong return value handler. @Transactional không thuộc tầng này — nó là AOP proxy quanh service.

HttpMessageConverter và content negotiation

Converter được chọn theo hai câu hỏi: nó đọc được Content-Type này với target type này không, và ghi được media type này không. Danh sách được duyệt theo thứ tự, cái đầu tiên trả lời “được” sẽ thắng — đây là nguồn gốc của gần như mọi lỗi JSON khó hiểu.

@ResponseBody (hoặc @RestController) nghĩa là “ghi thẳng kết quả ra body qua converter”. Không có @ResponseBody thì String trả về là tên view, và ViewResolver mới là người render. Cùng một giá trị trả về, hai con đường hoàn toàn khác nhau. produces không thay đổi converter; nó chỉ thu hẹp mapping và bắt buộc response phải ghi được media type đó.

  • 406 — Accept không thỏa bất kỳ mapping nào, hoặc converter không ghi được type client chấp nhận. Sinh ra bởi handleNoMatch hoặc HttpMediaTypeNotAcceptableException.
  • 415 — Content-Type của body không có converter nào đọc được, hoặc consumes không khớp. Sinh ra bởi argument resolver cho @RequestBody.
  • 500 — không converter nào ghi được kết quả trả về. Đây là HttpMessageNotWritableException, không phải 406; client gửi Accept: */* vẫn nhận 500.

curl mặc định gửi Accept: */*, nên 406 thường chỉ lộ ra trên browser hoặc client đặt Accept cụ thể. Nếu API “chạy trên Postman nhưng hỏng trên frontend”, kiểm tra Accept trước.

Một request cụ thể: GET /api/orders/42

// File: src/main/java/com/example/shop/order/OrderController.java
package com.example.shop.order;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController                          // @Controller + @ResponseBody
@RequestMapping("/api/orders")
public class OrderController {

    private final OrderService orders;

    public OrderController(OrderService orders) {
        this.orders = orders;
    }

    @GetMapping(path = "/{id}", produces = "application/json")
    public OrderDto byId(@PathVariable long id) {
        return orders.find(id);          // DTO, khong phai ten view
    }
}
  1. Tomcat chuyển request cho DispatcherServlet đang map /.
  2. Servlet gọi getHandler(); RequestMappingHandlerMapping khớp path, method GET và produces, rồi dựng HandlerExecutionChain gồm handler và các interceptor khớp /api/**.
  3. Servlet chọn RequestMappingHandlerAdapter cho handler này.
  4. preHandle của interceptor chạy trước: gắn request ID, ghi log, kiểm tra quyền.
  5. Adapter resolve @PathVariable thành 42, gọi orders.find(42); kết quả là OrderDto.
  6. RequestResponseBodyMethodProcessor chọn JacksonJsonHttpMessageConverter, ghi JSON và đặt Content-Type: application/json.
  7. postHandle rồi afterCompletion chạy; response 200 về client.

Nếu orders.find(42) ném OrderNotFoundException, bước 6 không xảy ra: exception vào HandlerExceptionResolver, postHandle bị bỏ qua, chỉ afterCompletion chạy. Vì vậy logic đóng tài nguyên trong interceptor phải nằm ở afterCompletion.

Cấu hình qua WebMvcConfigurer

Boot dựng sẵn mapping, adapter, converter theo classpath, resource handler cho classpath:/static/, view resolver từ spring.mvc.view.*, multipart resolver và ba exception resolver. WebMvcConfigurer chỉ là các callback để chèn thêm interceptor, argument resolver, converter, CORS, resource handler, formatter, content negotiation và API versioning.

// File: src/main/java/com/example/shop/web/WebConfig.java
package com.example.shop.web;

import java.time.Duration;

import org.springframework.context.annotation.Configuration;
import org.springframework.http.CacheControl;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration                     // KHONG kem @EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

    private final RequestIdInterceptor requestIdInterceptor;

    public WebConfig(RequestIdInterceptor requestIdInterceptor) {
        this.requestIdInterceptor = requestIdInterceptor;
    }

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

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins("https://app.example.com")
                .allowedMethods("GET", "POST", "PUT", "DELETE");
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/assets/**")
                .addResourceLocations("classpath:/static/assets/")
                .setCacheControl(CacheControl.maxAge(Duration.ofHours(1)));
    }
}

Đừng thêm @EnableWebMvc trong Boot. Annotation đó import DelegatingWebMvcConfiguration, một WebMvcConfigurationSupport, và WebMvcAutoConfiguration chỉ chạy khi không có bean loại này. Kết quả: mất converter mặc định, resource handler, view resolver theo property và cả cách Boot xử lý lỗi. Chỉ cần @Configuration cộng WebMvcConfigurer.

Converter thì dùng API mới, và nhớ rằng addCustomConverter chèn converter của bạn trước bộ mặc định:

@Override
public void configureMessageConverters(HttpMessageConverters.ServerBuilder builder) {
    builder.addCustomConverter(new CsvOrderConverter());   // them, khong tat mac dinh
}

Versioning cấu hình ở cùng tầng: configureApiVersioning(configurer -> configurer.useRequestHeader("X-API-Version")), mặc định bằng spring.mvc.apiversion.default. Cách này thay cho việc nhét version vào path ở mọi controller.

Bốn thành phần còn lại, và một thành phần đã mất

ViewResolver

Nhiệm vụ duy nhất: đổi tên view logic thành View cụ thể. InternalResourceViewResolver ghép prefix/suffix cho JSP; Thymeleaf thay bằng ThymeleafViewResolver khi có starter. Với API JSON, thành phần này không tham gia.

MultipartResolver

Chỉ còn StandardServletMultipartResolver, dựa trên Part API của Servlet 6.1; CommonsMultipartResolver không còn trong spring-web 7.0.10. Boot tự cấu hình sẵn, và spring.servlet.multipart.resolve-lazily quyết định parse lúc vào servlet hay lúc argument resolver chạm MultipartFile.

LocaleResolver

Mặc định là AcceptHeaderLocaleResolver. Khi cần người dùng tự đổi ngôn ngữ, dùng LocaleChangeInterceptor cộng SessionLocaleResolver hoặc CookieLocaleResolver; LocaleContextResolver là bản mở rộng mang thêm time zone. Boot đọc spring.mvc.locale và spring.mvc.locale-resolver.

FlashMapManager

Flash attribute sống đúng một redirect: addFlashAttribute ghi vào FlashMap, SessionFlashMapManager giữ trong session, request sau khớp target path và query params thì đọc ra. Đổi host, đổi path (kể cả dấu /) hoặc mất session cookie là mất flash. Đừng đặt object lớn.

ThemeResolver

Đã bị loại bỏ cùng toàn bộ theme support ở Framework 7.0, nên không có ThemeResolver để cấu hình. Ứng dụng JSP cũ còn dùng theme phải ở lại Framework 6.x hoặc bỏ theme trước khi nâng cấp.

HandlerExceptionResolver và @ControllerAdvice

Ba resolver mặc định chạy theo thứ tự: ExceptionHandlerExceptionResolver xử lý @ExceptionHandler, ResponseStatusExceptionResolver xử lý @ResponseStatus và ResponseStatusException, DefaultHandlerExceptionResolver map exception chuẩn của MVC sang status (405, 406, 415, 400). @ControllerAdvice không phải cơ chế thứ tư: nó chỉ là nơi đăng ký @ExceptionHandler để resolver đầu tiên tìm thấy.

Nếu bạn tự viết một HandlerExceptionResolver, nó nằm trong cùng chain và thứ tự do Ordered quyết định. Không khai báo order thì đừng giả định nó chạy trước @ControllerAdvice. Và nhớ bật spring.mvc.log-resolved-exception=true khi debug: mặc định exception đã được xử lý không xuất hiện trong log, nên “handler chạy mà không thấy log” là hành vi bình thường.

Nếu muốn lỗi theo chuẩn RFC 9457, bật spring.mvc.problemdetails.enabled: response có type, title, status, detail thay vì body tự chế.

Năm lỗi cấu hình hay gặp

  • Hai mapping trùng path và method. RequestMappingHandlerMapping ném IllegalStateException lúc khởi động (“Ambiguous mapping”), kèm tên hai method. Đây là lỗi tốt vì fail fast; sửa bằng cách làm điều kiện khác nhau rõ ràng — thêm params, headers, consumes hoặc version.
  • Custom converter phá JSON. Converter khai báo application/json hoặc */* và được addCustomConverter đặt trước Jackson sẽ nuốt mọi response JSON; configureMessageConverters(List) cũ còn tắt đăng ký default. Giới hạn supportedMediaTypes ở một type lạ và test bằng Accept: application/json.
  • Interceptor không chạy cho error dispatch. Exception thoát ra container thì container dispatch sang /error; interceptor map /api/** không khớp path mới. Khi exception đã được resolve, postHandle cũng không chạy. Đừng đặt metrics hay audit trong interceptor rồi tưởng nó phủ mọi response — dùng afterCompletion hoặc Filter.
  • Lẫn @ControllerAdvice với HandlerExceptionResolver. Cả hai cùng chain, nên advice thắng một resolver không có order. Xử lý một exception ở hai nơi chỉ tạo ra response không đoán được.
  • Static resources che API. Resource handler mặc định /** tìm trong classpath:/static/; một file static/api/orders sẽ trả 200 cho GET /api/orders khi chưa có controller, che mất 404 thật. Đặt asset dưới /assets/** và kiểm tra spring.mvc.static-path-pattern trước khi đổi.

Cấu hình ở đâu

Việc cần làm Chỗ đặt Lưu ý
Thêm interceptor addInterceptors Path pattern quyết định phạm vi
Thêm argument resolver addArgumentResolvers Chỉ nên cho kiểu tham số riêng
Thêm hoặc thay converter configureMessageConverters(ServerBuilder) API List cũ đã deprecate
CORS addCorsMappings Đừng trộn với cấu hình ở gateway
Static resources addResourceHandlers Giữ sau controller mapping
Exception tập trung @RestControllerAdvice Resolver tự viết phải có order
API versioning configureApiVersioning Hoặc spring.mvc.apiversion.*
Multipart, locale Property hoặc bean Boot đã dựng sẵn default

Nhìn về 2027

Boot 4.2.0-RC2 và Framework 7.1.0-RC2 đang ở RC, chưa phải bản phát hành. Nhiều khả năng các method converter dạng List sẽ bị xóa trong 7.1 hoặc 8.0, nên code mới viết theo ServerBuilder ngay từ bây giờ. RestTemplate dự kiến nhận @Deprecated chính thức ở 7.1; client mới nên dùng RestClient hoặc HTTP interface. Theme đã biến mất vĩnh viễn.

Checklist

  • Biết rõ mapping khớp theo path, method, consumes, produces, version — không chỉ path.
  • Endpoint JSON có @ResponseBody hoặc @RestController; endpoint view thì trả tên view hợp lệ.
  • Converter tự viết giới hạn supportedMediaTypes, không dùng API List đã deprecate.
  • Không thêm @EnableWebMvc trong Boot; cấu hình qua WebMvcConfigurer thuần.
  • Interceptor dùng afterCompletion cho việc phải chạy cả khi lỗi; audit phủ rộng đặt ở Filter.

Nền tảng của bài này nằm ở Kiến trúc Spring MVC: DispatcherServlet và những người bạn và Spring MVC giải mã. Để hiểu vì sao những bean trên xuất hiện mà bạn không khai báo, đọc Spring Boot Autoconfiguration; bức tranh toàn series ở Spring Boot Roadmap.