Skip to content

Servlet-基础 ​

[TOC]

概述 ​

Java Servlet(全称 Server Applet,意为“运行在服务器端的小程序”) 是 Java EE(现 Jakarta EE)规范体系中最核心的 Web 组件技术。它运行在支持 Java 的 Web 服务器或应用服务器中,专门用于接收客户端发起的 HTTP 请求、调度后端业务逻辑,并动态生成 HTTP 响应报文返回给客户端。

在静态 Web 时代,HTTP 服务器只能直接读取磁盘上的静态 HTML 文件原样返回;而 Servlet 的出现使 Java 具备了根据请求参数、用户会话状态及数据库实时数据动态构建响应内容的能力,同时也是 Spring MVC 等现代 Java Web 框架的底层基石(例如 Spring MVC 的核心入口 DispatcherServlet 本质上就是一个标准的 Servlet 实现)。

规范演进与命名空间 ​

随着 Java EE 移交至 Eclipse 基金会并正式更名为 Jakarta EE,Servlet 规范经历了包命名空间的重大迁移。在阅读源码或引入依赖时,需根据容器版本区分以下两个发展阶段:

规范阶段代表版本核心包名(Package)匹配的 Tomcat 版本最低 JDK 要求
Java EE 阶段Servlet 2.5 / 3.0 / 3.1 / 4.0javax.servlet.*Tomcat 7.x ~ 9.xJDK 6 ~ JDK 8
Jakarta EE 阶段Jakarta Servlet 5.0 / 6.0 / 6.1jakarta.servlet.*Tomcat 10.1.x ~ 11.xJDK 11 / JDK 17 / JDK 21

除顶层包名由 javax.servlet 变更为 jakarta.servlet(以及移除如 SingleThreadModel 等早期废弃接口)外,Servlet 的核心架构、生命周期机制与 API 方法签名均保持高度一致。

Web 容器 ​

Servlet 类不包含 main 方法,无法由 JVM 直接独立启动,必须部署并运行在 Web 容器(Web Container,又称 Servlet 容器) 中。常见的 Web 容器包括 Apache Tomcat、Eclipse Jetty、Undertow 等。

Web 容器作为宿主环境,在底层接管了繁琐的网络与系统级工作,使业务开发者只需专注于编写请求处理逻辑:

  1. 网络通信支持:容器负责监听指定网络端口(如 8080)、管理底层 TCP Socket 连接、解析原始 HTTP 请求字节流,并将响应数据重新编码为符合 HTTP 协议规范的报文发送回客户端。

  2. 生命周期管理:容器全权负责 Servlet 类的加载、反射实例化、初始化(init)、请求服务调用(service)以及卸载前的资源销毁(destroy)。

  3. 路由映射解析:容器根据客户端请求的 URL 路径,检索 web.xml 部署描述符或 @WebServlet 注解配置,将请求精准路由至目标 Servlet 实例。

  4. 多线程并发调度:容器内部维护工作线程池(Thread Pool),每当有新请求到达时自动分配独立线程并发执行,避免频繁创建与销毁线程带来的性能开销。

请求处理流程 ​

当客户端(浏览器或 HTTP 客户端)向服务器发起请求时,Web 容器与 Servlet 实例之间遵循标准化的协作流程。

完整请求与响应的 UML 时序交互关系如下图所示:

image-20261029154714072

整个协作过程按时间顺序分为以下 6 个核心步骤:

  1. 发起 HTTP 请求:客户端通过网络向 Web 服务器发起 HTTP 请求(例如 GET /hello)。

  2. 线程分配与路由解析:Web 容器接收到请求报文后,从内部线程池中分配一个工作线程,并根据请求的 URL 路径查找映射表(Mapping Resolver),定位到负责处理该路径的目标 Servlet。若目标 Servlet 尚未实例化,容器会在此刻完成类的加载、反射创建实例并调用 init() 方法初始化。

  3. 创建请求与响应对象:容器针对本次 HTTP 请求,在内存中创建一个 HttpServletRequest 对象(封装请求行、请求头、请求参数及输入流)和一个 HttpServletResponse 对象(封装响应状态码、响应头及输出流)。

  4. 调用 service 派发业务:工作线程调用目标 Servlet 实例的 service(ServletRequest, ServletResponse) 方法,并将创建好的请求与响应对象作为参数传入;HttpServlet 内部进一步根据请求方式(如 GET 或 POST)派发至子类重写的 doGet() 或 doPost() 方法。

  5. 读写数据与设置响应:在 doXxx() 方法内部,开发者通过 HttpServletRequest 读取客户端提交的数据,调用后端业务服务,并通过 HttpServletResponse 设置响应头、状态码以及写入响应正文(如通过 response.getWriter() 写入动态内容)。

  6. 返回响应与销毁回收:当 service() 方法执行结束返回后,容器将响应缓冲区中的数据封装为标准 HTTP 响应报文写回客户端,随后立即销毁(或清空回收)本次请求的 HttpServletRequest 与 HttpServletResponse 对象,并将工作线程归还至线程池等待下一个请求。

标准开发流程 ​

在实际项目中开发一个标准的 Servlet 组件,通常包含引入规范依赖、编写并注册 Servlet 类、打包部署三个步骤。

Maven 依赖配置 ​

在基于 Maven 构建的 Java Web 项目中,首先需要引入 Servlet 规范的官方 API 依赖。由于 Tomcat 等 Web 容器自身的 lib 目录下已经内置了 Servlet 规范的运行期实现包,因此依赖的 <scope> 必须声明为 provided,防止打包时将 API Jar 包重复打入 WEB-INF/lib 目录而引发类加载冲突。

xml
<!-- 1. 引入 Jakarta Servlet 官方规范 API 依赖 -->
<!-- Jakarta EE 9 及以上版本统一使用 jakarta.servlet 命名空间 -->
<dependency>
  <groupId>jakarta.servlet</groupId>
  <artifactId>jakarta.servlet-api</artifactId>
  <version>6.0.0</version>

  <!-- 2. 必须将依赖作用域声明为 provided -->
  <!-- 编译期有效,打包 WAR 时排除,运行期由 Tomcat 等容器自身提供实现 -->
  <scope>provided</scope>
</dependency>

编写与注册组件 ​

自定义业务 Servlet 时,标准做法是继承 jakarta.servlet.http.HttpServlet 抽象类,按需重写 doGet 或 doPost 方法,并在类声明上方使用 @WebServlet 注解绑定访问路径。

java
// 1. 使用 @WebServlet 注解注册组件并绑定访问路径
// 自定义类需继承 HttpServlet 抽象类以复用 HTTP 协议派发能力
@WebServlet("/hello")
public class HelloServlet extends HttpServlet {

  // 2. 重写 doGet 方法处理客户端发起的 HTTP GET 请求
  // 容器自动传入封装好的 HttpServletRequest 与 HttpServletResponse 对象
  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp)
      throws ServletException, IOException {
    // 3. 从请求对象中读取客户端传递的查询参数
    // 例如访问 /hello?name=Java 时返回 "Java"
    String name = req.getParameter("name");

    // 4. 设置响应内容类型与字符集并输出动态响应体
    // 通过 getWriter() 获取字符输出流向客户端写回数据
    resp.setContentType("text/plain;charset=UTF-8");
    resp.getWriter().write("Hello, " + (name != null ? name : "Servlet"));
  }
}

部署与访问 ​

完成代码编写后,将项目编译打包并部署至 Web 容器即可对外提供服务:

  1. 编译打包:通过构建工具(如 mvn clean package)将工程打包为标准的 .war(Web Application Archive)归档文件。

  2. 容器部署:将生成的 .war 包放置到 Tomcat 容器的 webapps 目录下。容器启动时会自动解压该归档包,扫描字节码中的 @WebServlet 注解并建立路由映射表。

  3. 客户端访问:打开浏览器访问 http://localhost:8080/<应用上下文路径>/hello?name=Java,即可触发 HelloServlet.doGet 方法并接收到服务端返回的 Hello, Java 响应文本。

Servlet 接口架构 ​

Java Servlet 规范通过一套层次分明的接口与抽象类体系,将底层容器契约、通用协议骨架与 HTTP 协议实现进行解耦。开发者在编写业务 Servlet 时,通常无需直接实现顶层接口,而是继承处于体系末端的抽象类。

继承体系层次 ​

