Servlets là Gì? Nền Tảng Vô Hình Giúp Spring MVC Vận Hành | Java Spring Roadmap

Bạn gắn một filter để thêm X-Request-Id, và các endpoint POST bắt đầu trả 415. Hoặc một servlet nhỏ ở /internal/build chạy đúng, nhưng @ControllerAdvice không bắt được lỗi. Cả hai là triệu chứng của cùng một hiểu sai: coi Servlet là di sản, còn Spring MVC chạy bên trên và không dính gì tới nó. Servlets là gì ở mức hợp đồng, và nó vẫn quyết định cách Spring MVC vận hành mỗi request.

Servlet API là tầng vận chuyển; Spring MVC là lớp triển khai trên đó. Tomcat không biết @RestController; nó chỉ biết ba phương thức vòng đời. Hiểu tầng dưới, bạn có địa chỉ cho lỗi 415, filter sai thứ tự và async treo.

Cập nhật 2026

  • Spring Boot 4.1.2 trên Spring Framework 7.0.10, Tomcat 11.0.x, Servlet 6.1, Jakarta EE 11. Chỉ còn jakarta.servlet; javax.servlet không được hỗ trợ.
  • spring-boot-starter-web deprecated ở 4.1; dùng spring-boot-starter-webmvc.
  • Không cần web.xml: ServletRegistrationBean, FilterRegistrationBean, ServletListenerRegistrationBean là đường chính. Boot 4.1 cũng có @ServletRegistration và @FilterRegistration.
  • Java 25 LTS và spring.threads.virtual.enabled=true làm virtual thread khả dụng, nhưng đổi chi phí thread, không đổi hợp đồng servlet.

Servlet là gì trong hợp đồng Jakarta EE 11

Servlet là một class Java implement jakarta.servlet.Servlet, do container quản lý. Bạn không new nó trong request, không gọi nó bằng tay, không viết main cho nó. Container tạo instance, gọi init, định tuyến request vào service, gọi destroy khi gỡ ứng dụng. Tomcat 11.0.x là mặc định của Boot 4.1.

Đơn vị được ánh xạ là registration: tên, URL pattern, init param; cùng class đăng ký hai lần tạo hai instance độc lập.

Với HTTP, bạn thường kế thừa jakarta.servlet.http.HttpServlet. Lớp này implement service để phân loại theo getMethod() và gọi doGet, doPost. Method chưa override trả 405, không phải 404.

Vòng đời: init, service, destroy

Ba pha, một instance cho mỗi registration, nhiều thread gọi service đồng thời. Đây là toàn bộ mô hình cần nhớ.

Pha Phương thức Khi nào và bao nhiêu lần
Khởi tạo init(ServletConfig) Một lần trước request đầu; sớm hơn nếu load-on-startup.
Phục vụ service(req, res) Mỗi request, có thể song song.
Kết thúc destroy() Một lần khi shutdown hoặc undeploy.

Đặt load-on-startup=1 cho servlet hạ tầng để lỗi init lộ ra lúc deploy thay vì ở request đầu tiên.

GenericServlet có hai mức init: init(ServletConfig) lưu config rồi gọi init() không tham số. Hãy override init() và dùng getInitParameter. Nếu override init(ServletConfig), bạn phải gọi super.init(config); quên một dòng là getServletContext() trả null và bạn nhận NullPointerException ở request đầu tiên.

Field chỉ nên chứa cấu hình bất biến set trong init; đừng giữ request hay buffer trong field vì instance dùng chung. Trạng thái theo request thuộc biến local hoặc request.setAttribute.

Request, response và ServletContext

HttpServletRequest là ảnh của request tại thời điểm gọi: method, URI, header, cookie, parameter, body, session, attribute. Hai điểm dễ sai:

  • getParameter() gộp query string và form body; lần gọi đầu có thể tiêu thụ body, sau đó getInputStream() có thể rỗng. Với JSON, dùng getInputStream hoặc getReader.
  • getSession() tạo session nếu chưa có; getSession(false) chỉ trả session đang tồn tại. Gọi getSession() trong filter logging có thể tạo session rỗng.

