Skip to content

Servlet-请求响应 ​

[TOC]

HttpServletRequest ​

HttpServletRequest 是 Servlet 规范中用于封装客户端 HTTP 请求报文的核心接口。每当 Web 容器(如 Tomcat)接收到一次客户端请求时,底层连接器(Connector)会解析原始 Socket 字节流中的请求行、请求头与请求体,将其封装为实现了 HttpServletRequest 接口的请求对象,并通过 Servlet.service(ServletRequest, ServletResponse) 方法传递给业务组件。

接口继承与门面封装 ​

在 Servlet 规范的接口设计中,HttpServletRequest 继承自通用协议接口 ServletRequest,在此基础上扩展了针对 HTTP 协议特性的访问能力(如请求方法、URI 路径拆解、HTTP 请求头、Cookie 以及 HttpSession 管理)。

以 Tomcat 容器为例,底层连接器解析完 HTTP 报文后,首先创建内部核心类 org.apache.catalina.connector.Request。由于该内部类包含大量容器私有的生命周期管理与底层连接控制方法,若直接将其暴露给应用程序,开发者可通过向下转型(Downcast)篡改容器内部状态。为此,Tomcat 采用门面模式(Facade Pattern),使用 RequestFacade 包装内部 Request 对象,并仅对外暴露 HttpServletRequest 接口规范定义的方法:

  1. 协议解耦层:顶层 ServletRequest 定义与具体应用层协议无关的基础能力,包括请求参数读取、流式通道访问、字符集控制、请求域属性(Attribute)存取及请求转发派发器获取。

  2. HTTP 协议扩展层:子接口 HttpServletRequest 专门绑定 HTTP 协议语义,提供请求方法识别、URL 路径分段提取、请求头检索以及会话追踪能力。

  3. 容器安全隔离层:业务 Servlet 接收到的实际运行期类型是 RequestFacade。该类持有内部 Request 对象的私有引用,将所有公开接口调用委托给内部对象执行;当请求处理结束并归还对象池(recycle())时,RequestFacade 会断开或清理内部状态,防止跨请求数据泄漏。

  4. 装饰器扩展层:规范同时提供了实现了 HttpServletRequest 的包装类 HttpServletRequestWrapper(继承自 ServletRequestWrapper),供开发者在 Filter 过滤器中通过装饰器模式重写参数过滤、字符编码转换或请求体缓存逻辑。

image-20261031102221888

HTTP 报文映射模型 ​

标准 HTTP 请求报文由请求行(Request Line)、请求头(Request Headers)、空行(CRLF)和可选的请求体(Request Body)四部分组成。容器在解析报文时,将不同报文区域映射为 HttpServletRequest 的不同访问维度:

image-20261031102244089

请求行路径拆解 ​

HTTP 请求行包含请求方法(如 GET、POST)、请求目标路径与协议版本(如 HTTP/1.1)。为了支撑 Web 应用的上下文部署与 Servlet 路由匹配,容器会将完整的请求 URL 按层级拆解为多个独立的路径段。

以客户端请求 http://localhost:8080/mall/order/detail/1024?status=paid&page=1(假设应用部署上下文为 /mall,目标 Servlet 映射路径为 /order/*)为例,各路径段的拆解边界如下:

路径组成部分解析值示例结构边界与路由语义
完整请求 URLhttp://localhost:8080/mall/order/detail/1024包含协议方案、主机名、端口与请求 URI,不含 ? 后的查询字符串
请求 URI/mall/order/detail/1024域名端口之后的完整资源路径,等于 contextPath + servletPath + pathInfo
上下文路径/mallWeb 应用在容器中的部署根路径;若部署为根应用(ROOT),则返回空字符串 ""
Servlet 路径/order触发当前 Servlet 映射规则的匹配路径段(不含通配符 * 匹配的后半部分)
额外路径信息/detail/1024位于 Servlet 路径之后、查询字符串之前的子路径;精确匹配或后缀匹配时为 null
查询字符串status=paid&page=1URL 中 ? 之后的原始未解码参数串;未携带查询参数时返回 null

请求头元数据解析 ​

HTTP 请求头紧随请求行之后,采用 Name: Value 键值对结构传递客户端环境、缓存策略、认证凭证及内容协商信息。