Servlet 核心架构由顶层接口、通用抽象类与协议专用抽象类三层结构组成,同时辅以配置接口与序列化接口:

  1. 顶层契约层(Servlet):定义所有 Servlet 必须遵守的生命周期方法与请求处理入口,不绑定任何具体网络协议。

  2. 通用骨架层(GenericServlet):实现 Servlet 与 ServletConfig 接口,提供与具体协议无关的默认骨架实现,简化配置对象的保存与初始化流程。

  3. 协议实现层(HttpServlet):继承 GenericServlet,专门针对 HTTP 协议进行扩展,将通用的 service 调用拆解为按 GET、POST 等 HTTP 动词分发的模板方法。

核心类与接口之间的 UML 继承与实现关系如下:

image-20261029154116910

Servlet ​

jakarta.servlet.Servlet(早期版本为 javax.servlet.Servlet)是整个体系的根接口,规定了 Web 容器与服务端组件交互的标准契约。容器仅面向该接口管理组件生命周期并派发请求。

接口共声明 5 个核心方法,按职责可分为三类:

  1. 生命周期管理:init(ServletConfig) 负责初始化资源,destroy() 负责在卸载前释放资源。

  2. 请求处理入口:service(ServletRequest, ServletResponse) 负责接收并处理每次客户端请求。

  3. 元数据获取:getServletConfig() 返回当前实例的配置对象,getServletInfo() 返回版权、版本等描述文本。

如果业务类直接实现 Servlet 接口,必须手动实现全部 5 个方法,并自行维护 ServletConfig 成员变量,代码较为繁琐。

GenericServlet ​

jakarta.servlet.GenericServlet 是针对 Servlet 接口提供的协议无关抽象实现类,采用适配器模式屏蔽了顶层接口中不常修改的样板方法。

GenericServlet 在架构中承担以下核心职责:

  1. 聚合配置功能:同时实现 Servlet 与 ServletConfig 接口,内部持有一个 ServletConfig 类型的成员变量,并将 getServletContext()、getInitParameter() 等方法直接委托给该成员变量执行。

  2. 解耦初始化逻辑:提供双 init 重载机制,避免子类在重写初始化逻辑时因遗漏 super.init(config) 而导致配置对象丢失。

  3. 保留业务抽象:将 service(ServletRequest, ServletResponse) 声明为抽象方法,留待具体协议子类实现。

    java
    // 1. 容器调用带参 init 方法传入配置对象
    // 将 ServletConfig 保存为成员变量并调用无参重载方法
    @Override
    public void init(ServletConfig config) throws ServletException {
      this.config = config;
      this.init();
    }
    
    // 2. 供子类重写的无参初始化钩子方法
    // 避免子类因重写带参方法而遗漏 super.init(config)
    public void init() throws ServletException {
      // 默认空实现
    }

HttpServlet ​

jakarta.servlet.http.HttpServlet 继承自 GenericServlet,是专为 HTTP 协议设计的抽象类。虽然该类不包含任何抽象方法,但声明为 abstract,旨在强制开发者通过继承并重写特定 HTTP 方法来编写业务逻辑。

service ​

HttpServlet 采用模板方法模式,通过两个重载的 service 方法完成了从通用请求到 HTTP 细分方法的路由派发:

  1. 公有入口方法:public void service(ServletRequest, ServletResponse) 实现自顶层接口,负责将通用的请求与响应对象强制向下转型为 HttpServletRequest 和 HttpServletResponse,随后调用受保护的重载方法。

  2. 受保护派发方法:protected void service(HttpServletRequest, HttpServletResponse) 通过 req.getMethod() 获取 HTTP 请求方式(如 GET、POST、PUT、DELETE),并分发至对应的 doXxx 方法。

    java
    // 1. 实现顶层 Servlet 接口的入口方法
    // 将通用请求与响应向下转型为 HTTP 协议专用类型
    @Override
    public void service(ServletRequest req, ServletResponse res)
        throws ServletException, IOException {
      if (!(req instanceof HttpServletRequest && res instanceof HttpServletResponse)) {
        throw new ServletException("non-HTTP request or response");
      }
      HttpServletRequest request = (HttpServletRequest) req;
      HttpServletResponse response = (HttpServletResponse) res;
      service(request, response);
    }
    
    // 2. 重载的 HTTP 专用派发方法
    // 提取请求方式并路由至对应的 doXxx 方法
    protected void service(HttpServletRequest req, HttpServletResponse resp)
        throws ServletException, IOException {
      String method = req.getMethod();
    
      // 3. 根据 HTTP 动词执行分支调用
      if (method.equals("GET")) {
        doGet(req, resp);
      } else if (method.equals("POST")) {
        doPost(req, resp);
      } else if (method.equals("PUT")) {
        doPut(req, resp);
      } else if (method.equals("DELETE")) {
        doDelete(req, resp);
      } else {
        resp.sendError(HttpServletResponse.SC_NOT_IMPLEMENTED);
      }
    }

doGet ​

在 HttpServlet 中,doGet、doPost、doPut、doDelete 等方法均提供了默认实现。为了保证安全性,这些默认实现不会执行任何业务操作,而是直接向客户端返回 405 Method Not Allowed(HTTP/1.1 及以上)或 400 Bad Request(HTTP/1.0)错误状态码。

java
// 1. HttpServlet 中 doGet 的默认实现逻辑
// 子类未重写时拒绝请求并返回错误状态码
protected void doGet(HttpServletRequest req, HttpServletResponse resp)
    throws ServletException, IOException {
  String protocol = req.getProtocol();
  String msg = "HTTP method GET is not supported by this URL";

  // 2. 根据 HTTP 协议版本返回 405 或 400 状态码
  if (protocol.endsWith("1.1")) {
    resp.sendError(HttpServletResponse.SC_METHOD_NOT_ALLOWED, msg);
  } else {
    resp.sendError(HttpServletResponse.SC_BAD_REQUEST, msg);
  }
}

因此,自定义 Servlet 继承 HttpServlet 时需遵循以下开发规范:

  1. 按需重写 doXxx:若业务需要处理 GET请求,则必须重写doGet方法;若未重写对应的doXxx方法而客户端发起了该类型的请求,容器就会走父类默认逻辑并返回405 状态码。

  2. 禁止调用 super.doXxx(req, resp):在子类重写的 doGet或doPost方法中,严禁保留 IDE 自动生成的super.doGet(req, resp)调用,否则请求依然会触发父类的sendError 逻辑,导致响应被直接拦截并报错。

  3. 避免直接重写 service:除非需要统一拦截所有类型的 HTTP 请求并放弃按动词分发、缓存头(如 Last-Modified的HEAD/GET检查)等内置特性,否则不应重写service 方法。

API: Servlet ​

生命周期管理 ​

  • void init():(ServletConfig config),组件初始化。由 Web 容器在 Servlet 实例化完成后立即调用一次,用于接收并保存 ServletConfig 配置对象以及加载前置系统资源;唯有该方法成功执行完毕后,容器才会向该实例派发客户端请求。

  • void destroy():(),组件销毁。由 Web 容器在卸载当前 Servlet 实例前调用一次,用于关闭外部连接、中断后台任务并释放已分配的底层系统资源。

注意事项:

  1. init() 和 destroy() 在单个 Servlet 实例的整个生命周期中均严格只被 Web 容器调用一次。
  2. 若 init() 执行期间抛出 ServletException 或其子类 UnavailableException,容器将判定初始化失败并直接废弃该实例,既不会向其派发请求,也不会调用其 destroy() 方法。
  3. 容器在调用 destroy() 前会等待当前正在执行 service() 的工作线程处理完毕或达到预设超时时间;一旦 destroy() 执行结束,容器将不再向该实例派发任何新请求。
java
import jakarta.servlet.Servlet;
import jakarta.servlet.ServletConfig;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;

public class ServletLifecycleDemo {

  static class CustomServlet implements Servlet {

    private ServletConfig config;
    private boolean resourceLoaded;

    @Override
    public void init(ServletConfig config) throws ServletException {
      // 1. 容器调用 init 传入配置对象并加载初始化资源
      this.config = config;
      this.resourceLoaded = true;
      System.out.println("Servlet initialized, resourceLoaded = " + this.resourceLoaded);
    }

    @Override
    public void destroy() {
      // 2. 容器卸载实例前调用 destroy 释放底层资源
      this.resourceLoaded = false;
      this.config = null;
      System.out.println("Servlet destroyed, resourceLoaded = " + this.resourceLoaded);
    }