HttpServletResponse là nơi ghi status, header và body. getWriter() và getOutputStream() loại trừ nhau; gọi cả hai sẽ ném IllegalStateException. Response commit khi buffer đầy hoặc flush; sau đó setStatus, setHeader và sendError không còn tác dụng.

ServletContext là một object cho mỗi ứng dụng web, chia sẻ cho mọi servlet, filter và session. Nó cung cấp init param cấp ứng dụng, attribute toàn cục, getResource, getContextPath, và API addServlet/addFilter/addListener. ServletConfig là cấu hình riêng của một servlet; ServletContext là không gian chia sẻ của cả ứng dụng.

Filter, listener, async và multipart

Filter

jakarta.servlet.Filter có init, doFilter(req, res, chain), destroy. Nó chạy trước và sau servlet, có thể chặn chain bằng cách không gọi chain.doFilter, hoặc wrap request/response. Filter map theo URL pattern hoặc tên servlet, nên có thể chỉ áp cho DispatcherServlet.

Thứ tự filter là thứ tự thực thi: encoding trước filter đọc body, auth trước business. Với @WebFilter, spec không bảo đảm thứ tự giữa các annotation. Trong Boot, đặt @Order trên class filter hoặc implement Ordered, hay dùng FilterRegistrationBean.setOrder(int); @Order trên method @Bean không có tác dụng.

Listener

ServletContextListener chạy lúc context khởi tạo và hủy; HttpSessionListener theo vòng đời session; ServletRequestListener theo từng request. Listener là chỗ đúng để đăng ký tài nguyên cấp ứng dụng, đóng pool, ghi metric khởi động. Đừng đặt logic nghiệp vụ theo request ở đây: nó chạy trên thread container cho mọi request, kể cả static. Trong Boot, listener là bean tự đăng ký hoặc dùng ServletListenerRegistrationBean/@WebListener với @ServletComponentScan; nó được tạo rất sớm, nên cần bean khác thì dùng event của Spring.

Async servlet

request.startAsync() trả AsyncContext và cho container thu hồi thread trong khi bạn xử lý ở thread khác. Điều kiện: request/response chưa commit và servlet, filter trong chain khai báo async-supported. Kết thúc bằng asyncContext.complete() hoặc dispatch() để quay lại container. Luôn đặt setTimeout; async không bao giờ complete sẽ giữ kết nối đến hết timeout.

Async không biến code blocking thành non-blocking. Thread request được trả lại, nhưng tác vụ vẫn chiếm một thread executor, một connection DB và CPU. Spring MVC bọc mô hình này bằng Callable, DeferredResult, SseEmitter.

Multipart

Servlet 6.1 xử lý multipart/form-data qua @MultipartConfig và request.getPart("file") / getParts(). Part cho getInputStream, getSubmittedFileName, getSize và write ra thư mục tạm. Nếu servlet không có @MultipartConfig (hoặc registration không set MultipartConfigElement), getPart ném IllegalStateException; đây là lỗi cấu hình, không phải lỗi client.

Với Boot, spring.servlet.multipart.max-file-size mặc định 1MB và max-request-size mặc định 10MB, áp cho Spring MVC; servlet tự đăng ký không tự thừa hưởng. Vượt giới hạn thường thành 500 nếu không bắt và trả 413. File lớn nên stream từ Part.getInputStream() sang disk hoặc object storage, đừng getBytes() vào heap.

DispatcherServlet là một servlet, Spring MVC là lớp trên Servlet API

DispatcherServlet kế thừa FrameworkServlet, kế thừa HttpServlet. Boot đăng ký nó vào / — default mapping của container — nên request không khớp mapping cụ thể hơn đều vào đây: API, HTML, ảnh tĩnh, Actuator và cả error dispatch. Servlet của bạn map /internal/build là exact mapping, thắng /, nên nó chạy song song với Spring MVC mà không qua controller.

Browser → Tomcat 11 (connector + thread pool)
  → Filter chain (DispatcherType.REQUEST)
  → DispatcherServlet "/"   hoặc   servlet riêng (exact mapping)
  → HandlerMapping → HandlerAdapter → Controller
  → Service → Repository → HttpMessageConverter
  → HttpServletResponse → client

Tomcat chỉ thấy hợp đồng servlet: init/service/destroy, async, multipart, session, error dispatch. Nó không thấy @RequestMapping. Spring MVC thấy request qua HttpServletRequest, ghi response qua HttpServletResponse, rồi chia việc cho HandlerMapping, adapter, resolver và converter.