容器在解析请求头时遵循 HTTP 规范的大小写不敏感(Case-Insensitive)原则,无论传入 "user-agent" 还是 "User-Agent" 均可命中同一请求头。对于允许在单次请求中出现多次的同名请求头(如 Accept、Accept-Language 或自定义多值头),容器在内部以列表结构维护全部值,支持读取首个值或遍历完整枚举集合。

请求体载荷映射 ​

当客户端发起 POST、PUT 等携带载荷的请求时,空行之后的二进制字节流即构成请求体。容器本身不会在接收请求时立即全量读取请求体,而是根据请求头中的 Content-Type 与 Content-Length 决定后续消费方式:表单类型可交由容器自动解析为参数表,而 JSON、XML 或二进制流则保留在底层输入通道中由开发者按需读取。

java
// 1. 定义 Servlet 组件,演示请求行路径拆解与请求头提取
@WebServlet("/order/*")
public class RequestLineHeaderServlet extends HttpServlet {

  // 2. 重写 doGet 方法,解析客户端请求报文元数据
  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    // 3. 拆解请求行中的 URI 各级路径段与查询字符串
    String method = req.getMethod();
    String requestURI = req.getRequestURI();
    String contextPath = req.getContextPath();
    String servletPath = req.getServletPath();
    String pathInfo = req.getPathInfo();
    String queryString = req.getQueryString();

    // 4. 读取请求头中的客户端标识与内容协商信息(不区分大小写)
    String userAgent = req.getHeader("User-Agent");
    String acceptEncoding = req.getHeader("Accept-Encoding");

    // 5. 获取客户端网络地址信息
    String remoteAddr = req.getRemoteAddr();
  }
}

请求参数延迟解析 ​

在 Web 开发中,客户端既可以通过 URL 查询字符串传递参数,也可以通过请求体表单传递参数。HttpServletRequest 对外提供了统一的参数读取视图,并在底层采用延迟解析(Lazy Parsing)策略优化性能。

image-20261031102301858

查询串与表单合并 ​

容器在创建 Request 对象时,并不会立即解析 URL 查询字符串或请求体中的表单数据,而是将解析动作推迟到业务代码首次调用参数读取方法(如 getParameter、getParameterValues、getParameterNames 或 getParameterMap)的时刻:

  1. 按需触发解析:当首次调用任一参数获取方法时,容器检查内部 parametersParsed 标志位;若为 false,则立即启动参数解析器并将标志位置为 true,后续调用直接复用已解析的内存哈希表。

  2. 多源参数合并:解析器首先解析 URL 中的查询字符串(Query String),随后检查当前请求是否为满足条件的表单请求;若是,则继续读取请求体字节流并解析表单键值对,统一存入同一个内部结构(Map<String, String[]>)。

  3. 同名参数保序追加:若同一个参数名在 URL 查询字符串与 POST 请求体中同时出现(或来自表单中的多个同名复选框),容器不会覆盖原有值,而是按“URL 参数在前、请求体参数在后”的顺序合并为字符串数组。读取单值方法固定返回数组的第 0 个元素,而读取多值方法则返回完整数组。

  4. 只读视图保护:容器返回的 ParameterMap 在外层被包装为不可修改映射(Locked Map),任何试图直接调用 .put() 或 .remove() 修改请求参数的操作都会抛出 IllegalStateException。

内容类型解析边界 ​

并非所有 POST 请求的请求体都会被容器自动解析到参数表中。根据 Servlet 规范,容器仅在同时满足以下三个条件时,才会自动消费请求体并提取表单参数:

  1. HTTP 请求方法为 POST。

  2. 请求头 Content-Type 的媒体类型严格匹配 application/x-www-form-urlencoded(忽略尾随的 ;charset=UTF-8 参数),或配置了 @MultipartConfig 且媒体类型为 multipart/form-data。

  3. 业务代码在调用参数获取方法之前,未曾主动调用过 getInputStream() 或 getReader() 消费请求体流。

当客户端发送 Content-Type: application/json 或 text/xml 格式的 POST 请求时,容器只会解析 URL 查询字符串中的参数,而不会触碰请求体。此时若通过参数方法获取 JSON 字段,返回值恒为 null。