    @Override
    public void service(ServletRequest req, ServletResponse res) {}

    @Override
    public ServletConfig getServletConfig() { return this.config; }

    @Override
    public String getServletInfo() { return "CustomServlet"; }
  }

  public static void main(String[] args) throws ServletException {
    Servlet servlet = new CustomServlet();

    // 3. 模拟 Web 容器触发 Servlet 初始化阶段
    servlet.init(null);

    // 4. 模拟 Web 容器触发 Servlet 销毁阶段
    servlet.destroy();
  }
}

请求处理 ​

  • void service():(ServletRequest req, ServletResponse res),请求处理入口。由 Web 容器在每次接收到匹配路由的客户端请求时调用,通过传入的 ServletRequest 读取客户端请求数据,执行业务逻辑后通过 ServletResponse 向客户端写回响应结果。

注意事项:

  1. 容器必须在 init() 方法成功执行完毕后,才会调用 service() 方法处理客户端请求。
  2. 由于容器默认采用单例多线程模型管理 Servlet,多个工作线程会并发调用同一个实例的 service() 方法,因此在方法内部访问实例成员变量或共享资源时必须自行保障线程安全。
java
import jakarta.servlet.Servlet;
import jakarta.servlet.ServletConfig;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import java.io.IOException;

public class ServletServiceDemo {

  static class EchoServlet implements Servlet {

    @Override
    public void service(ServletRequest req, ServletResponse res)
        throws ServletException, IOException {
      // 1. 接收容器派发的请求与响应对象并执行业务处理
      System.out.println("Handling client request in service()");
    }

    @Override
    public void init(ServletConfig config) throws ServletException {}

    @Override
    public ServletConfig getServletConfig() { return null; }

    @Override
    public String getServletInfo() { return "EchoServlet"; }

    @Override
    public void destroy() {}
  }

  public static void main(String[] args) throws ServletException, IOException {
    Servlet servlet = new EchoServlet();
    servlet.init(null);

    // 2. 模拟容器工作线程调用 service 处理并发请求
    servlet.service(null, null);
  }
}

元数据获取 ​

  • ServletConfig getServletConfig():(),配置对象获取。返回容器在调用 init(ServletConfig) 时传入的 ServletConfig 实例,用于获取当前 Servlet 的注册名称、局部初始化参数以及关联的全局 ServletContext。

  • String getServletInfo():(),描述信息获取。返回当前 Servlet 的纯文本元数据描述字符串,通常包含作者、版本及版权声明信息。

注意事项:

  1. 直接实现 Servlet 接口时,必须在 init(ServletConfig) 方法内部将容器传入的 ServletConfig 参数手动保存到成员变量中,才能保证 getServletConfig() 正常返回非空对象。
  2. getServletInfo() 的返回值应为纯文本字符串,不应包含 HTML 标签或格式化标记;若无需提供描述信息,通常返回空字符串 ""。
java
import jakarta.servlet.Servlet;
import jakarta.servlet.ServletConfig;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;

public class ServletMetadataDemo {

  static class MetadataServlet implements Servlet {

    private ServletConfig config;

    @Override
    public void init(ServletConfig config) throws ServletException {
      this.config = config;
    }

    @Override
    public ServletConfig getServletConfig() {
      // 1. 返回 init 阶段保存的 ServletConfig 配置对象
      return this.config;
    }

    @Override
    public String getServletInfo() {
      // 2. 返回当前 Servlet 的版本与版权描述文本
      return "MetadataServlet v1.0 - Copyright 2026";
    }

    @Override
    public void service(ServletRequest req, ServletResponse res) {}

    @Override
    public void destroy() {}
  }

  public static void main(String[] args) throws ServletException {
    Servlet servlet = new MetadataServlet();
    servlet.init(null);

    // 3. 获取当前 Servlet 绑定的配置对象引用
    System.out.println("Config: " + servlet.getServletConfig());

    // 4. 获取当前 Servlet 的元数据描述信息
    System.out.println("Info: " + servlet.getServletInfo());
  }
}

API: GenericServlet ​

构造方法 ​

  • GenericServlet GenericServlet():(),默认无参构造。初始化一个通用的、协议无关的 GenericServlet 骨架实例,所有配置注入与资源初始化操作均推迟至 init() 阶段由 Web 容器触发执行。

    java
    import jakarta.servlet.GenericServlet;
    import jakarta.servlet.ServletRequest;
    import jakarta.servlet.ServletResponse;
    
    public class GenericServletConstructorDemo {
    
      static class CustomGenericServlet extends GenericServlet {
    
        public CustomGenericServlet() {
          // 1. 调用父类 GenericServlet 的默认无参构造器
          super();
        }
    
        @Override
        public void service(ServletRequest req, ServletResponse res) {}
      }
    
      public static void main(String[] args) {
        // 2. 实例化自定义 GenericServlet 子类对象
        GenericServlet servlet = new CustomGenericServlet();
        System.out.println("Created instance: " + servlet.getClass().getSimpleName());
      }
    }

生命周期管理 ​

  • init():组件初始化重载族。负责在 Servlet 实例化后保存容器传入的 ServletConfig 配置引用,并提供无参钩子方法供子类编写自定义初始化逻辑。

    • void:(ServletConfig config),带参容器初始化。由 Web 容器直接调用,将传入的 ServletConfig 对象保存到内部 transient 成员变量中,随后自动调用无参 init() 方法。
    • void:(),无参扩展初始化。供子类重写的便捷初始化钩子方法,使子类无需手动调用 super.init(config) 即可直接安全地读取配置并初始化资源。
  • void destroy():(),组件销毁回调。由 Web 容器在卸载当前 Servlet 实例前调用一次,默认提供空实现,供子类按需重写以释放底层系统资源。

注意事项:

  1. 子类若需要编写自定义初始化逻辑,推荐直接重写无参的 init() 方法;若重写了带参的 init(ServletConfig config),必须在方法首行显式调用 super.init(config),否则内部 ServletConfig 成员变量将保持为 null,导致后续调用配置读取方法时抛出异常。
java
import jakarta.servlet.GenericServlet;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;

public class GenericServletLifecycleDemo {

  static class ResourceServlet extends GenericServlet {

    @Override
    public void init() throws ServletException {
      // 1. 重写无参 init 钩子方法执行自定义初始化逻辑
      System.out.println("ResourceServlet initialized via no-arg init()");
    }

    @Override
    public void destroy() {
      // 2. 重写 destroy 方法在组件卸载前释放资源
      System.out.println("ResourceServlet destroyed");
    }

    @Override
    public void service(ServletRequest req, ServletResponse res) {}
  }

  public static void main(String[] args) throws ServletException {
    GenericServlet servlet = new ResourceServlet();

    // 3. 容器调用带参 init(config),内部自动触发无参 init()
    servlet.init(null);

    // 4. 容器卸载组件时调用 destroy()
    servlet.destroy();
  }
}

请求处理 ​

  • abstract void service():(ServletRequest req, ServletResponse res),协议无关请求处理。实现自顶层 Servlet 接口并继续声明为抽象方法,强制具体协议子类(如 HttpServlet)重写该方法以解析特定网络协议请求并生成响应。

    java
    import jakarta.servlet.GenericServlet;
    import jakarta.servlet.ServletException;
    import jakarta.servlet.ServletRequest;
    import jakarta.servlet.ServletResponse;
    import java.io.IOException;
    
    public class GenericServletServiceDemo {
    
      static class PingServlet extends GenericServlet {
    
        @Override
        public void service(ServletRequest req, ServletResponse res)
            throws ServletException, IOException {
          // 1. 实现抽象 service 方法处理客户端通用请求
          System.out.println("Processing generic request in PingServlet");
        }
      }
    
      public static void main(String[] args) throws ServletException, IOException {
        GenericServlet servlet = new PingServlet();
        servlet.init(null);
    
        // 2. 调用 service 方法执行请求处理逻辑
        servlet.service(null, null);
      }
    }

