Servlet深度解析：从生命周期到Spring Boot底层原理与实战避坑-代码聚汇网

Servlet深度解析：从生命周期到Spring Boot底层原理与实战避坑

REECHO大鱼总舵·2026-09-01·阅读 22 GEO检测（免费）

ServletSpring BootFeignClient

|难度：普通|阅读约 40 分钟

做了这么多年 Java 后端，Servlet 是我最早接触也最常被认成“过时技术”的东西。很多人一上来就 Spring Boot 一把梭，结果遇到上传文件报错、请求编码乱码、过滤器不生效时，才不得不回头补 Servlet 的课。其实 Servlet 不仅没过时，Spring MVC、Spring Boot 的 Web 层底层全是它。把这层地基摸透了，排查很多 Web 层问题都会顺手得多。

这篇文章就从一个真实项目的角度出发，把 Servlet 的生命周期、手写项目流程、企业级常见坑（包括热搜里那个 FeignClient 解析 multipart 请求失败的问题）以及 Servlet 在前后端分离架构下的定位一次性讲清楚。适合刚接触 Java Web 的初学者，也适合被各种框架报错折腾到想骂人的老手。

1. Servlet 到底是什么：先从一次 HTTP 请求说起

1.1 Servlet 在 Web 开发生态里的真实地位

Servlet 是 Java EE（现在叫 Jakarta EE）规范里的一个核心组件，它的职责很纯粹：接收 HTTP 请求，处理后返回响应。很多人以为 Servlet 就是某个具体的类，其实它更像一个契约——规定了 Java 程序怎么和 Web 服务器打交道。Tomcat、Jetty、Undertow 这些容器实现了这个契约，你写的 Servlet 只是遵守契约的业务代码。

可以这么理解：Tomcat 是一个“前台接待”，它负责监听端口、收下 HTTP 请求报文、把报文转成 Java 对象，然后调你的 Servlet；Servlet 处理完业务后把结果写进响应对象，Tomcat 再把它拼成 HTTP 响应发回给客户端。你从头到尾看不到 Socket、看不到 HTTP 报文解析，这些脏活累活容器全干完了。

Spring MVC 的核心 DispatcherServlet 本身就是一个 Servlet，只是它帮你封装了 Controller 分发、参数绑定、视图解析这一整套流程。所以你在 Spring Boot 里写的 @RestController 和 @RequestMapping，最终都是被 DispatcherServlet 路由到对应方法的。换句话说，Servlet 是 Spring Web 体系的底层，不是被替代的关系。

1.2 Servlet 生命周期：五个阶段和一个常被误会的点

Servlet 的生命周期由容器管理，总共就五个阶段：加载、实例化、初始化 init、服务 service、销毁 destroy。

java复制public class LifecycleServlet extends HttpServlet {

    @Override
    public void init() throws ServletException {
        // 只会执行一次，适合做资源初始化
        System.out.println("init: 加载配置、创建全局对象");
    }

    @Override
    protected void service(HttpServletRequest req, HttpServletResponse resp) {
        // 每来一次请求都会执行
        System.out.println("service: 处理请求，分发到 doGet/doPost");
    }

    @Override
    public void destroy() {
        // 容器关闭或应用卸载时执行一次
        System.out.println("destroy: 释放连接池等资源");
    }
}

这里有一个重要细节：Servlet 默认是单实例多线程的。也就是说，同一个 Servlet 对象会被多个请求线程共享，service 方法里的局部变量是线程安全的，但实例变量和类变量就存在并发问题。我见过不少新手把用户数据存到实例变量里，结果出现串号问题，排查了半天才发现是共享变量惹的祸。

默认情况下，Servlet 在第一次请求时才被实例化（懒加载）
可以通过 <load-on-startup> 或 @WebServlet(loadOnStartup = 1) 让容器启动时立即加载
每次请求由容器分配工作线程，调用同一个 Servlet 实例的 service 方法

1.3 请求响应对象的核心职责

HttpServletRequest 封装了请求行、请求头、请求体，你通过它拿参数、拿 Cookie、拿 Session；HttpServletResponse 负责写状态码、写响应头、写响应体。两个对象都是容器创建的，请求结束后由容器回收，不需要你手动关闭。

日常开发中最常用的几个操作：

java复制// 接收参数
String name = request.getParameter("name");
String[] hobbies = request.getParameterValues("hobby");
Map<String, String[]> paramMap = request.getParameterMap();

// 转发与重定向的区别（这个面试也爱问）
request.getRequestDispatcher("/target").forward(request, response);
response.sendRedirect("/login");