Ranh giới này giải thích nhiều hành vi: filter nằm ngoài DispatcherServlet nên exception trong filter không qua @ControllerAdvice; interceptor nằm trong nên thấy HandlerMethod; @RequestBody đọc body một lần ở converter, nên filter đọc trước sẽ làm controller nhận body rỗng. Mọi tính năng servlet vẫn là nền của Spring MVC, không bị thay thế.

Đăng ký servlet và filter trong Boot 4.1, không cần web.xml

Boot tự đăng ký bean Servlet, Filter, servlet Listener với container nhúng; filter map mặc định /*. Cần URL pattern, init param, load-on-startup, multipart config hay thứ tự thì dùng registration bean. Với annotation, @ServletComponentScan quét @WebServlet, @WebFilter, @WebListener; Boot 4.1 cũng có @ServletRegistration và @FilterRegistration.

Các property server.servlet.* (context-path, session.timeout, encoding.*, register-default-servlet) áp cho mọi servlet, kể cả DispatcherServlet, nên đổi context path sẽ đổi cả URL Actuator và servlet nội bộ. Multipart dùng spring.servlet.multipart.*; đường dẫn MVC dùng spring.mvc.servlet.path.

Ví dụ chạy được với spring-boot-starter-webmvc: một servlet trả build info và một filter gắn request id, không cần web.xml.

// File: src/main/java/shop/web/BuildInfoServlet.java
package shop.web;

import jakarta.servlet.http.*;
import java.io.IOException;

public class BuildInfoServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response)
            throws IOException {
        response.setContentType("application/json");
        response.setCharacterEncoding("UTF-8");
        response.getWriter().write("{\"build\":\"2026.11\"}");
    }
}
// File: src/main/java/shop/web/RequestIdFilter.java
package shop.web;

import jakarta.servlet.*;
import jakarta.servlet.http.*;
import org.slf4j.MDC;
import java.io.IOException;
import java.util.UUID;

public class RequestIdFilter implements Filter {

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {
        HttpServletRequest request = (HttpServletRequest) req;
        HttpServletResponse response = (HttpServletResponse) res;
        if (request.getDispatcherType() != DispatcherType.REQUEST) {
            chain.doFilter(req, res); // async/error: khong tao id moi
            return;
        }
        String id = request.getHeader("X-Request-Id");
        if (id == null || id.isBlank()) id = UUID.randomUUID().toString();
        request.setAttribute("requestId", id);
        response.setHeader("X-Request-Id", id);
        MDC.put("requestId", id);
        try {
            chain.doFilter(req, res);
        } finally {
            MDC.remove("requestId");
        }
    }
}
// File: src/main/java/shop/web/WebRegistrationConfig.java
package shop.web;

import jakarta.servlet.DispatcherType;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.boot.web.servlet.ServletRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;

@Configuration
public class WebRegistrationConfig {

    @Bean
    ServletRegistrationBean<BuildInfoServlet> buildInfoServlet() {
        var registration = new ServletRegistrationBean<>(new BuildInfoServlet(), "/internal/build");
        registration.setName("buildInfoServlet");
        registration.setLoadOnStartup(1);
        return registration;
    }

    @Bean
    FilterRegistrationBean<RequestIdFilter> requestIdFilter() {
        var registration = new FilterRegistrationBean<>(new RequestIdFilter());
        registration.addUrlPatterns("/*");
        // Sau encoding filter, truoc filter doc body; khong dat HIGHEST_PRECEDENCE.
        registration.setOrder(Ordered.HIGHEST_PRECEDENCE + 100);
        registration.setDispatcherTypes(DispatcherType.REQUEST);
        return registration;
    }
}

load-on-startup=1 làm servlet khởi tạo cùng ứng dụng, nên lỗi init lộ ra lúc deploy thay vì ở request đầu tiên. DispatcherType.REQUEST là mặc định; khai báo rõ ở đây để thấy filter không chạy lại trên async/error dispatch. Nếu cần filter chạy cả lúc error page, thêm DispatcherType.ERROR, và nhớ rằng response có thể đã commit trước đó.

Những bẫy thường gặp

Import javax.servlet

Framework 7 và Boot 4 không còn hỗ trợ javax.*. Triệu chứng là package javax.servlet does not exist hoặc cannot find symbol HttpServlet. Sửa toàn bộ import sang jakarta.servlet, kiểm tra dependency cũ mang theo javax.servlet-api, và đổi tên class trong web.xml cũ. Đừng thêm jakarta.servlet-api vào WAR: Tomcat đã cung cấp, đóng gói trùng có thể gây ClassCastException.

Thứ tự filter sai

Filter chạy theo order tăng dần. @Order trên method @Bean bị bỏ qua; đặt trên class filter, implement Ordered, hoặc dùng setOrder. Filter đọc body không nên đặt Ordered.HIGHEST_PRECEDENCE vì có thể chạy trước filter encoding của Boot. Filter auth phải trước filter business. Sai thứ tự thường thành header thiếu, lỗi font, hoặc body rỗng ở controller.

Đọc body trong filter

getInputStream chỉ đọc được một lần; getParameter trên form body cũng tiêu thụ stream. Nếu filter đọc trước, @RequestBody nhận body rỗng và ném HttpMessageNotReadableException. Dùng ContentCachingRequestWrapper bọc request trước khi chain chạy, cho controller đọc qua wrapper, và chỉ lấy getContentAsByteArray() sau chain.doFilter để log.

Blocking trong service()

Tomcat mặc định 200 request thread. Nếu mỗi request block 5 giây trên một HTTP call đồng bộ, 200 thread cạn sau vài chục request đồng thời, request sau xếp hàng dù CPU rảnh. Virtual thread giảm chi phí mỗi thread, không tăng connection DB, không tăng CPU, không đổi hợp đồng servlet. Đặt timeout cho mọi call ra ngoài và tách tác vụ dài sang executor có giới hạn hoặc message queue. Block trong filter còn giữ thread lâu hơn servlet.

JSP và web.xml: legacy, không phải mặc định 2026

JSP vẫn chạy trên Tomcat 11 nếu thêm Jasper và đóng gói WAR, nhưng không còn là lựa chọn cho dự án mới. JSP không chạy trong executable jar của Boot; Thymeleaf hợp với Spring MVC hơn. Coi JSP là legacy, chỉ giữ khi bảo trì ứng dụng cũ.

web.xml cũng vậy. Boot 4 không đọc web.xml cho ứng dụng nhúng; đăng ký servlet, filter, listener diễn ra bằng bean và ServletContextInitializer. Deploy WAR vào Tomcat ngoài bằng SpringBootServletInitializer là mô hình legacy. Tài liệu mở đầu bằng <web-app> nên được thay bằng registration bean.

2027: hợp đồng servlet đứng yên, cách bạn dùng nó thì đổi

Servlet 6.1 đi cùng Jakarta EE 11 và còn là baseline của Boot 4.x. Thay đổi đáng chú ý nằm ở tầng thread: Java 25 LTS là baseline production, Java 27 là feature release không LTS, Boot 4.1 chạy cả hai. Virtual thread final từ Java 21; spring.threads.virtual.enabled=true làm việc chờ rẻ hơn nhưng không đổi vòng đời servlet hay làm service() non-blocking.

Structured concurrency vẫn preview ở Java 27, đừng đưa vào thiết kế production. Theo dõi cách container tận dụng virtual thread cho async và các bản vá Tomcat 11.0.x; hợp đồng ba phương thức không đổi.

Checklist trước khi thêm servlet hoặc filter

  • Xác định rõ servlet này có cần tồn tại ngoài Spring MVC không; nếu chỉ là endpoint nghiệp vụ, dùng @RestController.
  • Đặt tên và load-on-startup cho servlet hạ tầng để log, metric, debug dễ đọc.
  • Đặt order tường minh cho filter; filter đọc body phải sau encoding và dùng ContentCachingRequestWrapper.
  • Kiểm tra toàn bộ import là jakarta.servlet, và không đóng gói jakarta.servlet-api vào artifact deploy.
  • Đặt timeout cho async và mọi call mạng; không block trong service() hay filter.
  • Nếu dùng multipart, set MultipartConfigElement trên registration và trả 413 thay vì 500.

Đọc tiếp