java
// 1. 定义表单参数处理 Servlet
@WebServlet("/member/register")
public class ParameterParseServlet extends HttpServlet {

  // 2. 处理 POST 表单提交,触发底层参数的首次延迟解析
  @Override
  protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    // 3. 指定请求体解码字符集,必须在首次读取参数前调用
    req.setCharacterEncoding("UTF-8");

    // 4. 获取单值参数(合并查询字符串与 x-www-form-urlencoded 请求体)
    String username = req.getParameter("username");

    // 5. 获取同名多值参数(如复选框或 URL 与请求体同名参数)
    String[] hobbies = req.getParameterValues("hobby");

    // 6. 获取不可修改的参数映射快照
    Map<String, String[]> paramMap = req.getParameterMap();
  }
}

请求体流读取与互斥 ​

对于 JSON 接口交互、XML 报文接收或二进制文件上传等非传统表单场景,开发者需要直接操作 HttpServletRequest 暴露的底层输入流通道。容器为此提供了字节输入流 ServletInputStream 与字符输入流 BufferedReader 两种读取方式,但二者之间以及流与参数解析之间存在严格的状态互斥约束。

image-20261031102352459

字节流与字符流互斥 ​

在同一个请求生命周期内,容器内部维护了两个布尔状态标记:usingInputStream 与 usingReader:

  1. 字节流通道:适用于读取原始二进制数据(如文件字节流或交给第三方 JSON 框架直接按字节反序列化)。首次调用 getInputStream() 时,容器校验 usingReader 是否为 true;若为 true 则直接抛出 IllegalStateException,否则将 usingInputStream 设为 true 并返回 ServletInputStream。

  2. 字符流通道:适用于按行或按字符读取文本载荷。首次调用 getReader() 时,容器校验 usingInputStream 是否为 true;若为 true 同样抛出 IllegalStateException,否则根据当前请求字符集创建包装了底层缓冲区的 BufferedReader,并将 usingReader 设为 true。

  3. 互斥根源:由于 BufferedReader 内部包含字符解码缓冲区(StreamDecoder),一旦开启字符流预读,底层字节流游标将不再与已读取字符位置严格对齐,因此规范强制禁止在同一请求中混用两种流。

参数解析与流读取冲突 ​

由于底层网络输入流属于单向一次性消费资源(未额外包装缓存时不支持 reset() 回退),参数解析器与手动流读取共享同一个底层通道:

  1. 先读参数后读流:在 application/x-www-form-urlencoded 类型的 POST 请求中,一旦先调用了 getParameter(),容器内部就会将请求体字节流读取殆尽以构建参数表。此后业务代码若再调用 getInputStream() 或 getReader(),虽然不会抛出互斥异常,但读取到的流已经到达末尾(EOF),无法读出任何内容。

  2. 先读流后读参数:若业务代码(或前置 Filter 过滤器)率先调用了 getInputStream() 或 getReader() 读取请求体,容器内部会将流状态标记为已占用。此后调用 getParameter() 时,容器检测到流已被外部打开,将跳过请求体解析步骤,此时只能获取到 URL 查询字符串中的参数,表单请求体中的参数全部丢失。

  3. 多次读取解决方案:若需在日志过滤器中记录请求体日志,同时允许后续 Servlet 或框架继续读取请求体,必须自定义继承自 HttpServletRequestWrapper 的包装类,在首次读取时将请求体字节数组缓存至内存,并重写 getInputStream() 与 getReader() 使其每次均从内存字节数组生成新的流实例。

    java
    // 1. 定义处理非表单载荷(如 application/json)的 Servlet
    @WebServlet("/api/order")
    public class JsonBodyStreamServlet extends HttpServlet {
    
      // 2. 通过字符流读取请求体中的原始 JSON 文本
      @Override
      protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        // 3. 设置请求体字符解码格式,防止字符流读取中文乱码
        req.setCharacterEncoding("UTF-8");
    
        // 4. 获取包装后的字符流,注意同一请求内不可再调用 getInputStream()
        BufferedReader reader = req.getReader();
        StringBuilder jsonBuilder = new StringBuilder();
        String line;
    
        // 5. 逐行读取请求体内容并拼接为完整字符串
        while ((line = reader.readLine()) != null) {
          jsonBuilder.append(line);
        }
        String rawJson = jsonBuilder.toString();
      }
    }