// 写响应
response.setContentType("text/html;charset=UTF-8");
response.getWriter().write("<h1>hello</h1>");

转发是服务器内部的跳转，浏览器地址栏不变；重定向是告诉浏览器去访问另一个地址，地址栏会变。这俩的区别我后面排查问题时还会提到。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 手写一个 Servlet 项目：从 web.xml 到注解配置

2.1 不用框架，纯 Servlet 怎么跑起来

很多人只见过 Spring Boot 里的 Servlet，没见过原生 Servlet 项目长什么样。其实弄懂原生项目，框架的封装逻辑就很容易看透了。一个最简的 Servlet 项目只需要三样东西：一个继承 HttpServlet 的类、一个 Servlet 容器（比如 Tomcat）、一个配置文件。

先用最传统的 web.xml 方式注册 Servlet：

xml复制<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
         https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
         version="5.0">

    <servlet>
        <servlet-name>hello</servlet-name>
        <servlet-class>com.example.HelloServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>hello</servlet-name>
        <url-pattern>/hello</url-pattern>
    </servlet-mapping>
</web-app>

Servlet 3.0 之后支持注解方式，省掉不少 XML：

java复制@WebServlet(name = "hello", urlPatterns = "/hello", loadOnStartup = 1)
public class HelloServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws IOException {
        resp.setContentType("text/plain;charset=UTF-8");
        resp.getWriter().write("Hello Servlet!");
    }
}

把项目打成 WAR 包丢进 Tomcat 的 webapps 目录就能跑。如果你用的是 Maven，注意把打包方式设为 war，内置 Tomcat 插件可以直接启动调试。

2.2 路径映射：精确匹配、通配符和默认 Servlet

路径映射是 Servlet 里最容易踩坑的地方。容器匹配 URL 是有优先级的：精确匹配优先于最长路径前缀匹配，然后才是扩展名匹配，最后才是默认 Servlet。