配置访问 ​

  • ServletConfig getServletConfig():(),配置对象获取。返回当前实例在 init(ServletConfig) 阶段保存的 ServletConfig 对象引用。

  • ServletContext getServletContext():(),全局上下文获取。直接委托给内部持有的 ServletConfig 对象,返回当前 Servlet 所属 Web 应用的 ServletContext 全局上下文实例。

  • String getServletName():(),组件名称获取。委托给内部 ServletConfig 对象,返回当前 Servlet 在部署描述符或注解中注册的唯一标识名称。

  • String getServletInfo():(),组件描述获取。返回当前 Servlet 的版本、作者或版权等纯文本元数据描述,默认返回空字符串 ""。

  • String getInitParameter():(String name),局部参数读取。委托给内部 ServletConfig 对象,根据参数名获取当前 Servlet 的局部初始化参数值;若参数名不存在则返回 null。

  • Enumeration<String> getInitParameterNames():(),局部参数名枚举。委托给内部 ServletConfig 对象,返回包含当前 Servlet 所有局部初始化参数名称的 Enumeration 枚举集合。

注意事项:

  1. getServletContext()、getServletName()、getInitParameter() 与 getInitParameterNames() 在底层均先调用 getServletConfig() 获取配置引用再执行委托;若在构造器内或 init(ServletConfig) 完成前调用这些方法,将直接抛出 IllegalStateException。
java
import jakarta.servlet.GenericServlet;
import jakarta.servlet.ServletConfig;
import jakarta.servlet.ServletContext;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import java.util.Collections;
import java.util.Enumeration;
import java.util.Map;

public class GenericServletConfigDemo {

  static class ConfigDemoServlet extends GenericServlet {

    @Override
    public void service(ServletRequest req, ServletResponse res) {}

    @Override
    public String getServletInfo() {
      // 1. 重写 getServletInfo 返回组件元数据描述
      return "ConfigDemoServlet v1.0";
    }
  }

  public static void main(String[] args) throws ServletException {
    GenericServlet servlet = new ConfigDemoServlet();
    Map<String, String> params = Map.of("charset", "UTF-8");

    ServletConfig mockConfig = new ServletConfig() {
      @Override public String getServletName() { return "demoServlet"; }
      @Override public ServletContext getServletContext() { return null; }
      @Override public String getInitParameter(String name) { return params.get(name); }
      @Override public Enumeration<String> getInitParameterNames() {
        return Collections.enumeration(params.keySet());
      }
    };
    servlet.init(mockConfig);

    // 2. 直接通过 GenericServlet 委托方法读取注册名称与局部初始化参数
    System.out.println("Name: " + servlet.getServletName());
    System.out.println("Charset: " + servlet.getInitParameter("charset"));

    // 3. 遍历所有局部初始化参数名并获取配置对象与描述信息
    Enumeration<String> names = servlet.getInitParameterNames();
    while (names.hasMoreElements()) {
      System.out.println("Param key: " + names.nextElement());
    }
    System.out.println("Config ref: " + servlet.getServletConfig());
    System.out.println("Context ref: " + servlet.getServletContext());
    System.out.println("Info: " + servlet.getServletInfo());
  }
}

日志记录 ​

  • log():容器日志记录重载族。将指定消息或异常堆栈委托给底层 ServletContext 的日志通道输出,并在日志内容前自动拼接当前 Servlet 的注册名称作为前缀。
    • void:(String msg),纯文本日志输出。将普通文本消息追加当前 Servlet 名称前缀后写入 Web 容器的日志文件中。

    • void:(String message, Throwable t),异常堆栈日志输出。将错误说明消息及给定的 Throwable 异常完整调用栈一并写入 Web 容器的日志文件中。

      java
      import jakarta.servlet.GenericServlet;
      import jakarta.servlet.ServletConfig;
      import jakarta.servlet.ServletContext;
      import jakarta.servlet.ServletException;
      import jakarta.servlet.ServletRequest;
      import jakarta.servlet.ServletResponse;
      import java.lang.reflect.Proxy;
      import java.util.Collections;
      import java.util.Enumeration;
      
      public class GenericServletLogDemo {
      
        static class LoggableServlet extends GenericServlet {
          @Override
          public void service(ServletRequest req, ServletResponse res) {}
        }
      
        public static void main(String[] args) throws ServletException {
          GenericServlet servlet = new LoggableServlet();
      
          // 1. 构建模拟 ServletContext 拦截并打印底层日志输出
          ServletContext mockContext = (ServletContext) Proxy.newProxyInstance(
            ServletContext.class.getClassLoader(),
            new Class<?>[]{ServletContext.class},
            (proxy, method, methodArgs) -> {
              if ("log".equals(method.getName())) {
                System.out.println("[Container Log] " + methodArgs[0]);
              }
              return null;
            }
          );
      
          ServletConfig mockConfig = new ServletConfig() {
            @Override public String getServletName() { return "orderServlet"; }
            @Override public ServletContext getServletContext() { return mockContext; }
            @Override public String getInitParameter(String name) { return null; }
            @Override public Enumeration<String> getInitParameterNames() {
              return Collections.emptyEnumeration();
            }
          };
          servlet.init(mockConfig);
      
          // 2. 调用单参 log 方法输出带 Servlet 名称前缀的普通消息
          servlet.log("Order service started");
      
          // 3. 调用双参 log 方法输出错误消息与异常堆栈
          servlet.log("Failed to process order", new IllegalStateException("Timeout"));
        }
      }

API: HttpServlet ​

构造方法 ​

  • HttpServlet HttpServlet():(),默认无参构造。初始化一个针对 HTTP 协议定制的抽象骨架实例;由于 HttpServlet 被声明为抽象类,无法直接实例化,仅由具体业务子类在构造器中通过 super() 隐式或显式调用。

    java
    import jakarta.servlet.http.HttpServlet;
    
    public class HttpServletConstructorDemo {
    
      static class CustomHttpServlet extends HttpServlet {
    
        public CustomHttpServlet() {
          // 1. 调用父类 HttpServlet 的无参构造方法
          super();
        }
      }
    
      public static void main(String[] args) {
        // 2. 实例化自定义 HttpServlet 子类对象
        HttpServlet servlet = new CustomHttpServlet();
        System.out.println("Created instance: " + servlet.getClass().getSimpleName());
      }
    }

请求派发 ​

  • service():HTTP 请求路由派发。接收 Web 容器传入的请求与响应对象,完成协议类型强转、条件缓存校验(If-Modified-Since),并根据 HTTP 请求动词(如 GET、POST)分发至对应的 doXxx() 模板方法。

    • void:(ServletRequest req, ServletResponse res),通用请求转型入口。重写自父类 GenericServlet 的公有入口方法,将通用的 ServletRequest 与 ServletResponse 强制向下转型为 HttpServletRequest 与 HttpServletResponse,随后委托调用受保护的重载 service(HttpServletRequest, HttpServletResponse) 方法。
    • protected void:(HttpServletRequest req, HttpServletResponse resp),HTTP 动词分支派发。通过 req.getMethod() 获取客户端请求方式,结合 getLastModified() 处理条件 GET/HEAD 请求,并将请求路由至对应的 doGet()、doPost()、doPut()、doDelete()、doHead()、doOptions() 或 doTrace() 方法。
  • protected long getLastModified():(HttpServletRequest req),资源修改时间获取。返回当前请求目标资源的最后修改时间戳(距 1970 年 1 月 1 日 00:00:00 GMT 的毫秒数),供 service() 在处理 GET 与 HEAD 请求时比对客户端 If-Modified-Since 请求头,以决定是否直接返回 304 Not Modified 状态码;默认返回 -1L 表示未知或始终重新生成。

注意事项:

  1. 业务子类通常不应重写 service() 方法,否则会破坏 HttpServlet 内置的 HTTP 动词分发机制、If-Modified-Since 条件缓存校验以及 HEAD/OPTIONS 自动响应逻辑,应按需重写具体的 doXxx() 方法。
  2. HTTP 协议中的 If-Modified-Since 头部时间精度仅到秒级,容器在比对 getLastModified() 返回的毫秒时间戳时会自动向下取整到秒(即丢弃不足 1000 毫秒的余数)。
java
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.lang.reflect.Proxy;

public class HttpServletDispatchDemo {

  static class CachedArticleServlet extends HttpServlet {

    private final long lastModifiedTime = 1700000000000L;