字符编码与乱码治理 ​

HTTP 报文在网络中以字节序列传输,当客户端采用 UTF-8 编码中文字符,而服务端容器采用不支持中文的单字节编码 ISO-8859-1 进行解码时,就会产生中文乱码。在 HttpServletRequest 中,请求体与 URL 查询字符串分属两条独立的解码链路。

请求体解码时机 ​

POST 请求体的字符解码由 ServletRequest.setCharacterEncoding(String env) 控制(或在 Servlet 4.0 及以上版本的 web.xml 中配置 <request-character-encoding>):

  1. 默认编码演进:根据 Servlet 规范,若客户端未在 Content-Type 请求头中显式附带 charset 属性且服务端未手动设置编码,传统容器默认使用 ISO-8859-1 解码请求体。

  2. 前置调用约束:由于请求参数采取延迟解析机制,且 getReader() 在首次调用时初始化解码器,setCharacterEncoding("UTF-8") 必须在首次调用任何参数读取方法或 getReader() 之前执行。一旦参数已经解析完毕或字符流已经创建,后续再调用 setCharacterEncoding 将完全失效(静默忽略,不抛异常)。

URI 查询串解码 ​

URL 路径与 ? 后的查询字符串(包括 GET 请求参数以及 POST 请求 URL 上附带的参数)由容器底层的 HTTP 连接器(Connector)在解析请求行阶段直接处理,不受 request.setCharacterEncoding() 方法控制:

  1. 容器级默认编码:从 Tomcat 8.0(对应 Servlet 3.1)开始,连接器默认使用 UTF-8 解码 URI 查询字符串,因此现代容器中 GET 请求中文参数默认不会乱码。

  2. 旧版本兼容配置:在 Tomcat 7 及更早版本中,连接器默认采用 ISO-8859-1 解码 URI。若需支持中文查询参数,需在容器 server.xml 的 <Connector> 节点中显式配置 URIEncoding="UTF-8",或在代码中将获取到的乱码字符串按 ISO-8859-1 还原为原始字节数组后再使用 UTF-8 重新构造字符串。

请求域属性传递 ​

除了封装客户端传入的报文数据外,HttpServletRequest 还是 Servlet 三大域对象(Request 域、Session 域、Application/ServletContext 域)中生命周期最短、隔离粒度最细的容器组件。

  1. 属性与参数的本质区别:

    • 请求参数(Parameter):源自客户端 HTTP 报文,数值类型固定为 String 或 String[],在服务端属于只读数据,用于完成“客户端到服务端”的数据入参。
    • 请求域属性(Attribute):存储在容器内部维护的 Map<String, Object> 哈希表中,完全由服务端通过代码动态写入、覆盖或移除,值类型可为任意 Java 对象(如实体类、集合、分页结果),用于在同一次请求链路的多个服务端组件(如 Filter、入口 Servlet、转发目标 Servlet 或 JSP)之间传递上下文数据。
  2. 生命周期与线程安全:

    • 生命周期边界:Request 域自客户端请求进入容器创建 Request 对象起生效,历经所有匹配的 Filter 与 RequestDispatcher.forward() / include() 转发链路,直至最终响应提交并结束本次 service() 调用后立即销毁(内部属性表被清空回收)。若使用 sendRedirect() 重定向,由于客户端会发起全新的第二次 HTTP 请求,原 Request 域属性将无法跨越重定向保留。

    • 天然线程安全:在标准同步请求处理模型下,每个 HttpServletRequest 实例绑定在独立的工作线程(Worker Thread)中顺序执行,不存在多线程并发读写同一个 Request 域的情况,因此读写请求域属性无需额外加锁同步。

      java
      // 1. 定义业务处理入口 Servlet,向请求域绑定处理结果
      @WebServlet("/order/detail")
      public class OrderDetailServlet extends HttpServlet {
      
        // 2. 查询业务数据并挂载至当前 Request 域,随后转发至视图组件
        @Override
        protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
          // 3. 提取客户端传入的只读请求参数
          String orderId = req.getParameter("id");
      
          // 4. 将服务端组装的业务对象存入 Request 域属性映射表
          req.setAttribute("currentOrderId", orderId);
          req.setAttribute("orderStatus", "PAID");
      
          // 5. 通过请求转发共享当前 HttpServletRequest 实例
          RequestDispatcher dispatcher = req.getRequestDispatcher("/WEB-INF/views/order.jsp");
          dispatcher.forward(req, resp);
        }
      }