精确匹配：/hello、/user/detail
路径匹配：/user/*
扩展名匹配：*.do、*.action
默认匹配：/，兜底所有未匹配的请求

举个实际例子，如果你写了一个 /user/* 的 Servlet，当你访问 /user/123 时，request.getPathInfo() 返回 /123，request.getServletPath() 返回 /user。很多人在这两个方法上犯迷糊，其实记住一句话：getServletPath 是匹配到的那段路径，getPathInfo 是后面剩下的那部分。

还有一个常见需求是静态资源处理。Spring Boot 里默认静态资源映射到 /**，但它也是通过一个 DefaultServlet 实现的。你如果在 web.xml 里自己声明了一个 <url-pattern>/</url-pattern> 的 Servlet，就会覆盖容器的默认静态资源处理，导致 HTML、JS、CSS 全部 404。这个问题我在老项目迁移时遇到过不止一次。

2.3 过滤器、监听器：Servlet 生态的两大辅助角色

Filter 和 Listener 不算 Servlet 本体，但它们是 Servlet 规范里非常重要的组成部分。过滤器拦截请求和响应，在 Servlet 之前或之后执行；监听器监听容器和对象的生命周期事件。

过滤器最经典的应用就是编码设置和登录校验：

java复制@WebFilter(urlPatterns = "/*")
public class EncodingFilter implements Filter {

    @Override
    public void init(FilterConfig filterConfig) {
        System.out.println("过滤器初始化");
    }

    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
                         FilterChain chain) throws IOException, ServletException {
        HttpServletRequest req = (HttpServletRequest) request;
        HttpServletResponse resp = (HttpServletResponse) response;
        req.setCharacterEncoding("UTF-8");
        resp.setCharacterEncoding("UTF-8");
        chain.doFilter(req, resp);
    }

    @Override
    public void destroy() {
        System.out.println("过滤器销毁");
    }
}

监听器里最常用的是 ServletRequestListener 和 HttpSessionListener，可以用来做在线用户统计、请求耗时统计。虽然现在有 Spring 的 HandlerInterceptor 可以替代部分过滤器的功能，但过滤器优先级更高，因为它在 Servlet 容器层面生效，连 Spring MVC 的 DispatcherServlet 都拦得住。

2.4 实践中建议：能用框架还是要用框架

说了这么多纯 Servlet 的写法，我的真实建议是：学习时可以手写，生产项目还是用 Spring Boot 或者至少 Spring MVC。原因是纯 Servlet 项目里大量重复的样板代码，比如参数校验、JSON 序列化、异常处理，都得自己写。但理解 Servlet 能帮你真正读懂框架的报错信息，尤其是容器层面的错误，比如 404、405、请求解析失败这类问题，不懂 Servlet 基本无从下手。

3. 企业级项目里 Servlet 的常见坑与排查实录

3.1 热搜里的 FeignClient multipart 解析失败，到底怎么回事

热搜词里有一条很有代表性的报错：feign client failed to parse multipart servlet request; nested exception is ...。这行错误在 Spring Cloud 微服务项目里做文件上传时出现频率极高。

先说根本原因。Feign 在调用远程服务上传文件时，需要把请求以 multipart/form-data 格式发送。这里出问题通常有三个层面：

Feign 客户端没有正确配置 multipart 编码器（比如缺 feign-form 依赖）
服务端接收参数时用了 @RequestPart 但实际没有 multipart 请求
底层 multipart 解析器找不到临时目录或磁盘空间不足

解决思路分两步。第一步，确认 Feign 配置是否完整：

java复制@FeignClient(name = "file-service", configuration = FileUploadFeignConfig.class)
public interface FileUploadClient {

    @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    String upload(@RequestPart("file") MultipartFile file,
                  @RequestPart("userId") String userId);
}

Feign 默认用的是 SpringFormEncoder，如果不确定，显式加上 feign-form 和 feign-form-spring 两个依赖，并手动配置编码器：

java复制@Configuration
public class FileUploadFeignConfig {

    @Bean
    public Encoder feignFormEncoder() {
        return new SpringFormEncoder(new SpringEncoder(feignObjectFactory()));
    }

    private FeignContext feignContext;

    private ObjectFactory<HttpMessageConverters> feignObjectFactory() {
        HttpMessageConverters converters = new HttpMessageConverters(
                new MappingJackson2HttpMessageConverter());
        return () -> converters;
    }
}

第二步，排查服务端。报错信息里出现 Could not parse multipart servlet request 时，多半是 Tomcat 在处理 multipart 时抛出的底层异常，常见原因有以下几种：

排查点	检查方法	处理建议
临时目录	检查 `java.io.tmpdir` 指向的目录是否存在且有写权限	手动创建目录，或启动参数指定 `-Djava.io.tmpdir=/data/tmp`
文件大小限制	看是否触发 `max-file-size`、`max-request-size` 限制	适当调大 Spring Boot 配置
请求头缺失	确认 Feign 请求带上了 `Content-Type: multipart/form-data; boundary=...`	使用 `@RequestPart` 而非 `@RequestBody`
参数类型	确认服务端方法参数是 `MultipartFile` 且和 Feign 端一致	保持两端的参数名和类型一致

我个人遇到过最隐蔽的一次：生产环境临时目录被系统定时清理工具删了，但 Tomcat 启动时创建的临时目录句柄还在，应用看起来正常，上传却随机失败，报的正是这个错。重启应用又好了，过段时间又复现。最后把 multipart 的 location 显式配置到应用自己的目录下才彻底解决：

yaml复制spring:
  servlet:
    multipart:
      location: /data/app-tmp
      max-file-size: 50MB
      max-request-size: 100MB

3.2 编码问题：GET 和 POST 的乱码处理方式不一样

乱码问题很经典，而且 GET 和 POST 的乱码原因完全不同。POST 请求的参数在请求体里，所以 request.setCharacterEncoding("UTF-8") 有效；GET 请求的参数在 URL 里，这个设置根本不生效，乱码来自服务器对 URL 的解码方式。

Tomcat 8 之后默认对 URL 使用 UTF-8 解码，但老项目从 Tomcat 7 升级过来时，经常遇到 GET 中文乱码，就是因为 Tomcat 7 的默认 URIEncoding 是 ISO-8859-1。解决办法是在 server.xml 的 Connector 上配置 URIEncoding="UTF-8"，或者在 Spring Boot 里设置：

yaml复制server:
  tomcat:
    uri-encoding: UTF-8

这里我要多说一句，很多乱码问题并不是 Servlet 的问题，而是整个链路的问题：前端页面编码、HTTP 请求编码、Servlet 解码、数据库连接编码。任何一个环节不对，结果都是乱码。排查时按这个链路逐层检查，不要只盯着后端代码。

3.3 异步 Servlet：长任务的正确处理方式

Servlet 3.0 之后支持异步处理，这是个经常被忽略的能力。默认情况下，一个请求占用一个工作线程，直到响应完整写完才算结束。如果某个接口需要执行一个耗时的任务（比如调外部接口、处理大文件），工作线程会被长时间占用，线程池耗尽后所有请求都排队等待。

异步 Servlet 的思路是：先把请求线程释放回去，在另一个线程池里执行耗时任务，完成后通过 AsyncContext.complete() 或 dispatch() 返回结果。

java复制@WebServlet(urlPatterns = "/async", asyncSupported = true)
public class AsyncServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) {
        AsyncContext asyncContext = req.startAsync();
        asyncContext.start(() -> {
            try {
                String result = longRunningTask();
                resp.getWriter().write(result);
            } catch (IOException e) {
                log.error("async write error", e);
            } finally {
                asyncContext.complete();
            }
        });
    }
}

Spring Boot 里对应的就是 Callable、WebAsyncTask、DeferredResult。这些都是在 Servlet 异步机制基础上封装的。实际使用中要注意，异步任务必须自己管理线程池，否则容器默认的线程池寿命很短，任务没执行完线程就被销毁了。

Session 是 Servlet 规范里很重要的概念，本质是基于 Cookie 或 URL 重写实现的。HttpSession 的数据保存在服务器内存里，通过 JSESSIONID 这个 Cookie 识别客户端。

常见问题有几个：

忘记设置 HttpOnly，导致 JavaScript 能拿到 Session ID，存在 XSS 窃取风险
分布式环境下默认的 Session 内存存储导致用户登录状态丢失
关闭浏览器后 Session 失效，其实是 Cookie 默认是会话级别的，不持久化

生产中做分布式 Session 一般用 Redis 或者把登录态改为 JWT，不再依赖容器 Session。这也是 Servlet 里最值得重构的部分之一。

java复制// 设置 HttpOnly 和过期时间的 Cookie
Cookie cookie = new Cookie("JSESSIONID", sessionId);
cookie.setHttpOnly(true);
cookie.setSecure(true);
cookie.setMaxAge(3600);
response.addCookie(cookie);

4. Servlet 的现代演进：Spring Boot、Astro 与前后端分离架构

4.1 Spring Boot 对 Servlet 的封装逻辑

Spring Boot 内置了 Tomcat/Jetty/Undertow，你写 Controller 时完全不碰 Servlet API，但那层封装始终存在。DispatcherServlet 被自动注册到容器，它接收所有请求，然后通过 HandlerMapping 找到对应的 Controller 方法。

理解这个封装逻辑对排查问题很有帮助。比如你在 Controller 方法返回 ResponseEntity，Spring 会通过 HttpMessageConverter 把对象序列化成 JSON 写进 HttpServletResponse。这个过程中任何一步出错，最终抛回给容器的还是一个 Servlet 异常。

我自己调试时经常做一件事：在 Filter 里打印请求的 request.getRequestURI() 和 request.getMethod()，确认请求到底走到哪一步了。如果 Filter 里能拦截到但 Controller 没执行，说明是 Spring MVC 层的问题；如果 Filter 里都看不到请求，那问题出在容器层或拦截器之前。

4.2 Astro 做前端，Servlet 做后端：一种实用的前后端组合

热搜词里还有一条“astro 和 servlet”。Astro 是一个主打静态输出、按需加载的前端框架，它的特点是默认输出静态 HTML，交互很少的页面几乎不需要 JavaScript。很多人会用 Astro 做内容型网站，那后端数据从哪来？一种很常见的组合就是 Astro 生成静态页面，动态数据的接口由 Java 的 Servlet（或者基于 Servlet 的 Spring Boot）提供。

这种架构下，Astro 负责页面呈现和静态资源，Java Servlet 只写纯粹的 JSON API。Astro 页面在构建时或者运行时通过 fetch 调用后端接口拿数据。你不用把 Servlet 和 Astro 理解成两个竞争的技术，它们各管一段：

Astro 管浏览器端的页面结构和交互
Servlet 管数据接口、权限校验、业务逻辑
中间用约定好的 JSON 结构通信

我实际做过的博客系统就是这种结构。文章列表页由 Astro 静态生成，评论和搜索走 Servlet 接口。静态页面秒开，动态数据也不卡，架构简单，部署也方便。前端和后端可以分别部署在 Nginx 和 Tomcat 上，互不干扰。

如果你用了 Spring Boot，还可以用 @RestController 来提供这些 JSON 接口，本质上仍是 Servlet 在背后工作。用原生 Servlet 还是 Spring Boot，取决于你的团队是否需要 Spring 全家桶的功能，如果只是简单的数据接口，原生 Servlet 反而更轻量。

4.3 线上性能调优：从连接器参数到线程池配置

Servlet 容器层面有几组参数对性能影响很大，很多项目上线后才回来调这些。

Tomcat 连接器（Connector）的核心参数包括：

yaml复制server:
  tomcat:
    threads:
      max: 200
      min-spare: 10
    accept-count: 100
    max-connections: 8192
    connection-timeout: 20000

max-threads：最大工作线程数，线程太多会导致频繁上下文切换，太少则吞吐量不足。一般按 QPS * 平均响应时间 估算，比如 QPS 100、平均 200ms，所需线程约 20，再加上余量 50 到 100 就够。
accept-count：当请求数超过线程池容量时，进入等待队列的最大数量。这个值不要太大，否则用户会有很长的排队时间。
max-connections：连接数上限。注意 HTTP 1.1 默认 keep-alive 开启，一个连接上的多个请求可以复用，所以连接数和并发请求数不完全对应。

调整参数时要配合压测，不要拍脑袋。我习惯用 JMeter 或 wrk 压测，观察吞吐量和响应时间的变化拐点，再决定参数取值。

4.4 项目里还有哪些地方值得看 Servlet 源码

很多人问我要不要读 Servlet 源码，我的答案是：不用精读，但三个关键类值得看。第一个是 HttpServlet，看它怎么根据请求方法分发到 doGet、doPost；第二个是 HttpServletRequest 的 getParameter 实现，看它是怎么从请求行和请求体里解析参数的；第三个是 RequestDispatcher.forward 的实现，看它和 sendRedirect 的本质差异。

这三个点看完，你就掌握了 Servlet 最核心的执行逻辑。再回头去看 Spring MVC 的 DispatcherServlet 源码，会顺畅很多。Spring 的 DispatcherServlet 里那个中央分发循环，做的事情本质上和你手写 Servlet 时做的事是一样的：找出处理者、调用处理者、返回结果。只是它封装得更通用、更可扩展。

5. 一些容易忽略的 Servlet 细节清单

最后分享一份我自己整理的问题速查清单，都是踩过坑之后攒下来的。

现象	可能原因	解决方案
请求进入后 404	路径映射错误或 Servl 未注册	检查 `url-pattern` 和注解路径，确认 `@WebServlet` 被扫描到
405 Method Not Allowed	只重写了 `doGet` 但页面用 POST 提交	补上 `doPost`，或者让 `service` 统一处理
响应乱码	`setContentType` 设置在前或漏写	先写 `setCharacterEncoding("UTF-8")` 再拿 Writer
上传文件报错	multipart 解析器未配置	Spring Boot 设置 `spring.servlet.multipart.enabled=true`
Session 不生效	Cookie 被禁用或域/路径不匹配	检查 Cookie 的 `Path` 属性，必要时使用 URL 重写
静态资源 404	自定义 Servlet 映射了 `/`	不要覆盖容器默认的 DefaultServlet
请求线程被占满	同步处理耗时逻辑	使用异步 Servlet 或消息队列
过滤器不执行	过滤器路径没匹配	确认 `urlPatterns` 的含义，`/*` 匹配所有路径

还有一个细节：request.getParameter() 在请求体被读取过一次之后再次读取是拿不到的。所以如果你在 Filter 里做了 getParameter 操作，后面 Controller 再想拿参数可能会拿不到，这就是为什么很多框架需要包装一个可重复读的 HttpServletRequestWrapper。比如做日志记录要读取请求体，就得先把请求体会保存成字节数组，再重写 getInputStream 方法。

java复制public class RepeatableReadRequestWrapper extends HttpServletRequestWrapper {

    private final byte[] body;

    public RepeatableReadRequestWrapper(HttpServletRequest request) throws IOException {
        super(request);
        this.body = request.getInputStream().readAllBytes();
    }

    @Override
    public ServletInputStream getInputStream() {
        ByteArrayInputStream bais = new ByteArrayInputStream(body);
        return new ServletInputStream() {
            @Override
            public boolean isFinished() { return bais.available() == 0; }

            @Override
            public boolean isReady() { return true; }

            @Override
            public void setReadListener(ReadListener listener) {}

            @Override
            public int read() { return bais.read(); }
        };
    }

    @Override
    public BufferedReader getReader() {
        return new BufferedReader(new InputStreamReader(getInputStream(), StandardCharsets.UTF_8));
    }
}

这个包装类在实现审计日志、接口幂等校验、防重放攻击时都非常有用，建议收藏。

回到开头那个问题：Servlet 过时了吗？我的看法是，作为一个单独的开发技术，你不需要再手写大量 Servlet；但作为 Java Web 的地基，你永远绕不开它。能讲清楚 Servlet 生命周期、能看懂容器报错、知道过滤器和监听器怎么介入请求链路，这些能力在排查 Spring Boot 项目问题时直接决定你的效率。尤其是那个 FeignClient 上传文件的报错，把 multipart 解析的原理搞懂之后，你会发现它的排查路径其实非常清晰。希望这篇文章能把 Servlet 从“背概念”变成“用得上的真功夫”。