企业官网建设流程全解析

做Java Web的朋友，只要在Filter里处理过响应内容，基本都撞过同一堵墙：想统一给接口响应加个版本号、替换一段敏感词、给HTML注入一份统计脚本，或者单纯想拿到响应体打日志。于是顺手在chain.doFilter()后面直接response.getOutputStream().write(...)，结果发现页面上什么都没有，或者抛出一个IllegalStateException。原因很直接：Servlet在把响应交还给容器的过程里，输出流是单行道，等doFilter返回时响应很可能已经提交甚至已经写回客户端了，你再也插不进一个字。这个问题的标准解法，就是HttpServletResponseWrapper。

它是Servlet规范里专门用来包装响应对象的装饰器基类。思路并不玄乎：在Filter这一层用一个自定义包装器把响应“截”住，让下游Servlet的输出先落到你准备的缓存区，处理完之后你再决定怎么把内容放回真实的响应流。这篇文章我会从底层原理、核心骨架、完整实操讲到一系列常见坑，末尾再给几种进阶玩法，适合正在写通用中间件、网关层或统一响应处理的Web开发者。

1. 先搞懂问题：为什么直接在Filter里改响应不生效

1.1 Servlet响应管道的运行规则

要理解HttpServletResponseWrapper，先得认清Servlet的响应模型。一个Servlet处理完业务后，内容是通过HttpServletResponse的getWriter()或getOutputStream()输出的，而容器在收到doFilter()返回的信号后，会把缓冲区内容真正发到客户端。注意“通过响应头提交”这个动作是单向的：一旦flushBuffer()被调用，或者缓冲区写满，响应就处于isCommitted()为true的状态。提交之后，状态码、响应头都不能改，输出流的写入也不再有意义。

很多人在Filter里踩坑，是因为下意识把响应流当成了一个普通的、随时可写的Java流。实际不是这样，它背后连着容器的socket写逻辑。你在chain.doFilter()之后拿到的大概率已经是一条被写过了、甚至被关闭的流，继续写要么拼到原有内容后面，要么直接报错。套用一句更直白的话：响应输出就像一场已经讲到一半的现场直播，你在直播结束之后塞了一个新的开头进去，观众是看不到的。

1.2 装饰器模式从源码里走出来的典型用法

HttpServletResponseWrapper本质上是装饰器模式在Servlet规范里的落地实现。它持有原始HttpServletResponse引用，并实现了接口里的所有方法，默认全部透传给被装饰的response。这就给你一个天然的“拦截点”：只要继承Wrapper，重写你想劫持的方法，就能改变下游对象的行为，而下游的Servlet完全无感知。

往缓存里蓄水的思路是一个很好的类比。原始响应流是一根直通客户端的水管，你用包装器在中间接了一个水桶，下游Servlet输出的内容全部先流进这个水桶。处理完业务后，你取出水桶里的内容，替换、压缩、签名或记录，再把处理后的水放回水管。整个过程对上层Servlet透明，对容器透明，却能完整控制响应体。

1.3 关键一步：传给chain.doFilter的必须是包装器

有一个非常容易被忽略的细节：chain.doFilter()传入的下游请求和响应，直接决定了Servlet到底往哪里输出。如果你在Filter里创建了一个Wrapper，但调用链时仍然传原始response，那包装器就是个空壳，Servlet的内容全部走原路发走了，你什么都截不到。

正确姿势是把包装器传入调用链：

BufferedHttpServletResponseWrapper wrapper = new BufferedHttpServletResponseWrapper(response); chain.doFilter(request, wrapper); byte[] data = wrapper.getBufferContents();

从这一刻开始，下游所有Servlet、JSP、其他Filter拿到的response，都是你包装之后的对象。它们调用的getOutputStream()、getWriter()实际上调用的是你重写后的方法，输出自然会落入你准备好的缓存区。这也是整个方案能够成立的前提。

2. 自定义响应包装器的标准骨架

2.1 核心方法：getOutputStream与getWriter的重写

既然要让下游的输出先落进缓存区，最重要的就是重写这两个流入口。同时需要遵守Servlet规范的两个约束：第一，getWriter()和getOutputStream()不能混用，一旦被调用过另一条路径就要抛IllegalStateException；第二，同一个方法多次调用应该返回同一个实例。

我平时最常用的骨架是这样的：

