Servlet-请求调度
[TOC]
RequestDispatcher
RequestDispatcher 是 Servlet 规范中用于实现服务端容器内部组件派发的核心接口。当一个入口 Servlet 接收到客户端请求并完成前置业务处理后,可以通过 RequestDispatcher 将当前请求与响应对象移交或包含至同一个 Web 应用(ServletContext)内的其他组件(如另一个 Servlet、JSP 视图页面或静态 HTML 资源)协同处理。整个派发过程完全在服务端容器内部闭环完成,客户端浏览器仅发起一次 HTTP 请求,地址栏 URL 保持不变。
容器内部派发架构
在 Tomcat 等 Web 容器中,RequestDispatcher 的核心实现类为 org.apache.catalina.core.ApplicationDispatcher。与客户端发起的外部 HTTP 请求不同,容器内部派发不会重新经历底层 Socket 解析或连接器(Connector)建连,而是在同一个工作线程(Worker Thread)的调用栈中直接跨组件调用。
为了在共享同一个底层请求与响应上下文的同时,让目标组件感知到正确的目标路径并隔离非法的响应头篡改,容器在执行派发时会动态引入内部装饰器包装机制:
内部请求包装层:当调用派发方法时,
ApplicationDispatcher会创建继承自HttpServletRequestWrapper的内部类ApplicationHttpRequest,将原始请求对象包裹起来。该包装类拦截了路径获取方法(如getServletPath()、getRequestURI())与参数读取方法,使其能够根据转发或包含模式返回对应的路径视图与合并后的参数表;而对于请求域属性(Attribute)的读写,则直接穿透委托给最底层的原始Request对象。内部响应包装层:与此同时,容器会创建继承自
HttpServletResponseWrapper的内部类ApplicationHttpResponse包裹原始响应对象。在包含(Include)模式下,该包装类会静默拦截所有修改状态码与响应头的方法调用,防止被包含的局部子组件破坏主控组件的响应元数据。派发类型与过滤器链重建:每次内部派发都会将请求的派发类型(
DispatcherType)由初始的REQUEST切换为FORWARD或INCLUDE。容器会根据目标资源路径或组件名称重新构建一条匹配相应DispatcherType的ApplicationFilterChain,依次执行配置了<dispatcher>FORWARD</dispatcher>或<dispatcher>INCLUDE</dispatcher>的过滤器,最后调用目标 Servlet 的service()方法。生命周期自动解包:当目标组件的
service()方法及内部过滤链执行完毕并返回时,ApplicationDispatcher会自动销毁本次派发创建的ApplicationHttpRequest与ApplicationHttpResponse包装层,恢复外层组件原有的请求路径视图与查询参数状态。

派发寻址与安全穿透
在获取 RequestDispatcher 实例时,容器支持基于路径与基于组件名称两种寻址维度,且不同入口接口对路径格式有着不同的解析基准。
上下文根路径寻址
通过 ServletContext.getRequestDispatcher(String path) 获取派发器时,传入的路径参数必须以正斜杠 / 开头。容器固定将该 / 解析为当前 Web 应用的上下文根路径(contextPath);若传入的路径未以 / 开头,容器将直接返回 null 或抛出 IllegalArgumentException。
请求相对路径寻址
通过 ServletRequest.getRequestDispatcher(String path) 获取派发器时,既支持以 / 开头的上下文根路径,也支持不以 / 开头的相对路径。当传入不以 / 开头的相对路径(如 "detail")时,容器会提取当前请求 URI 所在的目录层级并将其拼接为完整的上下文绝对路径,随后再委托给 ServletContext 完成派发器创建。
组件名称寻址
通过 ServletContext.getNamedDispatcher(String name) 获取派发器时,容器直接根据目标 Servlet 注册的逻辑名称(即部署描述符中的 <servlet-name> 或 @WebServlet 注解的 name 属性)在容器内部组件注册表中查找目标实例。由于命名派发不涉及任何 URL 路径解析,派发期间不会改写请求的 URI 路径段,也不会向 Request 域注入任何派发路径属性。
WEB-INF 受保护资源穿透
在标准 Java Web 目录结构中,/WEB-INF 目录及其子目录属于受容器安全保护的私有区域。客户端浏览器若直接在地址栏请求 /WEB-INF/views/order.jsp,容器会直接拒绝访问并返回 404 Not Found。
然而,RequestDispatcher 运行在容器内部授信边界内,拥有直接穿透 /WEB-INF 目录隔离墙的权限。在实际 MVC 架构开发中,通常将所有 JSP 视图文件放置在 /WEB-INF/views/ 目录下,强制客户端请求必须先经过前置控制器 Servlet 完成权限校验与数据装配,再由控制器通过内部转发渲染视图。
// 1. 定义 MVC 控制器入口 Servlet,拦截客户端订单查看请求
@WebServlet("/order/view")
public class MvcViewDispatchServlet extends HttpServlet {
// 2. 处理业务数据并穿透访问受保护的 WEB-INF 视图资源
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
// 3. 将业务层查询结果挂载至当前 Request 域属性表
req.setAttribute("orderNo", "ORD_A_B");
req.setAttribute("amount", "299.00");
// 4. 获取指向 WEB-INF 受保护目录的请求派发器
RequestDispatcher dispatcher = req.getRequestDispatcher("/WEB-INF/views/orderDetail.jsp");
// 5. 将请求与响应控制权移交至目标视图,并立即结束当前方法
dispatcher.forward(req, resp);
}
}派发执行与缓冲区控制
RequestDispatcher 提供了控制权移交转发与响应流片段包含两种核心执行模式。二者在调用栈流转上均属于同步方法调用,但在底层响应缓冲区(OutputBuffer)管理与响应头控制权上存在本质差异:
| 对比维度 | 控制权移交转发 | 响应流片段包含 |
|---|---|---|
| 派发类型标识 | DispatcherType.FORWARD | DispatcherType.INCLUDE |
| 前置缓冲处理 | 自动清空未提交的响应体缓冲区 | 保留缓冲区中已写入的全部内容 |
| 响应头控制权 | 源组件与目标组件均可设置响应头 | 被包含的目标组件严禁修改状态码与响应头 |
| 输出流收尾 | 目标组件返回后由容器立即刷新并关闭流 | 目标组件返回后流保持打开,源组件可继续写出 |
| 典型应用场景 | MVC 控制器完成业务后跳转至视图渲染 | 页面聚合布局中嵌入公共页头、页脚或局部组件 |
控制权移交转发
转发模式代表源 Servlet 将生成最终响应体的职责彻底移交给目标资源:
前置缓冲区清空:在进入目标资源的
service()方法前,容器会首先检查响应是否已提交;若尚未提交,容器会自动调用底层resetBuffer()清空源 Servlet 此前写入缓冲区的所有响应体内容,但保留源 Servlet 已经设置的状态码、Cookie 与响应头。后置强制提交与流关闭:当目标资源执行完毕并退回至
ApplicationDispatcher时,容器会立即将目标资源生成的响应体刷出缓冲区(触发Committed状态),并主动关闭输出流。此后即便执行流回到源 Servlet,源 Servlet 后续写入的任何字节都将被直接丢弃。