    @Override
    protected long getLastModified(HttpServletRequest req) {
      // 1. 返回资源的最后修改时间戳以支持条件 GET 缓存校验
      return this.lastModifiedTime;
    }

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) {
      System.out.println("Executing doGet() after dispatch");
    }
  }

  public static void main(String[] args) throws ServletException, IOException {
    CachedArticleServlet servlet = new CachedArticleServlet();

    HttpServletRequest mockReq = (HttpServletRequest) Proxy.newProxyInstance(
      HttpServletRequest.class.getClassLoader(),
      new Class<?>[]{HttpServletRequest.class},
      (proxy, method, methodArgs) -> {
        if ("getMethod".equals(method.getName())) return "GET";
        if ("getDateHeader".equals(method.getName())) return -1L;
        return null;
      }
    );

    HttpServletResponse mockResp = (HttpServletResponse) Proxy.newProxyInstance(
      HttpServletResponse.class.getClassLoader(),
      new Class<?>[]{HttpServletResponse.class},
      (proxy, method, methodArgs) -> null
    );

    // 2. 调用公有 service(ServletRequest, ServletResponse) 入口完成转型与派发
    servlet.service((ServletRequest) mockReq, (ServletResponse) mockResp);

    // 3. 调用 getLastModified 与受保护的 HTTP 专用 service 方法
    System.out.println("LastModified: " + servlet.getLastModified(mockReq));
    servlet.service(mockReq, mockResp);
  }
}

业务方法 ​

  • protected void doGet():(HttpServletRequest req, HttpServletResponse resp),GET 请求处理。由 service() 方法在接收到 HTTP GET 请求时调用,用于执行幂等的资源读取、列表查询或页面渲染操作;子类未重写时默认向客户端返回 405 Method Not Allowed(HTTP/1.1)或 400 Bad Request(HTTP/1.0)状态码。

  • protected void doPost():(HttpServletRequest req, HttpServletResponse resp),POST 请求处理。由 service() 方法在接收到 HTTP POST 请求时调用,用于处理表单提交、文件上传、数据新增或非幂等的业务指令;子类未重写时默认返回 405 或 400 错误状态码。

  • protected void doPut():(HttpServletRequest req, HttpServletResponse resp),PUT 请求处理。由 service() 方法在接收到 HTTP PUT 请求时调用,用于执行目标资源的完整替换或状态更新操作;子类未重写时默认返回 405 或 400 错误状态码。

  • protected void doDelete():(HttpServletRequest req, HttpServletResponse resp),DELETE 请求处理。由 service() 方法在接收到 HTTP DELETE 请求时调用,用于删除服务端指定的目标资源;子类未重写时默认返回 405 或 400 错误状态码。

注意事项:

  1. 子类在重写 doGet()、doPost()、doPut() 或 doDelete() 时,严禁在方法体内调用 super.doXxx(req, resp),否则父类默认实现会直接调用 resp.sendError(405) 拦截响应并向客户端报错。
java
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.lang.reflect.Proxy;

public class HttpServletCrudDemo {

  static class RestUserServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
        throws ServletException, IOException {
      // 1. 重写 doGet 处理资源查询请求
      System.out.println("GET: Query user detail");
    }

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp)
        throws ServletException, IOException {
      // 2. 重写 doPost 处理资源创建请求
      System.out.println("POST: Create new user");
    }

    @Override
    protected void doPut(HttpServletRequest req, HttpServletResponse resp)
        throws ServletException, IOException {
      // 3. 重写 doPut 处理资源更新请求
      System.out.println("PUT: Update existing user");
    }

    @Override
    protected void doDelete(HttpServletRequest req, HttpServletResponse resp)
        throws ServletException, IOException {
      // 4. 重写 doDelete 处理资源删除请求
      System.out.println("DELETE: Remove user");
    }
  }

  public static void main(String[] args) throws ServletException, IOException {
    RestUserServlet servlet = new RestUserServlet();
    for (String httpMethod : new String[]{"GET", "POST", "PUT", "DELETE"}) {
      HttpServletRequest req = (HttpServletRequest) Proxy.newProxyInstance(
        HttpServletRequest.class.getClassLoader(),
        new Class<?>[]{HttpServletRequest.class},
        (proxy, method, methodArgs) -> {
          if ("getMethod".equals(method.getName())) return httpMethod;
          if ("getDateHeader".equals(method.getName())) return -1L;
          return null;
        }
      );
      HttpServletResponse resp = (HttpServletResponse) Proxy.newProxyInstance(
        HttpServletResponse.class.getClassLoader(),
        new Class<?>[]{HttpServletResponse.class},
        (proxy, method, methodArgs) -> null
      );

      // 5. 通过 service 自动路由至对应的 doGet、doPost、doPut、doDelete 方法
      servlet.service(req, resp);
    }
  }
}

协议方法 ​

  • protected void doHead():(HttpServletRequest req, HttpServletResponse resp),HEAD 请求处理。由 service() 方法在接收到 HTTP HEAD 请求时调用,默认通过内部包装一个丢弃响应体数据的 NoBodyResponse 对象并委托调用 doGet(),从而仅向客户端返回与 GET 完全一致的状态码与响应头(含自动统计的 Content-Length),而不发送任何响应正文。

  • protected void doOptions():(HttpServletRequest req, HttpServletResponse resp),OPTIONS 请求处理。由 service() 方法在接收到 HTTP OPTIONS 请求时调用,默认通过反射向上遍历类继承树,检测当前子类重写了哪些 doXxx() 方法,自动组装并写回包含所允许 HTTP 动词列表的 Allow 响应头(例如 GET, HEAD, POST, OPTIONS)。

  • protected void doTrace():(HttpServletRequest req, HttpServletResponse resp),TRACE 请求处理。由 service() 方法在接收到 HTTP TRACE 请求时调用,默认将客户端发来的请求行与请求头信息封装为 message/http 类型的响应体原样回显,主要用于网络链路诊断。

注意事项:

  1. 只要子类重写了 doGet() 方法,默认情况下无需再手动重写 doHead() 和 doOptions(),因为 doHead() 会自动复用 doGet() 生成响应头,且 doOptions() 会在检测到重写了 doGet() 时自动在 Allow 响应头中同时声明 GET 和 HEAD。
  2. 在生产环境中,TRACE 请求可能被攻击者利用配合跨站脚本发起跨站追踪攻击(XST),主流 Web 容器默认在连接器层面禁用 TRACE,或可在子类中重写 doTrace() 显式返回 405 Method Not Allowed。
java
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.io.PrintWriter;
import java.io.StringWriter;
import java.lang.reflect.Proxy;
import java.util.Collections;

public class HttpServletProtocolDemo {

  static class DiagnosticServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
        throws ServletException, IOException {
      resp.getWriter().write("Body Content");
    }

    @Override
    public void doHead(HttpServletRequest req, HttpServletResponse resp)
        throws ServletException, IOException {
      // 1. 调用父类默认 doHead 实现,执行 doGet 但忽略响应体输出
      super.doHead(req, resp);
    }

    @Override
    public void doOptions(HttpServletRequest req, HttpServletResponse resp)
        throws ServletException, IOException {
      // 2. 调用父类默认 doOptions 实现,自动计算并设置 Allow 响应头
      super.doOptions(req, resp);
    }

    @Override
    public void doTrace(HttpServletRequest req, HttpServletResponse resp)
        throws ServletException, IOException {
      // 3. 调用父类默认 doTrace 实现,回显客户端请求行与请求头信息
      super.doTrace(req, resp);
    }
  }

  public static void main(String[] args) throws ServletException, IOException {
    DiagnosticServlet servlet = new DiagnosticServlet();
    StringWriter buffer = new StringWriter();

    HttpServletRequest req = (HttpServletRequest) Proxy.newProxyInstance(
      HttpServletRequest.class.getClassLoader(),
      new Class<?>[]{HttpServletRequest.class},
      (proxy, method, methodArgs) -> {
        if ("getMethod".equals(method.getName())) return "TRACE";
        if ("getRequestURI".equals(method.getName())) return "/diag";
        if ("getProtocol".equals(method.getName())) return "HTTP/1.1";
        if ("getHeaderNames".equals(method.getName())) {
          return Collections.emptyEnumeration();
        }
        return null;
      }
    );

    HttpServletResponse resp = (HttpServletResponse) Proxy.newProxyInstance(
      HttpServletResponse.class.getClassLoader(),
      new Class<?>[]{HttpServletResponse.class},
      (proxy, method, methodArgs) -> {
        if ("setHeader".equals(method.getName())) {
          System.out.println("Header " + methodArgs[0] + ": " + methodArgs[1]);
        }
        if ("getWriter".equals(method.getName())) {
          return new PrintWriter(buffer);
        }
        return null;
      }
    );

    // 4. 触发 doOptions 生成 Allow 响应头,并触发 doTrace 回显请求报文
    servlet.doOptions(req, resp);
    servlet.doTrace(req, resp);
    System.out.println("Trace Output: " + buffer.toString().trim());
  }
}

