Struts 2 核心 Filter 在 web.xml 中的完整配置詳解

web.xml 是 Web 應用的部署描述符，負責載入 Servlet、Filter、Listener 等組件。Struts 2 將核心控制器設計為 Filter 而非 Servlet，隨容器啟動自動初始化框架。

核心 Filter 類演進

建議：全面使用新版 StrutsPrepareAndExecuteFilter，支援更完整的攔截器棧與 Action 上下文準備。

標準配置模板

<filter>
    <filter-name>struts2</filter-name>
    <filter-class>org.apache.struts2.dispatcher.ng.filter.StrutsPrepareAndExecuteFilter</filter-class>
    
    <!-- 可選初始化參數 -->
    <init-param>
        <param-name>config</param-name>
        <param-value>struts-default.xml,struts-plugin.xml,struts.xml</param-value>
    </init-param>
    <init-param>
        <param-name>actionPackages</param-name>
        <param-value>com.example.action</param-value>
    </init-param>
    <!-- 配置 Struts 常量，等同 struts.xml 中 constant -->
    <init-param>
        <param-name>struts.devMode</param-name>
        <param-value>true</param-value>
    </init-param>
    <init-param>
        <param-name>struts.ui.theme</param-name>
        <param-value>simple</param-value>
    </init-param>
</filter>

<filter-mapping>
    <filter-name>struts2</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

關鍵參數解析

• config：逗號分隔的配置文件路徑，框架按序載入，後載入覆蓋先載入。預設載入 struts-default.xml、struts-plugin.xml、struts.xml。
• actionPackages：掃描 Action 類的包路徑（逗號分隔），配合約定優於配置插件使用。
• configProviders：自定義 ConfigurationProvider 實現類名，極少用。
• 其他常量：每個 <init-param> 直接映射一個 Struts 常量，param-name 為常量名，param-value 為值，優先級高於 struts.xml。

Filter 映射路徑：為何必須是 /*？

<url-pattern>/*</url-pattern> 攔截所有進入應用的請求，確保 Struts 2 攔截器棧（參數綁定、驗證、文件上傳、I18N 等）完整生效。若改為 /action/*，靜態資源雖可繞過，但會導致：

1. 非 /action/* 的 Action 請求 404。
2. 結果頁面（JSP/FreeMarker）轉發請求未經攔截器，失去參數綁定、國際化等功能。

靜態資源放行：在 struts.xml 配置 <constant name="struts.action.excludePattern" value=".*\\.(css|js|jpg|png|gif|ico)(\\?.*)?$"/>，而非修改 Filter 映射。

標籤庫自動載入 (Servlet 2.4+ / J2EE 1.4+)

容器符合 Servlet 2.4 規範（Tomcat 5.5+）會自動掃描 JAR META-INF/struts-tags.tld，無需在 web.xml 手動聲明 <taglib>。僅當使用極舊容器 (Servlet 2.3) 時需手動配置：

<taglib>
    <taglib-uri>/s</taglib-uri>
    <taglib-location>/WEB-INF/struts-tags.tld</taglib-location>
</taglib>

常見誤區

• 配置兩次 Filter：某教程誤導在 web.xml 同時配置 FilterDispatcher 和 StrutsPrepareAndExecuteFilter，會導致雙重攔截、參數綁定錯亂。
• 漏掉 filter-mapping：只定義 filter 不映射路徑，Filter 永不執行。
• 在 struts.xml 重複設常量：web.xml init-param 優先級更高，以此為準。