HttpServletResponse 中 Header 与 OutputStream 的正确使用顺序（避坑指南）

在日常的 Java Web 开发中，我们经常会遇到这样一个场景：

给前端返回文件下载、接口响应流、或者做网关透传时，需要同时操作 HttpServletResponse 的 header 和输出流。

很多人写着写着就会踩一个经典坑：

java 复制代码

OutputStream out = response.getOutputStream();
out.write(data);

response.addHeader("Content-Disposition", "attachment; filename=test.pdf"); // ❌ 不生效

结果就是：

文件名丢失
浏览器行为异常（直接打开而不是下载）
甚至直接抛异常

这篇文章就把这个问题彻底讲清楚。

一、核心结论（先记住这一句）

👉 必须先设置 Header，再写 OutputStream

换句话说：

text 复制代码

setStatus → setHeader → write body

一旦开始写 body，就不要再改 header。

二、问题的根本原因：Response "提交（commit）"机制

在 Servlet 规范中，HTTP 响应是有明确结构的：

text 复制代码

Status Line
Headers
空行
Body

而 HttpServletResponse 的行为是：

👉 一旦响应被"提交（commit）"，header 就会被锁定，无法再修改

什么会触发 commit？

以下操作都可能触发：

response.getOutputStream().write(...)
response.getWriter().write(...)
flush()
buffer 写满自动刷新

一旦发生 commit：

java 复制代码

response.addHeader(...) // ❌ 要么无效，要么抛异常

三、正确写法（标准模板）

java 复制代码

// 1️⃣ 设置状态码
response.setStatus(200);

// 2️⃣ 设置 header（必须在前）
response.setHeader("Content-Type", "application/pdf");
response.setHeader("Content-Disposition", "attachment; filename=test.pdf");

// 3️⃣ 写 body（最后一步）
try (OutputStream out = response.getOutputStream()) {
    out.write(data);
}

四、错误示例（最常见）

java 复制代码

OutputStream out = response.getOutputStream();

out.write(data); // ⚠️ 这里可能已经触发 commit

response.addHeader("Content-Disposition", "attachment; filename=test.pdf"); // ❌ 不生效

👉 表现：

header 没生效
下载文件名异常
浏览器行为异常

五、文件下载场景的正确姿势

这是最容易踩坑的地方。

java 复制代码

response.setContentType("application/octet-stream");
response.setHeader("Content-Disposition", "attachment; filename=test.zip");

try (InputStream in = fileInputStream;
     OutputStream out = response.getOutputStream()) {

    byte[] buffer = new byte[8192];
    int len;

    while ((len = in.read(buffer)) != -1) {
        out.write(buffer, 0, len);
    }
}

👉 关键点：

header 一定在写流之前
不要中途修改 header

六、网关/代理透传场景（高频）

如果你在做文件代理或 API 网关：

java 复制代码

// 1️⃣ 状态码
clientResp.setStatus(remoteResp.getRawStatusCode());

// 2️⃣ header 透传
remoteResp.getHeaders().forEach((key, values) -> {
    for (String value : values) {
        clientResp.addHeader(key, value);
    }
});

// 3️⃣ body 透传
try (InputStream in = remoteResp.getBody();
     OutputStream out = clientResp.getOutputStream()) {

    byte[] buffer = new byte[8192];
    int len;

    while ((len = in.read(buffer)) != -1) {
        out.write(buffer, 0, len);
    }
}

👉 顺序不能乱，否则：

下载失败
header 丢失
浏览器无法识别文件

七、一个容易误解的点

getOutputStream() 会不会立即 commit？

👉 不一定，但：

写数据时很可能触发 commit
buffer 满时也会触发

👉 实践建议：

把 getOutputStream() 当成"最后一步"来用

八、进阶：为什么设计成这样？

这是 HTTP 协议本身决定的：

header 必须在 body 之前发送
一旦 body 开始发送，就不能回头修改 header

Servlet 只是遵守这个规则。

九、实战建议（避免踩坑）

✔ 1. 永远先 header 后 body

形成习惯：

text 复制代码

setHeader → write

java 复制代码

while (...) {
    response.addHeader(...) // ❌ 错误
}

✔ 3. 封装统一工具类（推荐）

避免每个地方都写错顺序。

✔ 4. 日志/调试时注意 commit 时机

很多"header失效"问题，本质都是：

👉 已经写了 body

十、一句话总结

👉 Header 是"声明"，Body 是"内容"，声明必须在内容之前

如果你经常做：

文件下载
接口代理
网关透传

这个顺序问题几乎是必踩坑之一，建议直接记住这条规则：

"只要开始写流，就别再碰 header"

HttpServletResponse 中 Header 与 OutputStream 的正确使用顺序（避坑指南）