继承: GenericServlet ​

destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, init, log, log

Servlet 生命周期 ​

Servlet 的生命周期是指一个 Servlet 实例从被创建、初始化、接收并处理客户端请求,直到最终被销毁并由 JVM 垃圾回收器回收的完整过程。与普通 Java 对象不同,开发者不会在业务代码中手动通过 new 关键字创建 Servlet,其整个生命周期完全由 Web 容器(如 Tomcat)全权托管。

在默认情况下,Web 容器对每个注册的 Servlet 声明采用单例多线程模式管理:即每个 Servlet 配置在容器中只会创建一个实例,所有并发请求共享同一个 Servlet 实例。

生命周期流转过程 ​

Servlet 的完整生命周期划分为四个核心阶段,依次对应类的反射实例化以及 Servlet 接口中的三个生命周期方法:init、service 和 destroy。

容器管理 Servlet 生命周期的状态流转与调用时序如下图所示:

image-20261029154231885

各阶段的核心执行规则如下:

  1. 类加载与实例化:Web 容器通过类加载器加载 Servlet 类文件,并通过反射机制调用其公有无参构造方法(public 无参构造器)创建唯一的 Servlet 实例。

  2. 初始化(init):实例创建完成后,容器立即调用其 init(ServletConfig) 方法完成前置资源准备。该方法在整个生命周期中仅执行一次。

  3. 请求处理(service):初始化完成后,Servlet 进入常驻内存的就绪状态。每当匹配的客户端请求到达时,容器从线程池分配工作线程并调用 service 方法。该方法在生命周期中会被并发调用多次。

  4. 销毁(destroy):当 Web 应用被卸载、重新部署或容器关闭时,容器调用 destroy 方法释放资源。该方法在整个生命周期中仅执行一次。

生命周期阶段触发时机执行次数执行线程核心职责
类加载与实例化首次请求到达或容器启动时1 次容器启动线程或首个请求工作线程加载字节码并反射调用无参构造器创建对象
初始化(init)实例化完成后立即执行1 次与实例化阶段同线程读取配置参数、初始化数据库连接池或缓存
请求处理(service)每次匹配的 HTTP 请求到达时多次(0 至 N 次)容器线程池分配的独立工作线程解析请求数据、执行业务逻辑、生成响应报文
销毁(destroy)应用停止、卸载或容器关闭前1 次容器关闭管理线程关闭外部连接、停止后台任务、持久化内存状态

init ​

当容器通过反射创建 Servlet 实例后,必须在将任何客户端请求路由给该实例之前完成 init 方法的调用。由于实例化依赖反射调用 Class.getDeclaredConstructor().newInstance(),自定义的 Servlet 类必须保留公有无参构造方法;若定义了带参构造器而未显式声明无参构造器,容器在实例化阶段将直接抛出 InstantiationException。

在初始化阶段,Web 容器保证线程安全性:只有当 init 方法成功执行完毕并正常返回后,容器才会将该 Servlet 标记为可用状态并向其派发请求。因此,在 init 方法内部对成员变量进行赋值时无需额外加锁。

java
// 1. 配置 loadOnStartup = 1
// 容器启动时立即完成实例化与初始化
@WebServlet(urlPatterns = "/lifecycle", loadOnStartup = 1)
public class LifecycleServlet extends HttpServlet {

  private String resourceState;

  // 2. 初始化阶段:整个生命周期仅执行一次
  // 用于加载耗时配置或建立全局连接资源
  @Override
  public void init() throws ServletException {
    this.resourceState = "INITIALIZED";
  }

  // 3. 请求处理阶段:每次客户端请求均会触发
  // 由容器分配独立工作线程并发调用
  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp)
      throws ServletException, IOException {
    resp.getWriter().write("State: " + this.resourceState);
  }

  // 4. 销毁阶段:应用卸载或容器关闭前仅执行一次
  // 用于释放已分配的底层系统资源
  @Override
  public void destroy() {
    this.resourceState = null;
  }
}

loadOnStartup ​

Servlet 的实例化与初始化触发时机由 loadOnStartup 属性(在 web.xml 中对应 <load-on-startup> 标签)控制,分为以下两种加载策略:

  1. 延迟加载(默认策略):当未配置该属性,或将其值设置为负数(如默认的 -1)时,容器在启动阶段不会创建该 Servlet。只有当客户端第一次发起匹配该 URL 的请求时,容器才会触发类加载、实例化与 init 调用。这种方式能够加快容器启动速度,但会导致第一个请求响应变慢。

  2. 启动预加载(积极加载):当将其值设置为大于或等于 0 的整数时,容器会在 Web 应用启动阶段立即完成实例化并调用 init 方法。若多个 Servlet 均配置了非负整数,容器会按照数值从小到大的顺序依次初始化(例如 0 优先于 1);若数值相同,则由容器自行决定加载顺序。

    xml
    <!-- 1. 注册 Servlet 实例名称与完整类名 -->
    <!-- 默认情况下容器采用延迟加载策略 -->
    <servlet>
      <servlet-name>lifecycleServlet</servlet-name>
      <servlet-class>com.example.servlet.LifecycleServlet</servlet-class>
    
      <!-- 2. 设置非负整数开启容器启动时预加载 -->
      <!-- 数值越小,初始化优先级越高 -->
      <load-on-startup>1</load-on-startup>
    </servlet>

UnavailableException ​

如果 Servlet 在执行 init 方法期间因配置缺失、数据库连接失败等原因抛出 ServletException 或其子类 UnavailableException,容器将判定初始化失败。此时,该实例不会被放入活跃服务池,也不会调用其 destroy 方法,而是直接将其废弃回收。

jakarta.servlet.UnavailableException 细分了两种不可用状态:

  1. 永久不可用:通过 new UnavailableException(String msg) 构造。容器直接放弃该 Servlet,在应用重新部署前向所有访问该路由的请求返回 404 Not Found 或 503 Service Unavailable。

  2. 暂时不可用:通过 new UnavailableException(String msg, int seconds) 构造。容器在指定的秒数内拒绝向该 Servlet 派发请求(直接向客户端返回 503 Service Unavailable 并携带 Retry-After 响应头),待冷却时间结束后,容器会重新尝试实例化并调用 init 方法。

    java
    // 1. 重写无参初始化方法校验核心依赖
    // 若初始化抛出异常,容器将放弃加载该实例
    @Override
    public void init() throws ServletException {
      boolean dbConnected = checkDatabaseConnection();
    
      // 2. 数据库未就绪时抛出暂时不可用异常
      // 通知容器在 60 秒后重新尝试初始化并在期间返回 503 状态码
      if (!dbConnected) {
        throw new UnavailableException("Database unavailable", 60);
      }
    }

service ​

当 Servlet 完成初始化后,便常驻于容器内存中等待请求。每当客户端发起 HTTP 请求,Web 容器与 service 方法的协作流程如下:

  1. 分配工作线程:容器从内部线程池中取出一个空闲的工作线程来托管本次请求。

  2. 创建请求与响应对象:容器针对本次 HTTP 通信创建一个全新的 HttpServletRequest 对象(封装请求报文)和一个全新的 HttpServletResponse 对象(用于构建响应报文)。

  3. 调用 service 方法:工作线程将 Request 和 Response 对象作为参数传入 Servlet.service(req, res),经由 HttpServlet 派发至对应的 doGet 或 doPost 方法执行业务逻辑并写入响应数据。

  4. 销毁请求与响应对象:当 service 方法执行结束返回后,容器将响应数据刷出至客户端,随后立即销毁(或清空回收)本次请求的 Request 与 Response 对象,并将工作线程归还至线程池。

需要注意区分对象生命周期的边界:Servlet 实例是单例长生命周期的(跟随应用存亡),而 HttpServletRequest 与 HttpServletResponse 对象是请求级短生命周期的 (跟随单次 service 调用存亡)。

destroy ​

当 Web 应用被停止、重新加载或 Web 容器正常关闭时,容器会启动 Servlet 销毁流程以回收系统资源。

