JavaWeb 原生开发 `web.xml` 配置讲义

（仅讲解 web\.xml 文件内的配置，含详细注释）

web\.xml 是 JavaWeb 原生开发的核心配置文件，位于 WEB\-INF/ 目录下，用于向服务器（Tomcat 等）描述应用的组件、规则和行为。

一、基本结构（必须掌握）

这是 web\.xml 的 “骨架”，所有配置都写在 \<web\-app\> 标签内。

<?xml version="1.0" encoding="UTF-8"?>
<!-- 根元素：声明这是一个 JavaWeb 应用，指定版本和命名空间（无需修改，直接复制） -->
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee 
                             http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
         version="4.0">

    <!-- 👇 所有具体配置都写在这里 👇 -->

</web-app>

二、常用配置项（含注释 + 例子）

1. 欢迎页面配置

配置访问应用根路径（如 http://localhost:8080/项目名/）时，默认展示的页面。

<!-- 欢迎页面列表：服务器会按从上到下的优先级查找 -->
<welcome-file-list>
    <!-- 优先级 1：先找 index.jsp -->
    <welcome-file>index.jsp</welcome-file>
    <!-- 优先级 2：没有 index.jsp 就找 index.html -->
    <welcome-file>index.html</welcome-file>
    <!-- 优先级 3：还可以是 Servlet 的访问路径（不用写 /） -->
    <welcome-file>home</welcome-file>
</welcome-file-list>

2. Servlet 配置（核心）

给 Servlet 起别名，并绑定访问 URL（告诉服务器 “访问哪个路径时调用这个 Servlet”）。

<!-- 第一步：定义 Servlet（像“给员工登记”） -->
<servlet>
    <!-- Servlet 的别名（随便起，但整个文件内唯一） -->
    <servlet-name>HelloServlet</servlet-name>
    <!-- Servlet 的完整类名（包名 + 类名，服务器通过它找到具体代码） -->
    <servlet-class>com.example.HelloServlet</servlet-class>
</servlet>

<!-- 第二步：绑定访问 URL（像“告诉前台，这个员工负责哪个窗口”） -->
<servlet-mapping>
    <!-- 和上面的 <servlet-name> 必须一致 -->
    <servlet-name>HelloServlet</servlet-name>
    <!-- 访问路径：http://localhost:8080/项目名/hello -->
    <url-pattern>/hello</url-pattern>
</servlet-mapping>

3. Filter 配置（过滤器）

用于拦截请求（如 “统一解决中文乱码”“检查登录状态”）。

<!-- 第一步：定义 Filter -->
<filter>
    <!-- Filter 的别名（唯一） -->
    <filter-name>EncodingFilter</filter-name>
    <!-- Filter 的完整类名 -->
    <filter-class>com.example.EncodingFilter</filter-class>
    
    <!-- 给 Filter 传初始化参数（可选） -->
    <init-param>
        <!-- 参数名 -->
        <param-name>encoding</param-name>
        <!-- 参数值 -->
        <param-value>UTF-8</param-value>
    </init-param>
</filter>

<!-- 第二步：绑定拦截路径 -->
<filter-mapping>
    <!-- 和上面的 <filter-name> 一致 -->
    <filter-name>EncodingFilter</filter-name>
    /* 表示拦截所有请求（包括 JSP、Servlet、静态资源） */
    <url-pattern>/*</url-pattern>
</filter-mapping>

4. 全局上下文参数配置

配置整个应用共享的参数（如数据库地址），所有 Servlet、Filter 都能读取。

<!-- 全局参数 1：数据库连接地址 -->
<context-param>
    <param-name>dbUrl</param-name>
    <param-value>jdbc:mysql://localhost:3306/test_db</param-value>
</context-param>

<!-- 全局参数 2：数据库用户名 -->
<context-param>
    <param-name>dbUser</param-name>
    <param-value>root</param-value>
</context-param>

5. 会话超时配置

设置用户会话（Session）的过期时间（单位：分钟）。

<session-config>
    <!-- 30 分钟后 Session 自动失效（不配置默认 30 分钟） -->
    <session-timeout>30</session-timeout>
</session-config>

6. 错误页面配置

配置出错时（如 404 页面找不到、500 服务器报错）展示的友好页面。

<!-- 场景 1：根据 HTTP 错误码配置 -->
<error-page>
    <!-- 404：页面找不到 -->
    <error-code>404</error-code>
    <!-- 错误页面路径（以 / 开头，代表项目根目录） -->
    <location>/error/404.jsp</location>
</error-page>

<error-page>
    <!-- 500：服务器内部错误 -->
    <error-code>500</error-code>
    <location>/error/500.jsp</location>
</error-page>

<!-- 场景 2：根据 Java 异常类型配置 -->
<error-page>
    <!-- 空指针异常 -->
    <exception-type>java.lang.NullPointerException</exception-type>
    <location>/error/npe.jsp</location>
</error-page>

7. 监听器配置（Listener）

用于监听应用的生命周期（如 “应用启动时初始化资源”）。

<!-- 直接配置监听器的完整类名即可，服务器会自动注册 -->
<listener>
    <listener-class>com.example.MyServletContextListener</listener-class>
</listener>

三、完整示例（可直接复制参考）

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee 
                             http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
         version="4.0">

    <!-- 1. 欢迎页面 -->
    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
        <welcome-file>index.html</welcome-file>
    </welcome-file-list>

    <!-- 2. Servlet 配置 -->
    <servlet>
        <servlet-name>HelloServlet</servlet-name>
        <servlet-class>com.example.HelloServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>HelloServlet</servlet-name>
        <url-pattern>/hello</url-pattern>
    </servlet-mapping>

    <!-- 3. 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>

    <!-- 4. 全局参数 -->
    <context-param>
        <param-name>dbUrl</param-name>
        <param-value>jdbc:mysql://localhost:3306/test_db</param-value>
    </context-param>
    <context-param>
        <param-name>dbUser</param-name>
        <param-value>root</param-value>
    </context-param>

    <!-- 5. 会话超时（20分钟） -->
    <session-config>
        <session-timeout>20</session-timeout>
    </session-config>

    <!-- 6. 错误页面 -->
    <error-page>
        <error-code>404</error-code>
        <location>/error/404.jsp</location>
    </error-page>
    <error-page>
        <error-code>500</error-code>
        <location>/error/500.jsp</location>
    </error-page>

</web-app>

（）

JavaWeb-web.xml详解