API: ServletRequest【待补充】 ​

API: HttpServletRequest【待补充】 ​

API: HttpServletRequestWrapper【待补充】 ​

API: ServletInputStream【待补充】 ​

HttpServletResponse ​

HttpServletResponse 是 Servlet 规范中用于构建并向客户端发送 HTTP 响应报文的核心接口。当 Web 容器接收到客户端请求时,会同时创建与 HttpServletRequest 成对出现的 HttpServletResponse 实例,并将其传入 Servlet.service(ServletRequest, ServletResponse) 方法。开发者通过操作该对象设置 HTTP 状态码、配置响应头元数据以及向底层输出流缓冲区写入响应体载荷。

接口继承与门面封装 ​

与请求体系对称,Servlet 规范将响应接口划分为协议无关的顶层接口与绑定 HTTP 协议语义的子接口,并在容器实现层采用门面模式(Facade Pattern)与装饰器模式(Decorator Pattern)保障安全性与可扩展性:

  1. 协议解耦层:顶层接口 ServletResponse 定义了通用响应输出能力,包括响应字符集设置、MIME 内容类型声明、二进制字节输出流与字符输出流获取,以及底层输出缓冲区的容量控制、刷新与重置。

  2. HTTP 协议扩展层:子接口 HttpServletResponse 继承自 ServletResponse,扩展了针对 HTTP 协议的专属操作,涵盖 HTTP 状态码常量与设置、HTTP 响应头(Header)的覆写与追加、Cookie 凭据下发、重定向响应生成以及 URL 会话标识重写。

  3. 容器安全隔离层:以 Tomcat 容器为例,连接器(Connector)内部维护的核心响应实现类为 org.apache.catalina.connector.Response。为防止应用程序通过强制类型转换调用容器内部的底层网络刷新、连接关闭或对象池回收方法(如 recycle()),Tomcat 使用实现了 HttpServletResponse 接口的 ResponseFacade 包装内部 Response 对象,仅向业务 Servlet 暴露标准规范方法。

  4. 装饰器扩展层:规范提供了实现了 HttpServletResponse 的标准包装类 HttpServletResponseWrapper(继承自 ServletResponseWrapper)。在 Filter 过滤器链中,若需对响应内容进行后置处理(如全站 GZIP 压缩、敏感词脱敏、响应报文签名或追加统一页脚),必须通过继承 HttpServletResponseWrapper 替换默认的底层输出流,将原本直接发往容器缓冲区的响应字节拦截至内存缓冲流中,待目标 Servlet 执行完毕后再统一改写并输出。

image-20261031102524785

HTTP 响应报文映射模型 ​

标准 HTTP 响应报文由状态行(Status Line)、响应头(Response Headers)、空行(CRLF)和响应体(Response Body)四部分组成。HttpServletResponse 将不同报文区域的组装逻辑解耦为独立的操作维度:

image-20261031102547983

状态行控制与错误页派发 ​

HTTP 状态行包含协议版本(如 HTTP/1.1)、三位数字状态码(Status Code)以及原因短语(Reason Phrase)。当业务代码未显式指定状态码时,容器默认返回 200 OK。

在设置非 200 状态码时,HttpServletResponse 提供了两种语义截然不同的控制机制:

对比维度纯状态码设置(setStatus)容器错误派发(sendError)
状态行作用仅修改 HTTP 响应状态码修改状态码并标记响应进入错误状态
缓冲区处理保留当前已写入缓冲区的响应体立即清空未提交缓冲区中的原有内容
响应体来源由当前 Servlet 自行通过流写出由容器生成的默认错误页或自定义错误页填充
错误页匹配不触发 web.xml 错误页路由触发 web.xml 中 <error-page> 规则匹配
典型场景RESTful 接口返回 400/401/500 JSON 报文传统 Web 页面跳转至统一 404/500 HTML 错误视图

