web.xml 配置全解析：加載順序、核心元素與常見坑點

web.xml 配置全解析：加載順序、核心元素與常見坑點

web.xml 是 Java Web 應用的部署描述符，定義了 Servlet、Filter、Listener 等組件的配置與加載順序。本文系統梳理加載流程、核心元素用法，並通過一個生產環境故障案例揭示配置陷阱。

故障案例：Filter 映射缺失 Servlet 導致 NPE

項目在 WebSphere 8.5 部署報錯 NullPointerException，堆疊指向 WebAppFilterManager。排查發現 <filter-mapping> 引用了不存在的 <servlet-name>import</servlet-name>，而 WebSphere 8.5 啟動時會校驗所有 Filter 映射的 Servlet 存在性，導致啟動失敗。

教訓： <filter-mapping> 中的 <servlet-name> 必須在 <servlet> 中有對應定義，否則某些容器會拋出異常。

web.xml 加載順序

1. context-param：上下文初始化參數
2. listener：監聽器（如 Spring 的 ContextLoaderListener）
3. filter：過濾器（按 <filter-mapping> 順序鏈式調用）
4. servlet：Servlet（受 load-on-startup 控制優先級）

同類型組件調用順序遵循映射配置順序。

核心元素詳解

1. context-param

<context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>/WEB-INF/applicationContext.xml</param-value>
</context-param>

Servlet 中通過 getServletContext().getInitParameter() 獲取。

2. Filter 配置

<filter>
    <filter-name>encodingFilter</filter-name>
    <filter-class>com.example.EncodingFilter</filter-class>
    <init-param>
        <param-name>encoding</param-name>
        <param-value>UTF-8</param-value>
    </init-param>
</filter>
<filter-mapping>
    <filter-name>encodingFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

3. Listener 配置

<listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>

4. Servlet 配置

<servlet>
    <servlet-name>dispatcher</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/spring-mvc.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>dispatcher</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>

load-on-startup 為正整數時容器啟動時加載，數值越小優先級越高；負數或缺失則首次請求時加載。

5. 其他常用配置

• session-config：會話超時（分鐘）<session-timeout>30</session-timeout>
• welcome-file-list：默認歡迎頁
• error-page：按錯誤碼或異常類型映射錯誤頁
• mime-mapping：擴展名與 MIME 類型映射
• resource-ref：JNDI 資源引用（如數據源 jdbc/sample_db）
• security-constraint / login-config / security-role：安全認證授權

最佳實踐建議

• Filter 需使用 Spring Bean 時，改用 ContextLoaderListener 啟動 Spring 容器，確保 Bean 已就緒。
• 多 Filter 時嚴格控制 <filter-mapping> 順序，避免異常。
• Servlet 3.0+ 環境優先使用註解（@WebServlet、@WebFilter、@WebListener）減少 XML 配置。