Spring控制器大文件写入OutputStream时的错误处理咨询

这个问题我之前处理过不少次，核心矛盾在于一旦你开始往原始的HttpServletResponse输出流写内容，响应头可能已经被发送给客户端了，这时候再想转发、重定向或者切换响应内容就会受限——容器会认为响应已经“提交”，不允许再修改响应状态或头部；直接写错误HTML也会被浏览器当成文件的一部分，导致文件损坏而不是展示错误页面。

下面是几种可行的解决思路，按优先级排序：

1. 用响应缓存包装器延迟响应提交（最优方案） #

Spring提供了ContentCachingResponseWrapper（以及针对大文件的DiskContentCachingResponseWrapper，Spring 5.2+支持），它会先把你写入的内容缓存到内存/磁盘，直到你主动触发copyBodyToResponse()才会把缓存内容发送给客户端。这样只要整个文件写入过程没出错，才会提交响应；中途出错的话，只要响应还没提交，就能重置缓存并输出错误内容。

代码示例： #

@GetMapping("/download")
public void downloadLargeFile(HttpServletResponse response) throws IOException {
    ContentCachingResponseWrapper cachedResponse = new ContentCachingResponseWrapper(response);
    InputStream inputStream = null;
    OutputStream out = null;

    try {
        // 设置响应头（比如文件名、Content-Type）
        response.setHeader("Content-Disposition", "attachment; filename=large-file.zip");
        response.setContentType("application/zip");

        inputStream = new FileInputStream(new File("/path/to/large-file.zip"));
        out = cachedResponse.getOutputStream();

        byte[] buffer = new byte[4096];
        int bytesRead;
        while ((bytesRead = inputStream.read(buffer)) != -1) {
            // 模拟中途出错的情况，比如读取到某位置抛出异常
            if (bytesRead > 3000) {
                throw new IOException("模拟文件读取出错");
            }
            out.write(buffer, 0, bytesRead);
        }

        // 写入成功，将缓存内容刷到真实响应
        cachedResponse.copyBodyToResponse();
    } catch (Exception e) {
        // 处理错误
        if (!cachedResponse.isCommitted()) {
            // 响应还没提交，重置缓存并输出错误页面
            cachedResponse.reset();
            // 重置响应头和状态码
            response.setContentType("text/html;charset=UTF-8");
            response.setStatus(HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
            
            PrintWriter writer = cachedResponse.getWriter();
            writer.write("<html><head><meta charset='UTF-8'></head><body>");
            writer.write("<h2>文件下载失败</h2>");
            writer.write("<p>错误原因：" + e.getMessage() + "</p>");
            writer.write("</body></html>");
            writer.flush();
            
            // 将错误内容刷到真实响应
            cachedResponse.copyBodyToResponse();
        } else {
            // 极端情况：响应已经提交（比如缓存满了自动刷出），只能记录日志，前端兜底
            log.error("文件下载中途出错，响应已提交，客户端可能收到损坏文件", e);
        }
    } finally {
        // 关闭流
        if (inputStream != null) inputStream.close();
        if (out != null) out.close();
    }
}

针对超大文件的优化： #

如果文件大到内存缓存撑不住，改用DiskContentCachingResponseWrapper，它会把缓存写到临时文件，避免OOM：

DiskContentCachingResponseWrapper cachedResponse = new DiskContentCachingResponseWrapper(response);
// 其他逻辑和上面一致，最后同样调用copyBodyToResponse()

2. 提前检查文件可用性（前置校验） #

在开始写入输出流之前，先做一些前置检查：比如文件是否存在、是否可读、权限是否足够、文件大小是否合法等。把能提前发现的错误在响应提交之前处理，直接返回错误页面，避免中途出错的情况。

比如：

File file = new File("/path/to/large-file.zip");
if (!file.exists() || !file.canRead()) {
    response.sendError(HttpServletResponse.SC_NOT_FOUND, "文件不存在或无法读取");
    return;
}
// 再开始后续的写入逻辑

3. 前端兜底校验 #

如果遇到极端情况（比如响应已经提交后才出错），后端没法再修改响应，这时候可以让前端配合做校验：

• 后端在响应头里设置Content-Length（文件的真实大小）
• 前端下载完成后，对比实际下载的文件大小和响应头里的Content-Length，如果不一致就提示用户“下载出错，请重新尝试”

比如前端用JavaScript下载时：

fetch('/download')
  .then(res => {
    const contentLength = parseInt(res.headers.get('Content-Length'));
    return res.blob().then(blob => {
      if (blob.size !== contentLength) {
        alert('文件下载不完整，请重新尝试');
        return;
      }
      // 正常处理下载的文件
    });
  });

为什么你之前的方法不行？ #

• 转发/重定向：一旦你往输出流写了内容，响应头已经发送，容器会标记响应为“已提交”，这时候转发/重定向会抛出IllegalStateException（提示OutputStream已获取）。
• 直接写错误HTML：浏览器已经在接收文件流（比如下载的二进制文件），会把错误HTML当成文件的一部分，导致文件损坏，而不会渲染成错误页面。

内容的提问来源于stack exchange，提问作者Cod