web.xml 配置全解析：核心元素詳解、Servlet/Filter/Listener 註冊、安全認證、會話控制與部署描述符最佳實踐

部署描述符文件結構

web.xml 是 Java Web 應用的部署描述符，遵循 Servlet 規範 DTD。文件順序敏感：XML 聲明 → DOCTYPE → <web-app> 根元素 → 子元素按規範定義順序排列。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
  "https://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
  <!-- 子元素順序：icon? display-name? description? context-param* filter* filter-mapping* listener* servlet* servlet-mapping* session-config? mime-mapping* welcome-file-list? error-page* taglib* resource-env-ref* resource-ref* security-constraint* login-config? security-role* env-entry* ejb-ref* ejb-local-ref* -->
</web-app>

核心元素詳解與配置示例

1. Servlet 註冊與映射

<servlet>
  <servlet-name>TestServlet</servlet-name>
  <servlet-class>moreservlets.TestServlet</servlet-class>
  <init-param>
    <param-name>param1</param-name>
    <param-value>value1</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup> <!-- 啟動時加載 -->
</servlet>
<servlet-mapping>
  <servlet-name>TestServlet</servlet-name>
  <url-pattern>/test</url-pattern>
</servlet-mapping>

2. JSP 初始化參數（使用 jsp-file 替代 servlet-class）

<servlet>
  <servlet-name>InitPage</servlet-name>
  <jsp-file>/InitPage.jsp</jsp-file>
  <init-param><param-name>firstName</param-name><param-value>Bill</param-value></init-param>
</servlet>
<servlet-mapping>
  <servlet-name>InitPage</servlet-name>
  <url-pattern>/InitPage.jsp</url-pattern> <!-- 覆蓋默認訪問路徑 -->
</servlet-mapping>

3. 應用級初始化參數

<context-param>
  <param-name>support-email</param-name>
  <param-value>admin@company.com</param-value>
</context-param>
<!-- ServletContext.getInitParameter("support-email") 獲取 -->

4. Filter 過濾器鏈

<filter>
  <filter-name>EncodingFilter</filter-name>
  <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
  <init-param><param-name>encoding</param-name><param-value>UTF-8</param-value></init-param>
  <init-param><param-name>forceEncoding</param-name><param-value>true</param-value></init-param>
</filter>
<filter-mapping>
  <filter-name>EncodingFilter</filter-name>
  <url-pattern>/*</url-pattern> <!-- 或指定 servlet-name -->
</filter-mapping>

5. Listener 監聽器

<listener>
  <listener-class>com.example.SessionListener</listener-class>
</listener>

6. 歡迎頁面列表

<welcome-file-list>
  <welcome-file>index.jsp</welcome-file>
  <welcome-file>index.html</welcome-file>
</welcome-file-list>

7. 錯誤頁面映射

<error-page>
  <error-code>404</error-code>
  <location>/error/404.jsp</location>
</error-page>
<error-page>
  <exception-type>java.lang.Exception</exception-type>
  <location>/error/500.jsp</location>
</error-page>

8. 安全約束與認證

<security-constraint>
  <web-resource-collection>
    <web-resource-name>AdminArea</web-resource-name>
    <url-pattern>/admin/*</url-pattern>
  </web-resource-collection>
  <auth-constraint>
    <role-name>admin</role-name>
  </auth-constraint>
  <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee> <!-- 強制 HTTPS -->
  </user-data-constraint>
</security-constraint>

<login-config>
  <auth-method>FORM</auth-method>
  <form-login-config>
    <form-login-page>/login.jsp</form-login-page>
    <form-error-page>/login-error.jsp</form-error-page>
  </form-login-config>
</login-config>

<security-role><role-name>admin</role-name></security-role>

9. 會話超時配置

<session-config>
  <session-timeout>30</session-timeout> <!-- 分鐘 -->
</session-config>

10. MIME 類型映射（文件下載）

<mime-mapping><extension>pdf</extension><mime-type>application/pdf</mime-type></mime-mapping>
<mime-mapping><extension>xls</extension><mime-type>application/vnd.ms-excel</mime-type></mime-mapping>
<mime-mapping><extension>doc</extension><mime-type>application/msword</mime-type></mime-mapping>

文檔化元素（IDE 工具友好）

<icon><small-icon>/images/app_16.png</small-icon><large-icon>/images/app_32.png</large-icon></icon>
<display-name>MyWebApp</display-name>
<description>企業級 Web 應用示例</description>

最佳實踐清單

1. 順序合規：嚴格遵循 DTD 定義的子元素順序，避免容器解析失敗；
2. Filter 置頂：編碼、安全等全局過濾器映射 /* 應在最前；
3. 負載均衡預熱：關鍵 Servlet 配置 load-on-startup；
4. 安全最小化：auth-constraint 僅授權必要角色，transport-guarantee 強制敏感路徑 HTTPS；
5. 錯誤頁友好：為 404/500/通用異常配置友好提示頁，避免洩露堆棧信息；
6. 會話超時：根據業務安全性設置 session-timeout，預設 30 分鐘。

掌握 web.xml 核心配置，是從「能跑通」邁向「工程化、可維護、可擴展」Java Web 開發的必經之路。