Tomcat Servlet 映射匹配流程詳解

Tomcat Servlet 映射匹配流程詳解

Tomcat 容器在接收到 HTTP 請求後，如何根據 web.xml 或註解配置的 @WebServlet 找到對應的 Servlet 實例？本文通過流程圖解析核心匹配邏輯。

匹配流程圖

核心匹配規則（按優先級降序）

1. 精確匹配：<url-pattern>/api/users</url-pattern> → 請求路徑 /api/users 完全一致。
2. 路徑前綴匹配：<url-pattern>/api/*</url-pattern> → 請求路徑以 /api/ 開頭，最長前綴優先。
3. 擴展名匹配：<url-pattern>*.do</url-pattern> → 請求路徑以 .do 結尾。
4. 默認 Servlet：<url-pattern>/</url-pattern> → 以上均不匹配時，由默認 Servlet（DefaultServlet）處理靜態資源/轉發。

關鍵源碼類

• org.apache.tomcat.util.http.mapper.Mapper：核心映射器，構建路由樹。
• org.apache.catalina.mapper.MapperContext：上下文容器，保存 Host/Context 級映射。
• org.apache.catalina.core.StandardContext：Web 應用上下文，初始化時註冊 Servlet 映射。

匹配算法要點

• 採用 Trie 樹 (前綴樹) 存儲路徑映射，實現 O(m) 查找（m 為路徑深度）。
• 同一 Context 內，精確匹配 > 最長前綴匹配 > 擴展名匹配 > 默認匹配。
• 多個相同模式按聲明順序（web.xml 順序或類加載順序）取第一個。
• 大小敏感取決於 <property name="mapperContextRootRedirectEnabled" value="true"/> 及 OS 文件系統特性。

實戰調試技巧

1. 啟用 Tomcat 訪問日誌：server.xml 中 <Valve className="org.apache.catalina.valves.AccessLogValve" .../>。
2. 添加 org.apache.tomcat.util.http.mapper 包 DEBUG 級日誌，觀察匹配詳情。
3. 使用 curl -v 或 Postman 發送測試請求，對比響應 Header 中的 X-Powered-By、Server 等信息。

常見誤區

• /* 會匹配所有路徑包括 /，導致默認 Servlet 失效，靜態資源 404。
• / 僅匹配未被其他模式匹配的請求，不等同於 /*。
• Spring MVC 的 DispatcherServlet 通常映射為 /，配合 <mvc:default-servlet-handler/> 轉發靜態資源。