容器在执行 destroy 时遵循优雅停机(Graceful Shutdown)原则:

  1. 停止接收新请求:容器首先将该 Servlet 从路由映射表中移除,不再向其派发新的客户端请求。

  2. 等待活跃请求完成:如果当前仍有工作线程正在执行该 Servlet 的 service 方法,容器会等待这些线程执行完毕,或者等待至容器预设的最大超时时间(Timeout)。

  3. 执行 destroy 回调:容器调用 destroy() 方法,开发者应在此处关闭文件句柄、释放非托管内存、中断自建后台线程或刷出内存缓存。

  4. 释放实例引用:destroy() 方法返回后,容器彻底断开对该 Servlet 实例的引用。此后该实例永远不会再处理任何请求,等待 JVM 垃圾回收器(GC)将其从堆内存中清理。

API: UnavailableException ​

构造方法 ​

  • UnavailableException():不可用异常构造重载族。用于构建表示 Servlet 或 Filter 组件处于永久不可用或暂时不可用状态的异常实例,通知 Web 容器暂停或终止向该组件派发请求。
    • UnavailableException:(String msg),永久不可用异常构造。使用指定的错误描述信息构建一个表示组件永久不可用的异常实例,容器捕获后将直接废弃该组件且在应用重新部署前不再重试。
    • UnavailableException:(String msg, int seconds),暂时不可用异常构造。使用指定的错误描述信息与预计恢复秒数构建一个表示组件暂时不可用的异常实例;若传入的 seconds 小于或等于 0,则表示无法预估具体的恢复时间。

注意事项:

  1. 当使用单参构造器 UnavailableException(String msg) 时,内部会将不可用状态标记为永久(isPermanent() 返回 true),若在 init() 阶段抛出该异常,容器不会将该组件放入活跃服务池,也不会调用其 destroy() 方法。
  2. 当使用双参构造器 UnavailableException(String msg, int seconds) 时,若传入的 seconds <= 0,内部会将其归一化存储为 -1,表示组件虽然属于暂时不可用,但无法提供明确的恢复倒计时。
  3. 早期规范中的 UnavailableException(Servlet, String) 与 UnavailableException(int, Servlet, String) 构造器自 Servlet 2.2 起已标记为废弃,并在 Jakarta Servlet 6.0 中被正式移除。
java
import jakarta.servlet.UnavailableException;

public class UnavailableExceptionConstructorDemo {
  public static void main(String[] args) {
    // 1. 构建表示永久不可用的异常实例
    UnavailableException permEx = new UnavailableException("Missing configuration file");
    System.out.println("Permanent message: " + permEx.getMessage());

    // 2. 构建表示暂时不可用且预计 30 秒后恢复的异常实例
    UnavailableException tempEx = new UnavailableException("Database connection pool busy", 30);
    System.out.println("Temporary message: " + tempEx.getMessage());
  }
}

状态查询 ​

  • boolean isPermanent():(),永久不可用判定。判断当前组件是否处于永久不可用状态;若返回 true,表示组件存在配置错误等无法自行恢复的故障,必须由管理员修复后重新部署应用。

  • int getUnavailableSeconds():(),不可用时长获取。返回组件预计持续不可用的秒数;若组件为永久不可用或无法预估具体恢复时长,则统一返回负数(-1)。

注意事项:

  1. 当 isPermanent() 返回 false 时,Web 容器会在 getUnavailableSeconds() 指定的冷却秒数内拒绝向该组件派发请求,直接向客户端返回 503 Service Unavailable 状态码,并在响应头中携带 Retry-After 字段。
  2. getUnavailableSeconds() 返回的正整数仅作为冷却期参考值,容器在倒计时期间不会开启后台线程主动探测故障是否恢复,而是等到冷却期结束后、下一个客户端请求到达时再次尝试初始化或调用该组件。
  3. 早期规范中的 getServlet() 方法自 Servlet 2.2 起已标记为废弃,并在 Jakarta Servlet 6.0 中被彻底移除。
java
import jakarta.servlet.UnavailableException;

public class UnavailableExceptionStatusDemo {
  public static void main(String[] args) {
    UnavailableException permEx = new UnavailableException("Fatal config error");
    UnavailableException tempEx = new UnavailableException("Downstream timeout", 60);

    // 1. 调用 isPermanent 判断是否为永久不可用状态
    System.out.println("permEx isPermanent: " + permEx.isPermanent());
    System.out.println("tempEx isPermanent: " + tempEx.isPermanent());

    // 2. 调用 getUnavailableSeconds 获取预计不可用的秒数
    System.out.println("permEx seconds: " + permEx.getUnavailableSeconds());
    System.out.println("tempEx seconds: " + tempEx.getUnavailableSeconds());
  }
}

继承: Throwable ​

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

继承: ServletException ​

getRootCause

Servlet 线程安全 ​

在 Java Web 容器中,Servlet 默认采用单例多线程(Singleton Multi-threading)模式运行。对于每一个在 web.xml 或通过 @WebServlet 注册的 Servlet 定义,容器在内存中仅创建一个实例;而当多个客户端同时发起请求时,容器会从内部线程池中分配多个独立的工作线程,并发调用同一个 Servlet 实例的 service(进而派发至 doGet、doPost)方法。

由于默认情况下容器并未对 service 方法加锁,因此 Servlet 本身并不是天然线程安全的。如果在 Servlet 中不当地定义并修改共享状态,在高并发场景下将直接引发数据覆盖、脏读或逻辑错乱等线程安全事故。

单例多线程并发模型 ​

要理解 Servlet 的线程安全问题,首先需要结合 JVM 内存模型区分堆内存(Heap)共享区与线程调用栈(Thread Stack)隔离区在请求处理过程中的边界:

  1. 堆内存共享区:唯一的 Servlet 实例存放在 JVM 堆内存中,其内部声明的实例成员变量(Instance Variables)与静态变量(Static Variables)被所有工作线程共同持有和访问。此外,全局唯一的 ServletContext(应用域)以及同一个用户跨请求共享的 HttpSession(会话域)也位于堆内存共享区。

  2. 线程私有与请求隔离区:每当一个 HTTP 请求到达时,容器从线程池分配一个工作线程(如 http-nio-8080-exec-1)。每个工作线程拥有自己独立的 JVM 调用栈,doGet/doPost 方法内部声明的局部变量(Local Variables)以及方法参数引用均存放在各自线程的栈帧中,彼此完全物理隔离。同时,容器为每次请求单独创建的 HttpServletRequest 和 HttpServletResponse 对象仅由当前工作线程独占,不会跨线程共享。

多个并发工作线程访问单例 Servlet 及其关联内存区域的 UML 架构与交互关系如下图所示:

image-20261029154632801

并发竞争问题演示 ​

当开发者将与单次请求绑定的业务数据(如当前登录用户名、订单金额、临时计算结果)定义为 Servlet 的可读可写成员变量时,多个工作线程同时交替执行就会产生竞态条件(Race Condition)。

以下代码展示了一个典型的非线程安全 Servlet 示例:

java
// 1. 错误示范:将请求级业务状态声明为 Servlet 实例成员变量
// 由于 Servlet 是单例的,所有并发工作线程共享同一个 currentUser 字段
@WebServlet("/unsafe")
public class UnsafeTransferServlet extends HttpServlet {

  // 2. 存放在堆内存中的共享可变成员变量
  // 多个线程并发读写该变量时会发生互相覆盖
  private String currentUser;

  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp)
      throws ServletException, IOException {
    // 3. 线程 A 赋值为 "Alice" 后若发生上下文切换或耗时 I/O
    // 线程 B 紧接着进入并将该成员变量篡改为 "Bob"
    this.currentUser = req.getParameter("username");

    try {
      Thread.sleep(100);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
    }

    // 4. 当线程 A 恢复执行并输出响应时
    // 读取到的 this.currentUser 已经变成了线程 B 写入的 "Bob"
    resp.getWriter().write("Transfer executed for: " + this.currentUser);
  }
}

在上述过程中,若线程 A(请求参数 username=Alice)执行完第 15 行赋值后进入耗时操作(如查询数据库、调用外部接口),CPU 调度器将执行权切换给线程 B(请求参数 username=Bob)。线程 B 瞬间将同一个 Servlet 实例的 this.currentUser 覆盖为 "Bob"。当线程 A 恢复执行第 25 行时,就会拿着 "Bob" 的身份执行后续逻辑,造成严重的跨用户数据串号事故。