在前后端分离架构中,后端接口通常需要返回状态码为 400 或 500 且响应体为自定义 JSON 结构的报文。此时必须使用纯状态码设置方式;若误用错误派发方式,容器将直接丢弃已写入的 JSON 字符串,转而向客户端输出一段 HTML 格式的容器错误页面,并立即提交响应。

响应头覆写与追加策略 ​

HTTP 响应头采用 Name: Value 键值对结构,用于向客户端声明服务端环境、内容编码格式、缓存控制策略、跨域权限(CORS)以及文件下载附件指令。

容器内部通过 MimeHeaders 结构维护响应头集合,并提供两种写入语义:

  1. 覆写模式(Set 语义):当响应头集合中已存在同名 Header(不区分大小写)时,新值会彻底覆盖此前设置的所有同名旧值。该模式适用于在单个响应中仅允许出现唯一值的元数据头,例如 Content-Type、Content-Length、Location 或 Cache-Control。

  2. 追加模式(Add 语义):无论响应头集合中是否已存在同名 Header,均保留原有值并在其后追加一条新的同名 Header 记录(或在协议层合并为逗号分隔的多值列表)。该模式适用于允许单次响应下发多个实例的头部,例如通过多次下发 Set-Cookie 写入多个 Cookie,或配置多条 Access-Control-Expose-Headers 规则。

    java
    // 1. 定义响应状态码与响应头控制示例 Servlet
    @WebServlet("/api/resource")
    public class StatusHeaderServlet extends HttpServlet {
    
      // 2. 重写 doGet 方法,组装响应状态行与元数据头
      @Override
      protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        // 3. 设置 HTTP 状态码(仅修改状态行,不触发容器默认错误页)
        resp.setStatus(HttpServletResponse.SC_OK);
    
        // 4. 覆写模式设置响应头,同名键仅保留最后一次设置的值
        resp.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
        resp.setDateHeader("Expires", 0L);
    
        // 5. 追加模式添加同名响应头,允许多个值并存
        resp.addHeader("Access-Control-Expose-Headers", "X-Request-Id");
        resp.addHeader("Access-Control-Expose-Headers", "X-RateLimit-Remaining");
      }
    }

响应缓冲区与提交机制 ​

按照 HTTP 协议传输规范,服务端向 Socket 通道写回数据时,必须严格遵循“先发送状态行与响应头、再发送空行、最后发送响应体”的字节流顺序。若业务代码每调用一次输出流写操作就立即将字节推入网卡,一旦开始写入第一字节响应体,状态行与响应头就已发往客户端,后续代码若捕获到业务异常将无法再修改状态码或执行重定向。

为解决这一时序矛盾,Web 容器在 HttpServletResponse 底层引入了响应输出缓冲区(在 Tomcat 中对应 OutputBuffer,默认缓冲区容量通常为 8KB)。

image-20261031102610622

缓冲区写入与刷新阈值 ​

当业务代码通过输出流写出响应体时,数据首先暂存在内存缓冲区中,此时 HTTP 状态行与响应头尚未写入底层网络通道,响应处于未提交状态(Uncommitted)。只有当满足以下任一触发条件时,容器才会将状态行、响应头与当前缓冲区中的响应体一并序列化并刷入底层 Socket 通道,使响应正式进入已提交状态(Committed):

  1. 缓冲区容量溢出:累计写入缓冲区的响应体字节数达到或超过预设的缓冲区大小(可通过 getBufferSize() 查看),容器自动触发首次刷新(Flush)以腾出内存空间。

  2. 显式刷新或关闭调用:业务代码主动调用了 response.flushBuffer(),或直接调用了输出流的 .flush()、.close() 方法。

  3. 达到声明的内容长度:业务代码预先通过 setContentLength() 或 Content-Length 响应头指定了精确字节长度,且累计写入输出流的字节数已达到该阈值。

  4. 终止型操作或生命周期结束:调用了 sendRedirect()、sendError(),或当前请求完整走完 Servlet.service() 与 Filter 链路并由容器执行收尾刷新。