响应流片段包含
包含模式代表源 Servlet 依然掌握主响应控制权,仅临时借用目标资源的输出流片段拼装到当前响应体中:

共用缓冲流追加写出:容器不会清空源 Servlet 已经写入缓冲区的字节,目标资源获取到的
PrintWriter或ServletOutputStream直接向同一个底层OutputBuffer尾部追加内容。元数据只读锁定:为防止局部被包含组件(如页脚 Servlet)意外篡改整个页面的
Content-Type或将状态码改为404/302,ApplicationHttpResponse在包含期间会屏蔽所有针对状态行和响应头的写操作。当目标资源执行完毕后,控制权回到源 Servlet,输出流保持开启状态,源 Servlet 可以继续写入后续内容或包含其他组件。java// 1. 定义页面布局聚合 Servlet,组合多个子组件输出片段 @WebServlet("/portal/home") public class PageLayoutIncludeServlet extends HttpServlet { // 2. 依次包含页头、主内容区与页脚组件,拼装完整响应流 @Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { // 3. 由主控 Servlet 统一声明响应内容类型与字符集 resp.setContentType("text/html;charset=UTF-8"); PrintWriter writer = resp.getWriter(); // 4. 包含公共导航页头组件,执行完毕后控制权返回当前方法 req.getRequestDispatcher("/fragments/header").include(req, resp); // 5. 继续向同一个输出缓冲区写入主组件内容并包含页脚 writer.println("<main>Portal Core Content</main>"); req.getRequestDispatcher("/fragments/footer").include(req, resp); } }
派发路径重写与参数合并
当请求在容器内部跨越多个不同映射路径的组件时,目标组件往往既需要感知自身的路径坐标,又可能需要追溯客户端最初请求的入口路径。同时,派发目标路径中还可以额外附带新的查询字符串参数(如 /order/target?channel=internal&tag=v2)。