public class BufferedHttpServletResponseWrapper extends HttpServletResponseWrapper { private final ByteArrayOutputStream buffer = new ByteArrayOutputStream(); private ServletOutputStream outputStream; private PrintWriter writer; public BufferedHttpServletResponseWrapper(HttpServletResponse response) { super(response); } @Override public ServletOutputStream getOutputStream() throws IOException { if (writer != null) { throw new IllegalStateException("getWriter() has already been called"); } if (outputStream == null) { outputStream = new ServletOutputStream() { @Override public boolean isReady() { return true; } @Override public void setWriteListener(WriteListener writeListener) { // 同步响应场景下不需要监听器，空实现即可 } @Override public void write(int b) throws IOException { buffer.write(b); } @Override public void write(byte[] b, int off, int len) throws IOException { buffer.write(b, off, len); } }; } return outputStream; } @Override public PrintWriter getWriter() throws IOException { if (outputStream != null) { throw new IllegalStateException("getOutputStream() has already been called"); } if (writer == null) { writer = new PrintWriter(new OutputStreamWriter(buffer, getCharacterEncoding())); } return writer; } @Override public String getCharacterEncoding() { String encoding = super.getCharacterEncoding(); return encoding == null ? "UTF-8" : encoding; } @Override public void flushBuffer() throws IOException { // 空实现，阻止响应提前提交 } public byte[] getBufferContents() { if (writer != null) { writer.flush(); } return buffer.toByteArray(); } }

如果用的是Jakarta命名空间的容器，只需要把javax.servlet替换成jakarta.servlet。这个骨架看起来简单，但里面有几个细节决定成败。

2.2 编码处理是乱码的命门

看getWriter()里的代码，PrintWriter构造时传入了getCharacterEncoding()的返回值。这就是很多人中文乱码的根源：如果你直接用new OutputStreamWriter(buffer)而不指定编码，会使用平台默认编码，在Linux服务器上通常是UTF-8，在Windows上可能是GBK，于是同一个项目换个环境就乱码。

更隐蔽的是，Servlet容器的默认编码在不同版本之间并不一致，很多时候super.getCharacterEncoding()返回null。我在包装器里重写了这个方法，null时统一回落到UTF-8。这个习惯强烈建议保留，能救很多次命。

同时要明白PrintWriter的内部机制：它有自己的字符流缓冲，写入的内容不会立刻进入ByteArrayOutputStream。如果直接从外部调用getBufferContents()取值，可能拿到的是一份不完整的字节数组。所以方法里第一步就是writer.flush()，把PrintWriter缓冲区的数据全部刷到底层字节流中。这个步骤少了，症状就是“内容不全，只剩下后半段”或者“内容完全为空”。

2.3 flushBuffer空实现背后的提交时机

默认情况下，HttpServletResponseWrapper.flushBuffer()会直接透传原始response的flushBuffer()。一旦Servlet或者某个下游组件调用了这个方法，原始响应就会进入“已提交”状态，响应头和状态码被钉死。但我们的目标是先让内容进缓存，等待业务处理完毕后再写回，所以必须对这个方法做空处理。

有一个很极端的例子：某个接口在业务里主动调用了response.flushBuffer()，按默认透传，容器会把一个空的响应头发给客户端。等你处理完缓存里的内容想写回时，连接已经开始传送数据，一切都晚了。重写为空实现后，flushBuffer()只影响包装器自己的虚拟缓冲，原始响应始终保有待写状态，逻辑上所有内容都还握在你手里。

如果你担心直接空实现会导致下游某些依赖flushBuffer语义的代码异常，可以在里面只做buffer的刷新，不要碰原始response。就我实际经验，绝大多数场景空实现完全够用，偶尔出现性能问题也是因为下游大量调用flushBuffer，那属于业务设计不合理，不该由这个类背锅。

3. 实战：基于包装器实现全站内容替换

3.1 场景设定：给所有HTML页面统一注入一段代码

理论讲再多，不如一个完整Demo。假设我们有一个老系统，几百个JSP和Servlet页面，现在要统一给所有HTML响应注入一段埋点脚本。直接改每个页面工程量太大，也不方便后续维护，最合理的做法就是在Filter层一次性完成。

目标很明确：只处理text/html类型的响应，拿到完整HTML后，在</body>前插入一段脚本。要做到这一点，就需要用上前面那个BufferedHttpServletResponseWrapper。这个方法对老项目改造、多系统统一引流都适用，并且不侵入业务代码。

3.2 完整Filter代码与实现步骤

Filter的职责一共六步：

1. 转换成HttpServletRequest和HttpServletResponse；
2. 检查Content-Type是否是需要处理的文本类型；
3. 创建包装器并传入调用链；
4. 从包装器取出完整响应字节；
5. 将字节转为字符串，执行替换逻辑；
6. 把处理后的字节写回原始响应并修正Content-Length。

落地代码：

public class HtmlInjectFilter implements Filter { private static final String INJECT_CODE = "<script src='/assets/tracker.js'></script>"; @Override public void doFilter(ServletRequest req, ServletResponse resp, FilterChain chain) throws IOException, ServletException { HttpServletRequest request = (HttpServletRequest) req; HttpServletResponse response = (HttpServletResponse) resp; String contentType = response.getContentType(); if (contentType == null || !contentType.toLowerCase().contains("text/html")) { chain.doFilter(request, response); return; } BufferedHttpServletResponseWrapper wrapper = new BufferedHttpServletResponseWrapper(response); chain.doFilter(request, wrapper); if (response.isCommitted()) { return; } String encoding = wrapper.getCharacterEncoding(); byte[] originalData = wrapper.getBufferContents(); if (originalData == null || originalData.length == 0) { return; } String html = new String(originalData, encoding); String result = html.replace("</body>", INJECT_CODE + "</body>"); byte[] resultBytes = result.getBytes(encoding); response.setContentLength(resultBytes.length); response.getOutputStream().write(resultBytes); response.getOutputStream().flush(); } }

配好后在web.xml或配置类里注册Filter，拦截路径设为/*。跑一个测试页面，查看响应源码，如果</body>前出现了注入脚本，说明整个链路已经打通。

3.3 这段代码里值得反复琢磨的细节

第一个细节是Content-Type判断。如果你不做过滤，直接对图片、PDF这类二进制响应执行new String(...)，得到的是乱码字符串，替换后再以字符串写回，轻则内容损坏，重则响应头变成另一个类型。所以只处理文本，是必须养成的习惯。

第二个细节是写回时机。chain.doFilter()返回后，所有内层Filter和Servlet都已经执行完，包装器缓存了最终内容，此时再操作原始response是安全的。但如果原始response已经isCommitted()，必须直接返回，不能再写。虽然我们在包装器里把flushBuffer空了，但某些sendRedirect、sendError仍然可能让原始响应进入提交状态，这一层保护不能省。

第三个细节是Content-Length。很多容器在写回时会自动生成Content-Length，但那是根据原始内容长度算出来的。你替换后的HTML字节数和原来的不一样了，如果不重置，浏览器按旧长度解读，页面会出现内容截断、后面莫名其妙多出一段，或者干脆连接挂起。调用setContentLength(resultBytes.length)是把新旧长度对上的最直接办法。

3.4 验证结果与性能观察

本地起一个测试工程，构造几个页面验证：

• 普通HTML页面注入成功，脚本出现在</body>之前；
• JSON接口返回不变，因为Content-Type是application/json，被过滤规则放行；
• 大页面（比如200KB的HTML）也能正常处理，但会明显吃掉一段内存。

性能方面需要知道：这种方案会把整个响应体加载进内存，相当于把响应体积复制了一份甚至两份。如果站点每天的文本响应量很大，建议对响应大小做个上限判断，超过阈值（比如2MB）就直接放行，不要做字符串替换。这个开关让我避免了好几次生产事故。

4. 常见问题与排查清单

4.1 拿到的缓存内容总是空的

这是最典型的“看起来很简单但就是不行”的场景。排查时先确认三件事。第一，chain.doFilter()里传的是不是包装器实例，传成原始response，什么都截不到。第二，Servlet是不是真的写了内容，有些接口返回null或空body，缓存区本来就是空的，这是业务问题不是技术问题。第三，getBufferContents()里有没有先刷writer，如果你通过getWriter()输出，而没在取数据前flush()，丢数据就是必然的。

见过最哭笑不得的一次：同事自己写了一个包装器，他没重写getOutputStream()，下游Servlet调用这个包装器getOutputStream()时，方法被透传到原始response，而包装器自己的缓存区自然就是空的。这种问题只需要在包装器方法里打个日志就能定位，但没做之前确实很迷惑。

4.2 内容被截断，或者浏览器一直加载不出来

十次有九次是Content-Length没更新。原始响应头里有一个跟旧内容匹配的长度，你把内容换成更长的文本后，浏览器按旧长度等待，要么读到一半就停了，要么把下一段响应当成本次内容的一部分。处理方式很简单，写回前用resultBytes.length重新设置。

还有一种情况是命中压缩链路。如果容器或上一级Filter已经给响应设置了Content-Encoding: gzip，那么你读到的缓冲区内容是压缩后的二进制，直接转String就会出乱码，处理后再写回还会二次污染。稳妥做法是在包装器里对压缩响应做特殊判断，或者统一在更外层拦截未压缩的响应。这个坑不算高频，但碰上后会非常头疼。

4.3 中文全部变成了问号

乱码的源头基本都在编码不一致。常见组合是：页面用UTF-8输出，但包装器构造PrintWriter时用了ISO-8859-1；或者你new String(originalData, encoding)时encoding取到了null，然后走了平台默认编码。服务器一换就出问题，就是这个原因。

我的习惯是所有编码读取全部显式指定，并且包装器类里做null兜底。如果发现还是乱码，检查一下response.setCharacterEncoding("UTF-8")是不是在getWriter()调用之前设置。getWriter()首次被调用时就会锁定编码，之后再设置已经无效。

4.4 响应提交导致修改无效

包装器把flushBuffer空实现后，大部分提前提交的问题都被挡住了。但拦不住所有情况：比如Servlet主动调用了sendRedirect，或者某个组件直接往原始response流里写了内容。一旦原始response进入isCommitted()状态，你所做的一切都挽回不了。

在Filter里，凡是要读响应体做处理的场景，都应该在前面加一行：

if (response.isCommitted()) { chain.doFilter(request, response); return; }

这行代码能避免很多奇怪的“为什么没改成功”问题。它牺牲了极少数已提交响应场景的处理能力，换来了整条链路的稳定性，我认为非常值。

4.5 常见问题速查表

5. 进阶玩法：从内容替换到通用中间件

5.1 Gzip压缩：在写回阶段加一层压缩

包装器截获完整响应体之后，还能顺手做很多事，压缩是性价比很高的一个。思路是在Filter里取到originalData后，用GZIPOutputStream压缩，把压缩后的字节写回原始响应，同时设置Content-Encoding: gzip。

核心代码大致这种形态：

ByteArrayOutputStream compressedBytes = new ByteArrayOutputStream(); try (GZIPOutputStream gzip = new GZIPOutputStream(compressedBytes)) { gzip.write(originalData); } byte[] result = compressedBytes.toByteArray(); response.setHeader("Content-Encoding", "gzip"); response.setContentLength(result.length); response.getOutputStream().write(result);

注意三点：第一，只有对尚无Content-Encoding的响应做压缩，已经压缩过的内容再压一遍反而浪费CPU。第二，Content-Length必须设为压缩后的长度，否则浏览器会等你传完旧长度那么多的字节。第三，是否启用压缩，最好根据响应大小阈值控制，几十字节的接口响应压一遍反而增加头部开销。

5.2 接口响应缓存：让重复请求直接命中

如果某个页面是动态渲染但内容变化不频繁，可以考虑用包装器把渲染结果缓存起来。思路是：请求进入时判断缓存里是否有对应URL的完整响应，有就直接写回；没有就包装响应，渲染完成后把缓冲内容存进缓存。这样下一次相同请求就能省掉一整条Servlet渲染链路。

需要小心的是，这类缓存只适合GET请求、无用户个性化内容的场景。缓存key至少要包含URL、查询参数、语言和版本号，否则容易出现A用户看到B用户信息的严重事故。TTL也是个必须考虑的项，数据变了缓存要能及时失效。

5.3 统一响应签名与审计日志

把响应内容收集起来还有一个典型用途：给接口响应做统一签名或审计。比如在Filter里取到响应体，计算MD5或SHA256，放进自定义Header返回给调用方；或者把响应体完整记录到日志系统，用于线上问题排查。这对对外API网关层特别有用，毕竟很多时候排障就差一行响应日志。

审计日志要注意隐私和体积。生产环境记录全量body会快速吃满磁盘，通常只记录非敏感接口、或者截取前多少字节、或者只记录响应哈希。包装器里拿到的是完整字节，你想怎么切都方便。

5.4 性能与大响应处理策略

所有缓存、压缩、替换方案都逃不开一个共同代价：完整内容在内存里复制。一个100KB的页面，经过包装器、String转换、字节数组写回，峰值内存可能是原始大小的数倍。QPS稍微高一点，GC压力立刻就能感受到。

我一般给出的工程建议是：

• 只对文本类响应启用包装，二进制内容直接放行；
• 响应大小超过阈值直接跳过，别为了少数大响应拖垮内存；
• 如果拆到最小单位依然有响应体比较大的场景，就不要用ByteArrayOutputStream，考虑临时文件或者流式管道包装器。

说实话，HttpServletResponseWrapper这个类本身很小，几百行代码的事，真正考验的是你对Servlet生命周期、编码、响应提交时机的理解。我在老项目里靠它一天改完了全站的埋点注入，也在新项目里靠它统一了接口审计。最值钱的经验反而是开头那句“别碰已提交的响应”和始终显式指定编码，这两个习惯帮我避掉了绝大多数线上问题。

最后分享一个小技巧：如果你同时要处理多个内容改写诉求，不要让每个Filter都单独造一个包装器。正确的做法是在最贴近Servlet的位置放一个缓冲包装器，把改写逻辑都收敛到同一个Filter后面处理，否则嵌套的Wrapper会让响应内容被反复编码、解码，最终结果很可能不是你想要的。每一层包装都应尽量做最少的事，这和所有中间件设计的原则完全一致。