响应提交后的状态锁定 ​

响应是否已经提交(可通过 isCommitted() 检测)是 Servlet 响应控制中最关键的状态分水岭。一旦响应进入 Committed 状态,意味着状态行与响应头字节已经离开服务端网卡发往客户端,不可撤回:

  1. 状态码与响应头修改静默失效:在响应提交之后,任何调用 setStatus()、setHeader()、addHeader()、addCookie()、setContentType() 或 setCharacterEncoding() 的操作都会被容器直接忽略(不会抛出异常,但也不会生效)。

  2. 缓冲区重置与跳转抛出异常:在响应未提交前,调用 resetBuffer() 可清空已写入缓冲区的响应体(保留状态码与响应头),调用 reset() 则会同时清空缓冲区、状态码与响应头。但一旦响应已经提交,再调用 reset()、resetBuffer()、sendRedirect()、sendError() 或 RequestDispatcher.forward() 时,容器将直接抛出 IllegalStateException。

因此,在编写包含重定向、转发或错误跳转逻辑的 Servlet 时,必须在调用跳转方法后立即使用 return; 终止当前方法执行,防止后续代码继续向输出流写入数据或触发二次提交异常。

java
// 1. 定义演示响应缓冲区控制与提交边界的 Servlet
@WebServlet("/buffer/demo")
public class BufferControlServlet extends HttpServlet {

  // 2. 演示缓冲区大小调整、未提交重置与强制刷新提交
  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    // 3. 在写入任何响应内容前调整底层缓冲区容量
    resp.setBufferSize(16384);
    resp.setContentType("text/plain;charset=UTF-8");

    // 4. 写入临时数据后检查是否已提交,未提交时可安全清空缓冲内容
    PrintWriter writer = resp.getWriter();
    writer.write("Temporary draft content...");
    if (!resp.isCommitted()) {
      resp.resetBuffer();
    }

    // 5. 写入最终业务载荷并主动刷新缓冲区,触发响应进入 Committed 状态
    writer.write("Final committed payload.");
    resp.flushBuffer();
  }
}

响应体流输出与互斥 ​

为了兼顾二进制媒体传输与文本内容渲染,ServletResponse 提供了字节输出流 ServletOutputStream 与字符输出流 PrintWriter 两条输出通道。二者底层共享同一个容器 OutputBuffer,但在单次请求处理周期内严格互斥。

image-20261031102631920

字节流与字符流互斥 ​

容器在内部 Response 对象中维护了 usingOutputStream 与 usingWriter 两个互斥状态位:

  1. 二进制字节通道:getOutputStream() 返回 ServletOutputStream,适用于输出图片验证码、PDF 文档、压缩包下载字节流,或交由 Jackson、Fastjson 等序列化框架直接写出 UTF-8 字节数组。首次调用时,容器检查 usingWriter 是否为 true;若为 true 则抛出 IllegalStateException,否则将 usingOutputStream 标记为 true。

  2. 字符文本通道:getWriter() 返回 PrintWriter,适用于直接拼接并输出 HTML 片段、纯文本或 JSON 字符串。首次调用时,容器检查 usingOutputStream 是否为 true;若为 true 同样抛出 IllegalStateException,否则根据当前响应字符集初始化字符编码转换器,并将 usingWriter 标记为 true。

  3. 互斥设计原因:PrintWriter 内部封装了字符到字节的编码缓冲区(WriteConvertor),字符写入后并非总是立即转化为底层字节;若允许在同一响应中交替调用 ServletOutputStream 与 PrintWriter,将导致原始字节直接穿插在未刷新的多字节字符编码序列中间,造成客户端解码错位与数据损坏。

容器资源回收与流关闭边界 ​

在标准 Servlet 开发中,当 doGet 或 doPost 方法执行完毕返回容器后,Tomcat 等容器会自动刷新 OutputBuffer 并关闭底层输出流,随后将 Response 对象重置放回对象池。因此,常规业务代码无需在 finally 块中强制手动关闭 PrintWriter 或 ServletOutputStream。

但若业务代码主动调用了 writer.close() 或 out.close(),该操作会立即触发响应提交并将流标记为已关闭;此后在当前请求后续链路(如 RequestDispatcher.include() 包含的后续组件或后置 Filter)中向输出流写入的任何内容都将被静默丢弃。