各级变量与域对象的并发安全性 ​

在编写 Servlet 代码时,必须明确不同生命周期变量与四大域对象在多线程环境下的安全边界:

变量或对象类型内存分配与作用范围线程安全性结论核心原因与使用规范
方法局部变量当前工作线程的 JVM 栈帧绝对线程安全每个线程执行 doXxx 时各自在栈帧中创建独立副本,互不干扰(前提是局部变量未引用外部共享可变对象)
HttpServletRequest(请求域)单次 HTTP 请求内部线程安全容器为每次请求创建独立实例,仅在当前工作线程调用链(含 forward 转发)内流转(异步处理派发多线程除外)
HttpServletResponse单次 HTTP 响应内部线程安全与 Request 一一对应,由当前请求工作线程独占写入
只读实例成员变量 / 常量堆内存(Servlet 单例持有)线程安全仅在 init() 阶段赋值或声明为 final,运行期所有工作线程只读不写,无竞态条件
可写实例成员变量 / 静态变量堆内存 / 方法区非线程安全所有并发请求工作线程直接共享读写,极易发生脏读与数据覆盖,严禁用于保存请求状态
HttpSession(会话域)同一客户端跨多次请求共享非线程安全同一用户在浏览器同时打开多个标签页或发起并发 Ajax 请求时,多个线程会同时读写同一个 HttpSession 实例
ServletContext(应用域)整个 Web 应用全局共享非线程安全全站所有客户端请求线程均可并发读写,复合操作存在严重竞态风险

保障线程安全的工程方案 ​

针对 Servlet 单例多线程模型的特点,在实际工程中应按以下优先级采取防范措施。

无状态化与局部变量 ​

最根本、性能最高的解决方案是将 Servlet 设计为无状态组件(Stateless Component):

  1. 禁止定义可写成员变量:不在 Servlet 类中声明任何用于保存业务请求状态的实例字段。

  2. 状态下沉至局部变量:将所有与单次请求相关的参数、中间结果全部声明为 doGet/doPost 方法内部的局部变量,或者挂载到 HttpServletRequest 属性(req.setAttribute)中向下传递。

  3. 只读配置与线程安全组件:如果必须在成员变量中持有对象,仅允许持有在 init() 中初始化完毕的只读配置项,或者本身已经实现线程安全的组件(如数据库连接池 DataSource、无状态的 Service 单例等)。

    java
    // 1. 仅保留在 init 阶段初始化的只读配置或线程安全组件
    // 移除所有保存单次请求业务状态的可变成员变量
    @WebServlet("/safe-transfer")
    public class SafeTransferServlet extends HttpServlet {
    
      private String systemEnv;
    
      // 2. 在初始化阶段完成只读成员变量的赋值
      // 容器保证 init 执行完毕后才派发请求,运行期只读不写是线程安全的
      @Override
      public void init() throws ServletException {
        this.systemEnv = this.getInitParameter("env");
      }
    
      @Override
      protected void doGet(HttpServletRequest req, HttpServletResponse resp)
          throws ServletException, IOException {
        // 3. 将请求数据声明为方法内的局部变量
        // 局部变量分配在当前工作线程独立的栈帧中,天然具备线程隔离性
        final String currentUser = req.getParameter("username");
        resp.getWriter().write("[" + this.systemEnv + "] Transfer for: " + currentUser);
      }
    }

JUC 原子类与并发容器 ​

如果业务确实需要在 Servlet 实例级别统计全局指标(例如统计当前 Servlet 自启动以来的总调用次数、或维护一个组件级内存缓存),则不能使用普通的 int、long 或 HashMap,而应使用 java.util.concurrent(JUC)包下的线程安全类:

  • 计数与累加:使用 AtomicInteger、AtomicLong 或高并发下吞吐量更高的 LongAdder。

  • 键值映射与集合:使用 ConcurrentHashMap、CopyOnWriteArrayList 等并发容器。

    java
    // 1. 使用 AtomicLong 原子类定义实例级共享计数器
    // 底层基于 CAS (Compare-And-Swap) 无锁指令保障并发累加安全
    @WebServlet("/counter")
    public class CounterServlet extends HttpServlet {
    
      // 2. 声明为 final 引用,防止引用本身被重新赋值
      // 多个线程并发调用原子方法不会产生计数丢失
      private final AtomicLong requestCount = new AtomicLong(0);
    
      @Override
      protected void doGet(HttpServletRequest req, HttpServletResponse resp)
          throws ServletException, IOException {
        // 3. 以原子方式将计数加 1 并返回更新后的值
        // 避免使用非线程安全的 count++ 复合操作
        long current = this.requestCount.incrementAndGet();
        resp.getWriter().write("Total requests: " + current);
      }
    }

ThreadLocal ​

当调用链路较深(例如从 Servlet 依次调用多个辅助类或工具方法),且不希望在每个方法签名中显式透传 HttpServletRequest 参数时,可以使用 java.lang.ThreadLocal<T> 将当前请求的状态绑定到当前工作线程的私有存储映射表(ThreadLocalMap)中。

由于 Web 容器采用线程池复用机制,工作线程在处理完当前 HTTP 请求后并不会销毁,而是直接归还给线程池并用于处理下一个客户端请求。因此,在 Servlet 中使用 ThreadLocal 必须遵守一条铁律:必须在 try-finally 块的 finally 分支中显式调用 remove() 方法清理数据。若遗漏清理,不仅会导致严重的内存泄漏(Memory Leak),还会导致下一个复用该工作线程的请求读取到上一个遗留的脏数据。

java
// 1. 定义静态 ThreadLocal 容器保存线程绑定的上下文数据
// 每个工作线程通过它读写各自独立的副本
@WebServlet("/context-holder")
public class ThreadLocalServlet extends HttpServlet {

  private static final ThreadLocal<String> USER_HOLDER = new ThreadLocal<>();

  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp)
      throws ServletException, IOException {
    // 2. 在 try 块中绑定当前请求数据并执行业务逻辑
    // 同一线程后续调用的任何方法均可通过 USER_HOLDER.get() 获取数据
    try {
      USER_HOLDER.set(req.getParameter("username"));
      resp.getWriter().write("Current user: " + USER_HOLDER.get());
    } finally {
      // 3. 必须在 finally 块中调用 remove() 清除当前线程绑定的数据
      // 防止容器线程池复用该线程时发生跨请求数据污染与内存泄漏
      USER_HOLDER.remove();
    }
  }
}

synchronized ​

在操作某些无法替换为并发类的非线程安全共享资源时,可以使用 synchronized 关键字进行互斥同步。但在 Servlet 中使用 synchronized 需要注意锁粒度:

  1. 严禁直接在 service 或 doGet 方法声明上加 synchronized:这等价于锁住整个单例 Servlet(synchronized(this)),会导致所有客户端并发请求退化为完全串行排队执行,系统吞吐量瞬间骤降。

  2. 减小同步代码块粒度:仅针对存在竞态条件的最小代码片段加锁,并声明专门的私有锁对象(private final Object lock = new Object()),确保耗时 I/O 操作留在同步块之外。

SingleThreadModel ​

在早期的 Servlet 2.0 规范中,曾提供过一个名为 javax.servlet.SingleThreadModel 的标记接口(Marker Interface,内部没有任何方法)。其设计初衷是:如果某个 Servlet 实现了该接口,Web 容器将保证同一时刻绝不会有两个工作线程同时执行同一个 Servlet 实例的 service 方法(容器通常通过对 service 方法加锁串行化,或为该 Servlet 维护一个多实例对象池来实现)。

然而,该接口在 Servlet 2.4 规范中已被正式标记为废弃(@Deprecated),并在 Jakarta Servlet 6.0(Jakarta EE 10)规范中被彻底移除。废弃并移除的核心原因如下:

  1. 产生虚假的安全感:即使容器为实现了 SingleThreadModel 的 Servlet 创建多个实例,它也只能隔离普通实例成员变量,根本无法解决静态变量(static)、HttpSession 会话域以及 ServletContext 应用域的并发读写冲突。

  2. 严重的性能劣化:无论是将并发请求阻塞排队,还是在内存中频繁创建销毁多个重量级 Servlet 实例,都会在高并发场景下造成剧烈的性能瓶颈。