Servlet 3.0+ @WebServlet 註解完整指南：替代 web.xml 的零配置映射

Servlet 3.0+ @WebServlet 註解完整指南

Servlet 3.0 引入註解配置，徹底擺脫繁瑣的 web.xml 映射。本文系統講解 @WebServlet 全屬性用法、多 URL 映射、啟動加載順序、異步處理配置及與 web.xml 混合部署的優先級規則。

一、基礎用法：單 URL 映射

@WebServlet("/hello.do")
public class HelloServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        resp.getWriter().write("Hello, Annotation!");
    }
}

• 等價於 <servlet-mapping><url-pattern>/hello.do</url-pattern></servlet-mapping>；
• 類名默認作為 servlet-name（全限定名），可通過 name 屬性覆蓋。

二、完整屬性速查表

三、進階配置示例

@WebServlet(
    name = "OrderServlet",
    urlPatterns = { "/order/create", "/order/query", "/order/*" },
    loadOnStartup = 1,
    initParams = {
        @WebInitParam(name = "pageSize", value = "20"),
        @WebInitParam(name = "maxRetries", value = "3")
    },
    asyncSupported = true,
    description = "訂單核心處理 Servlet"
)
public class OrderServlet extends HttpServlet {
    private int pageSize;
    private int maxRetries;

    @Override
    public void init() throws ServletException {
        pageSize = Integer.parseInt(getInitParameter("pageSize"));
        maxRetries = Integer.parseInt(getInitParameter("maxRetries"));
    }

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        // 異步處理示例
        AsyncContext ctx = req.startAsync();
        ctx.start(() -> {
            try { Thread.sleep(2000); } catch (InterruptedException ignored) {}
            ctx.getResponse().getWriter().write("Async Done");
            ctx.complete();
        });
    }
}

四、URL 模式匹配規則（與 web.xml 一致）

1. 精確匹配：/order/create 只匹配該路徑；
2. 路徑前綴：/order/* 匹配 /order/ 及其子路徑；
3. 擴展名映射：*.do、*.action 匹配對應後綴；
4. 默認 Servlet：/ 匹配所有未被其他模式匹配的請求（靜態資源通常由 DefaultServlet 處理）。

優先級：精確 > 最長前綴 > 擴展名 > 默認。

五、與 web.xml 混合部署的優先級

• Servlet 3.0 規範：web.xml 中的 <servlet>、<servlet-mapping> 覆蓋 註解配置；
• web.xml 中 <absolute-ordering> 可控制掃描順序，甚至禁用註解掃描（<absolute-ordering/> 空標籤）；
• 建議：全項目統一風格，新項目全註解，遺留項目全 XML，避免混用導致維護混亂。

六、常見坑與避坑指南

七、最佳實踐總結

1. 核心業務 Servlet：loadOnStartup=1 預熱，減少首請求延遲；
2. 異步長連接 Servlet：asyncSupported=true + 線程池異步執行；
3. 參數外部化：initParams 僅放極少數不變常量，業務配置走 Spring @Value/Nacos；
4. 命名規範：name 使用業務語義（如 OrderCreateServlet），便於監控與管理；
5. 測試驗證：啟動後訪問 https://host:port/manager/html (Tomcat Manager) 查看 Servlet 註冊表，確認映射生效。

「註解配置讓 Servlet 成為真正的 POJO 組件，零 XML 侵入。善用 loadOnStartup 預熱、asyncSupported 異步，能讓 Servlet 容器在高併發下跑出非阻塞的性能。」