java
// 1. 定义使用字节输出流返回二进制数据的 Servlet
@WebServlet("/image/captcha")
public class BinaryStreamServlet extends HttpServlet {

  // 2. 通过 ServletOutputStream 输出原始字节数组
  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    // 3. 声明二进制媒体类型与响应体字节长度
    byte[] imageBytes = new byte[]{0x47, 0x49, 0x46, 0x38, 0x39, 0x61};
    resp.setContentType("image/gif");
    resp.setContentLength(imageBytes.length);

    // 4. 获取字节流写出数据,同一请求内严禁再调用 getWriter()
    ServletOutputStream out = resp.getOutputStream();
    out.write(imageBytes);
  }
}

字符编码与乱码治理 ​

当使用 PrintWriter 输出包含中文字符的文本响应时,数据会经历“服务端将 Java String 编码为字节流”与“客户端浏览器将字节流解码为字符”两个阶段。只要两端采用的字符集不一致,就会出现中文问号(???)或乱码字符。

服务端编码与浏览器解码对齐 ​

  1. 默认编码陷阱:根据 Servlet 规范(Servlet 4.0 显式配置前),若服务端未指定响应字符集,容器在初始化 PrintWriter 时默认采用单字节编码 ISO-8859-1。由于 ISO-8859-1 码表不包含中文字符,所有输出的中文字符在服务端编码阶段就会直接丢失高字节信息,变成 ASCII 码为 0x3F 的问号 ?。

  2. 仅设置服务端编码的局限:单独调用 response.setCharacterEncoding("UTF-8") 只能将服务端 PrintWriter 的编码器切换为 UTF-8,但不会在 HTTP 响应中生成 Content-Type 响应头。当浏览器接收到没有 charset 声明的字节流时,可能会按照操作系统本地默认编码(如中文 Windows 下的 GBK)去解码 UTF-8 字节序列,从而产生乱码(如“浣犲ソ”)。

  3. 标准对齐方案:通过调用 response.setContentType("text/html;charset=UTF-8")(或 application/json;charset=UTF-8),容器会在底层同时完成两项工作:

    • 提取 ;charset= 后的字符集名称,自动将服务端响应编码(characterEncoding)设置为 UTF-8。
    • 向客户端下发完整的 Content-Type: text/html;charset=UTF-8 响应头,指示浏览器同样使用 UTF-8 解码响应体。

编码设置前置约束 ​

与 HttpServletRequest 类似,HttpServletResponse 的字符编码设置同样具有严格的调用时序要求:

  1. 必须在获取 PrintWriter 之前调用:容器在首次执行 response.getWriter() 时,会根据当前时刻已配置的 characterEncoding 实例化字符编码转换器并绑定到 PrintWriter 上。若先调用了 getWriter(),后调用 setCharacterEncoding("UTF-8") 或 setContentType("text/html;charset=UTF-8"),虽然响应头中的 charset 属性在未提交前仍能更新,但 PrintWriter 内部绑定的编码器已经固化为 ISO-8859-1,写出的中文依然会变成 ?。

  2. 必须在响应提交之前调用:一旦响应进入 Committed 状态,响应头已发往客户端,此时再调用任何编码或内容类型设置方法均不再生效。

    java
    // 1. 定义字符流编码对齐与中文响应输出 Servlet
    @WebServlet("/api/profile")
    public class CharsetEncodingServlet extends HttpServlet {
    
      // 2. 演示正确设置响应字符集并输出 JSON 中文文本
      @Override
      protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        // 3. 在调用 getWriter() 前同时指定 MIME 类型与 UTF-8 字符集
        resp.setContentType("application/json;charset=UTF-8");
    
        // 4. 获取绑定了 UTF-8 编码器的字符输出流并写出中文内容
        PrintWriter writer = resp.getWriter();
        writer.println("{\"status\": \"success\", \"message\": \"订单支付成功\"}");
      }
    }

API: ServletResponse【待补充】 ​

API: HttpServletResponse【待补充】 ​

API: HttpServletResponseWrapper【待补充】 ​

API: ServletOutputStream【待补充】 ​