路径视图切换与原始路径保留
在基于路径的派发过程中,ApplicationHttpRequest 对路径获取方法的重写遵循“谁掌控主响应,路径视图就指向谁”的原则:
| 路径维度 | 转发模式下的路径视图 | 包含模式下的路径视图 |
|---|---|---|
getRequestURI() 等方法返回值 | 重写为目标组件的路径与查询串 | 保持为源入口组件的路径与查询串 |
| 保留的 Request 域属性前缀 | javax.servlet.forward.* | javax.servlet.include.* |
| 属性保存的路径对象 | 客户端最初请求的原始入口组件路径 | 当前被包含的目标子组件路径 |
转发路径重写:在转发模式下,目标组件接管了完整的响应生成,为了确保目标组件(如 JSP)在解析页面相对路径时以自身位置为基准,容器会将
getRequestURI()、getServletPath()、getPathInfo()与getQueryString()的返回值全部重写为目标资源的路径。同时,容器将最外层入口请求的原始路径信息存入以javax.servlet.forward.*为前缀的 5 个标准 Request 域属性中(若经历多层链式转发,该组属性始终保留第一次入口的原始路径,不会被中间节点覆盖)。包含路径保持:在包含模式下,主响应仍由源组件掌控,因此直接调用
getRequestURI()等方法返回的依然是源入口组件的路径;而被包含的目标子组件若需获知自身的映射路径,则需从javax.servlet.include.*系列 Request 域属性中读取。
派发查询参数栈式合并
若获取 RequestDispatcher 时传入的目标路径中包含 ? 查询字符串(例如客户端原始请求为 /entry?tag=raw,内部派发至 /order/target?channel=internal&tag=dispatch),容器会在 ApplicationHttpRequest 内部执行栈式参数合并:
同名参数优先级前置:派发路径上新附带的查询参数会与原始请求参数合并到同一个参数视图中。若出现同名参数(如
tag),派发路径中的新参数值会排在字符串数组的最前端(索引0位置),原始请求的参数值顺延至其后。因此在目标组件中调用单值读取方法时,优先获取到的是派发路径上显式指定的新值。作用域局部隔离:上述合并产生的新增参数仅在当前目标组件的执行周期内可见。一旦目标组件的派发调用返回到外层源组件,内层
ApplicationHttpRequest被销毁,派发路径附带的参数随之失效,源组件看到的仍是原始参数表。java// 1. 定义转发目标 Servlet,检视派发后的路径属性与合并参数 @WebServlet("/order/target") public class DispatchTargetServlet extends HttpServlet { // 2. 读取容器注入的原始请求路径属性及叠加后的查询参数 @Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException { // 3. 获取当前目标路径与容器保存在 Request 域中的入口原始 URI String currentServletPath = req.getServletPath(); String originalUri = (String) req.getAttribute(RequestDispatcher.FORWARD_REQUEST_URI); // 4. 读取派发路径追加的参数以及同名多值参数数组 String sourceChannel = req.getParameter("channel"); String[] traceTags = req.getParameterValues("tag"); } }
提交状态与后置逻辑陷阱
在使用 RequestDispatcher 进行请求转发时,开发者最常遇到的运行时故障集中在响应缓冲区已提交冲突与方法调用栈未及时退出两个方面。
响应已提交引发转发异常
由于转发模式要求在进入目标组件前调用 resetBuffer() 清空此前写入的响应体,并根据目标组件的执行结果重新生成状态行与响应头,因此请求转发必须在响应尚未提交(Uncommitted)的前提下执行。
若源 Servlet 在执行转发前主动调用了 response.flushBuffer()、writer.close(),或者向输出流写入的临时数据量超过了 OutputBuffer 容量阈值(默认 8KB)导致容器自动刷出状态行与响应头,响应即刻进入 Committed 状态。此时再执行转发调用,容器将立即抛出 IllegalStateException: Cannot forward after response has been committed。
转发后代码继续执行问题
在 Java 语言层面,执行请求转发只是一次普通的同步对象方法调用,并不等同于 return 关键字。当目标组件渲染完视图并由容器关闭响应流后,JVM 线程调用栈会逐层退回至源 Servlet 中转发语句的下一行继续向下执行:
后置业务代码冗余执行:若转发语句位于条件分支(如参数校验失败或未登录拦截)内部且未跟随
return;,线程在完成错误页渲染后仍会继续向下执行正常的数据库写入或扣款业务。链式二次转发或重定向崩溃:若源 Servlet 在第一个转发分支后未及时
return;,后续代码又触发了第二次转发或sendRedirect(),由于第一次转发结束时容器已经强制提交并关闭了响应,第二次跳转必将抛出IllegalStateException。
因此,在编码实践中,除极少数需要在转发完成后做纯粹内存清理或耗时统计的场景外,每一次转发调用后都应立即紧跟 return; 语句显式结束当前方法。
// 1. 定义具备提交状态防御与控制流提前返回机制的 Servlet
@WebServlet("/order/checkout")
public class SafeForwardServlet extends HttpServlet {
// 2. 根据业务校验结果执行条件转发,防止二次提交异常
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
// 3. 参数缺失时转发至错误提示页,并通过 return 终止当前方法栈
if (req.getParameter("cartId") == null) {
req.setAttribute("errorMsg", "购物车标识不能为空");
req.getRequestDispatcher("/WEB-INF/views/error.jsp").forward(req, resp);
return;
}
// 4. 执行核心结算逻辑并在转发前确认响应尚未提交
req.setAttribute("checkoutStatus", "SUCCESS");
if (!resp.isCommitted()) {
// 5. 安全移交响应控制权至结算结果视图
req.getRequestDispatcher("/WEB-INF/views/success.jsp").forward(req, resp);
return;
}
}
}API: RequestDispatcher【待补充】
API: DispatcherType【待补充】
sendRedirect
sendRedirect 是 HttpServletResponse 接口中用于触发客户端 HTTP 重定向的核心机制。与容器内部闭环执行的请求转发不同,重定向是一种基于 HTTP 协议标准交互的外部跳转行为:服务端向客户端浏览器下发 302 Found 状态码与 Location 目标地址响应头,指示浏览器主动断开或结束当前请求,并向新地址发起第二次完全独立的 HTTP 请求。
协议交互与容器底层流程
在 Tomcat 等 Web 容器中,调用 response.sendRedirect(String location) 并不会在服务端内部直接调用目标 Servlet,而是将该操作转化为一次标准的特殊 HTTP 响应组装与提交过程:
前置提交状态校验:容器首先检查当前响应是否已进入已提交状态(
isCommitted())。若响应头已经发往客户端,容器无法再将状态码改写为302,此时会直接抛出IllegalStateException。输出缓冲区强制重置:校验通过后,容器自动调用底层
resetBuffer(),清空当前 Servlet 在调用重定向前已写入OutputBuffer但尚未提交的所有响应体内容,同时保留此前已设置的非冲突响应头(如通过addCookie()写入的Set-Cookie响应头)。相对路径解析与绝对 URL 转换:容器将传入的
location路径参数解析并转换为符合 HTTP 规范的完整 URL(或相对于宿主域名的根路径 URI)。写入状态码与 Location 响应头:容器将响应状态码设置为
302(即HttpServletResponse.SC_FOUND),并将解析后的目标地址写入Location响应头。立即刷新并关闭响应流:容器将响应标记为立即提交状态,刷出底层响应缓冲区并关闭输出流。客户端浏览器收到包含
302状态码与Location头的响应报文后,自动提取目标地址栏 URL,并以GET方法发起第二次全新的 HTTP 请求。
HTTP 3xx 重定向状态码演进
在 HTTP/1.0 与 HTTP/1.1 规范演进过程中,针对“客户端重定向后是否允许将原 POST 请求自动转换为 GET 请求”以及“浏览器是否应当缓存重定向映射关系”,定义了多个细分状态码:
| 状态码 | 规范语义名称 | 请求方法转换规则 | 缓存与搜索引擎语义 |
|---|---|---|---|
301 | Moved Permanently | 历史浏览器普遍将 POST 转为 GET | 永久重定向,浏览器默认强缓存跳转目标,转移页面权重 |
302 | Found | 历史浏览器普遍将 POST 转为 GET | 临时重定向,sendRedirect 默认状态码,默认不缓存 |
303 | See Other | 强制要求将任意请求方法显式转换为 GET | 专为 PRG(Post-Redirect-Get)模式设计的临时重定向 |
307 | Temporary Redirect | 严禁改变原请求方法与请求体(POST 保持 POST) | 严格保持原请求语义的临时重定向 |
308 | Permanent Redirect | 严禁改变原请求方法与请求体(POST 保持 POST) | 严格保持原请求语义的永久重定向 |
由于 HttpServletResponse.sendRedirect() 方法在底层固定将状态码硬编码为 302,当业务场景需要下发 301、307 或 308 状态码时,不能直接调用 sendRedirect(),而应通过手动设置状态码配合 Location 响应头完成构建:
// 1. 定义需要保持原 POST 请求方法语义的 307 临时重定向 Servlet
@WebServlet("/api/v1/pay")
public class CustomStatusRedirectServlet extends HttpServlet {
// 2. 通过手动设置 307 状态码与 Location 响应头替代默认 sendRedirect
@Override
protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
// 3. 声明 307 状态码,指示客户端重定向时严禁将 POST 改写为 GET
resp.setStatus(HttpServletResponse.SC_TEMPORARY_REDIRECT);
// 4. 指定新版本接口的完整上下文目标路径
resp.setHeader("Location", req.getContextPath() + "/api/v2/pay");
}
}寻址基准与 URL 会话重写
与容器内部执行的 RequestDispatcher 不同,sendRedirect 解析出的 Location 地址最终交由客户端浏览器执行跳转,因此其路径基准与内部转发存在显著差异。
相对路径与根路径寻址基准
在调用 sendRedirect(String location) 时,传入的路径格式直接决定了容器拼接目标地址的基准:
完整协议 URL(如
[https://www.google.com](https://www.google.com)):容器不做任何本地路径拼接,原样写入Location响应头,支持跨域名、跨站点的外部系统跳转。以正斜杠
/开头的路径(如"/login.jsp"):容器将该/解析为整个 Web 服务器(Servlet 容器宿主域名与端口)的根路径(即http://localhost:8080/login.jsp),而不包含当前 Web 应用的上下文路径(contextPath)。因此,在重定向至当前应用内部的资源时,必须显式拼接上下文路径:resp.sendRedirect(req.getContextPath() + "/login.jsp")。不以
/开头的相对路径(如"success.jsp"):容器会以当前请求 URI 所在的父级目录为基准,将其自动拼接为包含contextPath与当前目录层级的完整路径后再写入Location响应头。
URL 重写与会话追踪兼容
在依赖 HttpSession 进行会话管理的 Web 应用中,容器默认通过名为 JSESSIONID 的 Cookie 在客户端与服务端之间传递会话标识。若客户端浏览器禁用了 Cookie,单纯调用 sendRedirect 会导致第二次请求无法携带 JSESSIONID,从而丢失登录状态。
为此,HttpServletResponse 提供了 encodeRedirectURL(String url) 方法。在将目标地址传入 sendRedirect 前先经过该方法处理,容器会自动探测当前客户端是否支持 Cookie;若检测到 Cookie 被禁用且当前存在活跃 Session,容器会自动在目标 URL 路径末尾追加 ;jsessionid=xxx 路径参数,确保重定向后的第二次请求仍能命中原有会话。
// 1. 定义遵循上下文路径拼接规范与会话重写机制的重定向 Servlet
@WebServlet("/member/AuthRedirect")
public class ContextPathRedirectServlet extends HttpServlet {
// 2. 演示内部资源重定向时的上下文路径拼接与 URL 会话编码
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
// 3. 获取或创建当前会话并存入跨请求共享的用户凭证
HttpSession session = req.getSession();
session.setAttribute("loginUser", "admin");
// 4. 显式拼接应用上下文路径,并对重定向目标执行会话 ID 兼容重写
String targetUrl = req.getContextPath() + "/portal/dashboard.jsp";
String encodedUrl = resp.encodeRedirectURL(targetUrl);
// 5. 下发 302 状态码与 Location 响应头,触发客户端第二次请求
resp.sendRedirect(encodedUrl);
}
}PRG 模式与跳转机制选型
在 Web 表单提交(如订单创建、用户注册、转账支付)场景中,如果服务端在 doPost 方法中处理完数据入库后,直接使用 RequestDispatcher.forward() 转发至成功结果页,此时浏览器地址栏依然停留在原本的 POST 提交地址上。一旦用户在结果页按下 F5 刷新浏览器,浏览器会重新发送上一次的 POST 请求及表单载荷,导致订单或数据被重复提交入库。
PRG 防重复提交设计模式
为了彻底阻断刷新引发的表单重复提交,工程实践中普遍采用 PRG(Post-Redirect-Get)模式:
Post(接收并处理表单):客户端通过
POST请求提交表单数据至业务处理 Servlet,服务端完成数据库持久化操作。Redirect(响应 302 重定向):业务处理 Servlet 不直接渲染结果 HTML,而是调用
sendRedirect()指向一个专门用于展示结果的查询地址(如/order/result?id=1024)。Get(拉取结果视图):浏览器收到
302响应后,自动将地址栏更新为/order/result?id=1024并通过幂等的GET请求拉取结果页。此后无论用户如何刷新浏览器,触发的都只是安全的GET结果查询请求,不会再次执行POST入库逻辑。
请求转发与重定向全景对比
在架构设计中,选择内部请求转发还是客户端重定向,取决于跳转边界、地址栏语义、域数据共享需求以及请求幂等性要求:
| 对比维度 | RequestDispatcher 请求转发 | sendRedirect 重定向 |
|---|---|---|
| 跳转执行主体 | 服务端容器内部直接跨组件调用 | 客户端浏览器收到 302 后重新发起请求 |
| HTTP 请求次数 | 1 次请求,共用同一对 Request/Response | 2 次独立请求,每次创建新的 Request/Response |
| 浏览器地址栏 | 保持初始入口 URL 不变 | 更新为 Location 指向的新目标 URL |
| 目标资源范围 | 仅限当前 Web 应用内部,可穿透 /WEB-INF | 支持任意外部域名站点,不可访问 /WEB-INF |
/ 路径基准 | 代表当前 Web 应用根路径(含 contextPath) | 代表服务器站点根路径(不含 contextPath) |
| 跨组件数据传递 | 直接通过 Request 域属性(Attribute)高效传递 | Request 域失效,需借助 URL 查询参数或 Session 域 |
重定向异常与安全边界
在编写包含 sendRedirect 的业务代码时,除了需要防范与请求转发相同的“响应已提交冲突”和“跳转后代码继续执行”问题外,还需特别关注跨请求数据丢失与开放重定向安全漏洞。
响应已提交与后续执行阻断
已提交状态抛出异常:由于
sendRedirect需要清空响应体缓冲区并写入302状态码与Location头,若在调用sendRedirect前已经调用过flushBuffer()、关闭了输出流或因写入数据量超过缓冲区上限触发了自动提交,调用sendRedirect将立即抛出IllegalStateException: Cannot call sendRedirect() after the response has been committed。强制配合
return;终止方法栈:sendRedirect执行完毕后仅代表向响应头写入了跳转指令并提交了响应,并不会中断当前 Java 方法的执行流。若在条件分支中调用sendRedirect后未立即跟随return;,下方代码将继续执行,极易引发业务状态错乱或因后续再次执行转发/重定向而抛出二次提交异常。
Request 域属性丢失与开放重定向漏洞
Request 域属性无法跨重定向存活:在
sendRedirect之前通过request.setAttribute()存入的数据,会在第一次请求结束时随Request对象回收而被徹底清空;浏览器发起的第二次请求对应全新的HttpServletRequest实例,读取该属性恒为null。若需在重定向前后传递提示信息或业务标识,应将其拼接在目标 URL 的查询字符串中(需经过URLEncoder.encode(val, "UTF-8")编码),或临时存放在HttpSession中并在读取后及时移除(即 Flash Attribute 机制)。开放重定向(Open Redirect)安全防御:在登录认证等场景中,常通过 URL 参数接收登录成功后的回跳地址(如
/login?redirectUrl=xxx)。若服务端未对客户端传入的redirectUrl做白名单校验便直接传入sendRedirect(redirectUrl),攻击者可构造指向钓鱼网站的恶意链接诱导用户点击。因此,接收外部参数执行重定向时,必须严格校验目标地址是否属于本系统相对路径或受信任的域名白名单。java// 1. 定义采用 PRG 模式防止重复提交并具备安全边界控制的订单 Servlet @WebServlet("/order/create") public class SafePrgOrderServlet extends HttpServlet { // 2. 处理 POST 订单创建请求,完成后通过重定向跳转至结果查询页 @Override protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException { // 3. 校验未登录状态时立即重定向至登录页,并通过 return 阻断后续业务代码 if (req.getSession().getAttribute("loginUser") == null) { resp.sendRedirect(req.getContextPath() + "/login.jsp"); return; } // 4. 对需通过 URL 跨请求传递的中文提示参数进行 UTF-8 编码 String encodedMsg = URLEncoder.encode("订单创建成功", "UTF-8"); String targetUrl = req.getContextPath() + "/order/detail?msg=" + encodedMsg; // 5. 确认响应未提交后执行重定向,彻底避免 F5 刷新重复提交表单 if (!resp.isCommitted()) { resp.sendRedirect(targetUrl); return; } } }
AsyncContext
AsyncContext 是 Servlet 3.0 规范引入的异步处理核心接口,用于将“Web 容器连接器工作线程”与“耗时业务处理线程”彻底解耦。在传统的同步阻塞模型中,每次 HTTP 请求都会独占一个容器工作线程直至响应完全写出;而通过开启 AsyncContext,容器工作线程在接收请求并触发后台任务后即可立即归还至容器线程池去服务其他客户端连接,底层 Socket 通道则保持挂起状态,待后台业务线程处理完毕后再通过异步上下文完成响应输出或触发容器再派发。
线程解耦与状态机流转
在默认同步请求处理模型(Thread-Per-Request)下,Tomcat 等 Web 容器的业务吞吐量受限于连接器工作线程池(如 http-nio-8080-exec-*)的最大线程数。当应用中存在远程 RPC 调用、慢速数据库查询、大文件生成或长轮询(Long Polling)消息推送等高延迟 I/O 操作时,大量容器工作线程会陷入阻塞等待状态。一旦容器工作线程池耗尽,即使服务器 CPU 利用率极低,新到达的轻量级请求也会在连接队列中排队甚至被拒绝。
容器线程与业务线程解耦架构
引入 AsyncContext 后,单次 HTTP 请求的生命周期被拆分为“容器主线程接收阶段”与“后台线程异步处理阶段”:
主线程请求接管与挂起:客户端请求进入容器后,由容器工作线程执行前置
Filter链与入口Servlet.service()方法。当业务代码调用request.startAsync()时,容器在底层创建AsyncContext实例(Tomcat 中实现类为AsyncContextImpl),并将当前请求标记为异步挂起状态。主线程无阻塞退出:入口
Servlet.service()将耗时任务连同AsyncContext引用提交给独立的业务线程池(或异步事件队列),随后立即结束方法返回。容器工作线程逆向退出Filter链的后置逻辑后,不会刷新或关闭响应流,也不会回收Request与Response对象,而是直接归还至容器线程池继续处理其他客户端连接。后台线程延后响应:在异步挂起期间,客户端与服务端之间的底层 Socket 连接保持开启。当独立业务线程池完成耗时计算后,可直接通过
AsyncContext持有的响应对象写出数据并终结异步周期,或将请求重新派发回容器工作线程完成视图渲染。

容器内部异步状态机
为了精确管控跨线程场景下的并发状态切换,Tomcat 在 AsyncContextImpl 内部通过 AsyncStateMachine 维护了严格的异步生命周期状态机:
开启过渡态(
STARTING->STARTED):当容器工作线程还在Servlet.service()方法内部调用startAsync()时,状态机由初始的DISPATCHED切换为STARTING;只有当容器工作线程彻底退出Servlet.service()及外层Filter链后,状态机才正式进入STARTED挂起态(若在退出service()前就同步调用了完成或派发方法,则会直接转入MUST_COMPLETE或MUST_DISPATCH状态)。终结过渡态(
COMPLETING->DISPATCHED):当后台线程调用完成方法或发生未处理的超时后,状态机转入COMPLETING,由容器负责刷新响应缓冲区、触发监听器的完成回调,并将请求与响应对象重置回收。再派发过渡态(
DISPATCHING->DISPATCHED):当后台线程调用再派发方法时,状态机进入DISPATCHING,容器重新从工作线程池分配一个容器线程执行目标资源;若目标资源未再次调用startAsync(),则在该次派发执行完毕后自动完成响应并回收资源。

过滤链异步支持与上下文包装
开启 Servlet 异步处理不仅需要在目标 Servlet 上显式声明异步支持,还受到当前请求所经过的整条 Filter 过滤器链的严格约束。
全链路异步配置约束
在容器启动阶段,部署解析器会读取每个 Servlet 与 Filter 的 asyncSupported 元数据属性(默认值为 false)。当业务代码在运行期调用 request.startAsync() 时,容器会检查当前请求调用链上经过的所有组件:
Servlet 级声明:目标 Servlet 必须通过
@WebServlet(asyncSupported = true)注解或web.xml中的<async-supported>true</async-supported>标签开启异步能力。Filter 链级传导约束:凡是拦截了该请求、位于目标 Servlet 前方的每一个
Filter过滤器,也必须全部显式声明asyncSupported = true。只要调用链中存在任何一个未开启异步支持的组件,容器在执行startAsync()时就会立即抛出IllegalStateException: A filter or servlet of the current chain does not support asynchronous operations。传导约束的设计原因:在异步模式下,容器工作线程在退出
Servlet.service()后会立即执行Filter.doFilter()放行语句之后的代码,而此时后台业务线程尚未生成最终响应体。因此,链路上的所有Filter必须明确知晓当前响应在chain.doFilter()返回时尚未完成,避免在后置逻辑中过早关闭资源或假设响应已写出。
原始请求与包装请求保留
开启异步上下文时,ServletRequest 提供了无参开启与带参开启两种方式,二者在跨线程或再派发阶段对装饰器包装类(ServletRequestWrapper / ServletResponseWrapper)的保留行为截然不同:
无参开启模式:固定使用容器连接器最初创建的原始
RequestFacade与ResponseFacade初始化异步上下文。若前置Filter中使用自定义的HttpServletRequestWrapper包装了请求(如实现敏感词过滤或请求体缓存),在后台线程通过asyncContext.getRequest()获取请求或执行容器再派发时,外层包装类将全部丢失。带参开启模式:显式将当前经过
Filter或当前 Servlet 包装后的request与response实例传入异步上下文。此后无论是在后台线程读取请求/响应,还是触发容器再派发,目标组件接收到的均是保留了完整装饰器链的包装对象。java// 1. 显式开启 asyncSupported 属性,声明当前 Servlet 支持异步处理 @WebServlet(urlPatterns = "/api/report", asyncSupported = true) public class AsyncReportServlet extends HttpServlet { // 2. 定义独立的业务线程池,避免占用 Tomcat 容器工作线程 private final ExecutorService bizExecutor = Executors.newFixedThreadPool(10); // 3. 接收请求后立即开启异步上下文并释放容器主工作线程 @Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) { resp.setContentType("application/json;charset=UTF-8"); // 4. 开启异步模式并设置超时阈值(毫秒) AsyncContext asyncContext = req.startAsync(); asyncContext.setTimeout(5000L); // 5. 将耗时任务提交至独立业务线程池异步执行 bizExecutor.submit(() -> { try { PrintWriter writer = asyncContext.getResponse().getWriter(); writer.write("{\"status\": \"COMPLETED\"}"); // 6. 业务响应写入完毕后显式终结异步周期,触发缓冲刷新与资源回收 asyncContext.complete(); } catch (IOException e) { asyncContext.complete(); } }); } }
异步终结与容器再派发
当后台业务线程执行完耗时任务后,必须通过显式指令终结当前挂起的 AsyncContext。规范为此提供了“直接完成响应”与“容器内部再派发”两种终结路径:
| 对比维度 | 直接完成模式 | 容器再派发模式 |
|---|---|---|
| 响应写出主体 | 后台业务线程直接操作输出流写出 | 重新交由容器工作线程执行目标组件写出 |
| 派发类型转换 | 保持初始 DispatcherType 不变 | 切换为 DispatcherType.ASYNC |
| 过滤器链触发 | 不再触发任何 Filter 过滤器 | 触发配置了 ASYNC 派发类型的 Filter |
| 缓冲刷新时机 | 调用完成方法后由容器立即刷新并关闭流 | 目标组件 service() 返回后自动完成并关闭流 |
| 典型应用场景 | 异步返回纯 JSON 报文或长轮询消息推送 | 异步计算数据后交由 JSP 或视图组件渲染页面 |

直接完成模式
在前后端分离的 RESTful 接口或消息推送场景中,后台业务线程可以直接从 AsyncContext 中获取 ServletResponse 的输出流写出 JSON 字符串或二进制数据,随后调用完成方法。该操作会通知容器底层连接器将 OutputBuffer 中的数据刷入 Socket 通道、触发注册在当前上下文上的完成监听回调,并立即回收请求与响应对象。
容器再派发模式
在传统 MVC 视图渲染或需要将“异步数据加载”与“同步响应生成”分离的架构中,后台业务线程本身不直接操作响应输出流,而是将计算结果存入 Request 域属性(Attribute),随后调用派发方法将请求重新派发回容器:
派发类型切换:容器接收到异步再派发指令后,会从容器工作线程池中分配一个线程,将请求的
DispatcherType切换为DispatcherType.ASYNC,并重新组装一条包含所有声明了<dispatcher>ASYNC</dispatcher>的过滤器链。默认路径与指定路径派发:若调用无参派发方法,容器会将请求重新派发回最初开启异步的入口 Servlet(可通过判断
req.getDispatcherType() == DispatcherType.ASYNC区分首次进入与异步回调进入);若传入具体路径,则直接派发至目标 JSP 或目标 Servlet。自动终结闭环:当被派发的目标组件执行完
service()方法且未再次调用startAsync()时,容器会自动替开发者执行响应提交与异步终结流程,无需再手动调用完成方法。在同一轮startAsync()周期内,最多只允许执行一次再派发;若连续调用两次派发方法,容器将直接抛出IllegalStateException。java// 1. 定义支持异步容器再派发的控制器 Servlet @WebServlet(urlPatterns = "/order/asyncQuery", asyncSupported = true) public class AsyncDispatchServlet extends HttpServlet { // 2. 根据派发类型区分首次请求入口与异步再派发入口 @Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { // 3. 若当前为 ASYNC 再派发阶段,直接读取异步结果并输出响应 if (req.getDispatcherType() == DispatcherType.ASYNC) { String result = (String) req.getAttribute("asyncOrderData"); resp.getWriter().write("Order Result: " + result); return; } // 4. 首次 REQUEST 阶段开启异步上下文,并在后台完成后触发容器再派发 AsyncContext asyncContext = req.startAsync(req, resp); CompletableFuture.runAsync(() -> { req.setAttribute("asyncOrderData", "ORD_PAID"); // 5. 将请求重新派发回当前 Servlet(DispatcherType 切换为 ASYNC) asyncContext.dispatch(); }); } }
生命周期监听与超时治理
由于异步任务的执行跨越了多个线程且脱离了主线程的 try-catch 异常捕获栈,一旦后台线程发生死锁、网络超时或未捕获异常,挂起的 Socket 连接将无法正常释放。为此,Servlet 规范提供了 AsyncListener 监听器机制与容器级超时巡检机制。
四大异步事件回调边界
通过向 AsyncContext 注册 AsyncListener 实现类,开发者可以精确监听异步周期的四个关键节点:
完成事件(
onComplete):当异步请求通过正常完成或再派发执行完毕、容器即将回收Request/Response对象前触发。该阶段响应通常已提交,适合执行业务侧内存清理、连接关闭与监控耗时统计。超时事件(
onTimeout):当异步挂起时长达到预设超时阈值(Tomcat 默认超时时间为30000毫秒,设为0或负数表示永不超时),且后台线程尚未调用完成或派发方法时,由容器后台巡检线程触发。异常事件(
onError):当异步再派发执行期间或非阻塞 I/O 读写期间抛出未捕获的Throwable异常时触发。重开异步事件(
onStartAsync):由于监听器必须在首次调用request.startAsync()获取到AsyncContext实例之后才能注册,因此刚注册的监听器不会收到本次startAsync()的通知;仅当请求经过异步再派发并在目标组件中第二次调用startAsync()开启新一轮异步周期时,才会触发该回调(且上一轮注册的监听器不会自动保留到新一轮周期中,若需继续监听需在onStartAsync中重新注册)。
超时与异常回调中的强制终结约束
在实现 onTimeout 与 onError 回调方法时,最容易踩入的陷阱是仅向响应流写入降级提示而遗漏了显式终结调用:
容器对超时回调的兜底检查:当容器后台线程执行完所有注册的
AsyncListener.onTimeout()方法后,会检查当前AsyncContext是否已在监听器内部被调用了完成方法或再派发方法。未终结引发 500 错误派发:若监听器在
onTimeout()中既未调用完成方法也未调用派发方法,容器会强制将响应状态码改写为500 Internal Server Error,触发一次DispatcherType.ERROR类型的错误页派发,随后再强制关闭连接并触发onComplete()。因此,在自定义的onTimeout和onError处理逻辑末尾,必须显式调用完成方法或派发方法以正常接管降级输出。java// 1. 实现 AsyncListener 接口,统一治理异步超时、异常与资源清理 public class SafeAsyncListener implements AsyncListener { // 2. 持有与业务线程共享的原子状态锁,防止超时后业务线程继续操作已回收的响应对象 private final AtomicBoolean completed; public SafeAsyncListener(AtomicBoolean completed) { this.completed = completed; } // 3. 监听异步超时事件,抢占状态锁后输出降级报文并显式调用 complete() @Override public void onTimeout(AsyncEvent event) throws IOException { if (completed.compareAndSet(false, true)) { ServletResponse resp = event.getSuppliedResponse(); resp.getWriter().write("{\"error\": \"ASYNC_TIMEOUT\"}"); event.getAsyncContext().complete(); } } // 4. 监听异步异常事件,确保发生未捕获异常时正常终结异步周期 @Override public void onError(AsyncEvent event) throws IOException { if (completed.compareAndSet(false, true)) { event.getAsyncContext().complete(); } } // 5. 监听异步完成事件,确保最终状态标记为已完成 @Override public void onComplete(AsyncEvent event) { completed.set(true); } // 6. 监听再次开启异步事件(仅在异步再派发后二次调用 startAsync 时触发) @Override public void onStartAsync(AsyncEvent event) { } }
非阻塞流读写扩展
在 Servlet 3.0 的 AsyncContext 模型中,虽然容器主工作线程得到了释放,但后台业务线程在调用 ServletInputStream.read() 读取大请求体或调用 ServletOutputStream.write() 写出大响应体时,底层流操作依然是同步阻塞 I/O。如果客户端网络带宽极低(或遭受慢速连接攻击),后台业务线程池同样会被慢速网络读写阻塞殆尽。
为实现彻底的全链路异步非阻塞,Servlet 3.1 在 AsyncContext 基础上为字节输入流与字节输出流引入了基于事件驱动的非阻塞 I/O 监听器:
非阻塞请求体读取(
ReadListener):开启异步上下文后,业务代码获取ServletInputStream并绑定ReadListener实现类。此后容器底层 Selector 仅在网卡接收缓冲区有数据可读且inputStream.isReady()返回true时,才回调onDataAvailable()方法读取数据块;当全部请求体字节读取完毕后,自动回调onAllDataRead()触发业务处理与响应终结。非阻塞响应体写出(
WriteListener):在写出超大数据流时,业务代码获取ServletOutputStream并绑定WriteListener实现类。当底层 Socket 发送缓冲区可写时,容器回调onWritePossible()方法;开发者在while (outputStream.isReady())循环中分块写入字节。一旦网卡发送缓冲区写满,isReady()立即返回false并挂起写入循环,释放当前线程,待客户端确认接收、缓冲区腾出空间后由容器再次回调onWritePossible()继续写出。
异步并发与对象池回收陷阱
在生产环境中使用 AsyncContext 时,由于打破了单线程顺序执行的封闭边界,极易因线程池误用或跨线程共享 Request/Response 对象引发严重故障。
容器内部线程池借用陷阱
AsyncContext 接口提供了一个看似便捷的 start(Runnable run) 方法用于启动异步任务。然而在 Tomcat 等容器实现中,该方法并未创建独立的业务线程池,而是直接向当前 Servlet 容器自身的连接器工作线程池提交任务。
如果在 asyncContext.start(Runnable) 中执行阻塞式 I/O 操作,实际上只是归还了一个容器工作线程,同时又立刻从同一个容器线程池中借走了另一个容器工作线程,完全丧失了线程解耦的意义。因此,生产级异步开发严禁使用该方法处理耗时业务,必须自行维护独立的业务 ThreadPoolExecutor。

对象池回收与跨线程数据串扰
为了降低高频 GC 压力,Tomcat 容器对 Request 和 Response 对象采用了对象池复用机制(Object Pooling):
回收触发时刻:一旦调用了
asyncContext.complete()(无论是由业务线程正常调用,还是由AsyncListener.onTimeout()超时触发),容器就会立即执行底层的request.recycle()与response.recycle(),清空请求参数、请求头、属性表及输出缓冲区,并将该对象实例放回对象池。跨线程并发污染风险:假设某个请求在
5000ms时触发了超时回调并执行了complete(),此时该Request与Response实例已被回收并立即分配给另一个新进入的客户端请求 B 使用。如果此前那个超时的后台业务线程在5200ms时才执行完毕,并在未做状态校验的情况下继续调用原req.getAttribute()或resp.getWriter().write(),就会直接把上一次超时请求的数据错写进客户端 B 的响应报文中,造成极其隐蔽的跨用户数据泄露或抛出NullPointerException。防御规范:
- 在提交异步任务前,应在容器主线程中提前将所需的请求参数、请求头提取为不可变的普通 Java 值对象(DTO),避免在后台线程中延迟读取
HttpServletRequest。 - 后台业务线程与
AsyncListener之间必须共享一个AtomicBoolean状态锁(如上文SafeAsyncListener示例所示),双方在写出响应或调用complete()前均通过compareAndSet(false, true)抢占唯一执行权,确保已超时的后台线程在苏醒后直接放弃写入。
- 在提交异步任务前,应在容器主线程中提前将所需的请求参数、请求头提取为不可变的普通 Java 值对象(DTO),避免在后台线程中延迟读取