Spring文件下载遇连接重置的异常处理与响应终止方案咨询

这个问题我之前在处理文件下载接口的时候也碰到过，简直是头疼——连接重置后不仅日志里一堆恶心的嵌套异常，用户还会拿到不完整的文件却显示下载成功，体验太差了。让我给你几个可行的解决方案：

一、手动控制流复制与响应（最优方案） #

核心问题在于：当你返回InputStreamResource时，Spring会自动帮你复制流到响应输出中，但这个过程中如果抛出IO异常，Spring的默认错误处理器会尝试渲染/error页面，可此时响应已经开始写入（已经发送了200状态码和部分文件内容），就会触发getOutputStream() has already been called的异常。

我们可以绕过Spring的自动处理，直接用HttpServletResponse手动控制整个流的复制过程，这样就能在异常发生时直接终止响应、设置错误状态码，避免错误处理器介入。

代码示例：

@GetMapping("/download")
public void downloadFile(String path, HttpServletResponse response) throws IOException {
    FileContentInformation fileContent = getInputContentFromSomewhere();
    
    // 设置响应头（Content-Type、Content-Disposition、Content-Length等）
    response.setContentType(fileContent.getContentType());
    response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + fileContent.getFileName() + "\"");
    response.setContentLengthLong(fileContent.getContentLength());
    response.setStatus(HttpStatus.OK.value());

    // 手动复制流，捕获IO异常
    try (InputStream inputStream = fileContent.getInputStream();
         OutputStream outputStream = response.getOutputStream()) {
        StreamUtils.copy(inputStream, outputStream);
        outputStream.flush();
    } catch (IOException e) {
        // 判断是否是连接重置类异常
        if (e instanceof SocketException || (e.getMessage() != null && e.getMessage().contains("Connection reset"))) {
            // 尝试设置错误状态码（如果响应还未完全提交）
            if (!response.isCommitted()) {
                response.setStatus(HttpStatus.BAD_GATEWAY.value());
            }
            // 关闭输出流，强制终止连接，避免客户端卡顿
            response.getOutputStream().close();
        }
        // 记录清晰的错误日志，不用再看嵌套异常
        log.error("Failed to download file from external source (path: {})", path, e);
    }
}

这种方式的优势在于：

• 完全掌控响应的生命周期，不会触发Spring的默认错误处理逻辑
• 可以在异常发生时直接关闭流，避免客户端出现卡顿、吞吐量降为0的情况
• 日志更清晰，没有多余的嵌套异常干扰

二、自定义全局异常处理器 #

如果你更倾向于保留ResponseEntity的写法，可以自定义一个全局异常处理器，专门捕获文件下载过程中的IO异常，处理响应的收尾工作。

代码示例：

@ControllerAdvice
public class DownloadExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(DownloadExceptionHandler.class);

    @ExceptionHandler({IOException.class, SocketException.class})
    public void handleDownloadExceptions(Exception e, HttpServletResponse response) {
        if (response.isCommitted()) {
            // 响应已经提交，无法修改状态码，只能关闭流并记录日志
            log.error("Response already committed, cannot update status code. Error details:", e);
            try {
                response.getOutputStream().close();
            } catch (IOException ex) {
                log.error("Failed to close output stream after error", ex);
            }
            return;
        }
        // 设置合适的错误状态码，比如502（外部服务不可用）
        response.setStatus(HttpStatus.BAD_GATEWAY.value());
        try {
            // 给客户端返回简单的错误提示
            response.getWriter().write("Download failed: connection to external source was reset");
        } catch (IOException ex) {
            log.error("Failed to write error message to response", ex);
        }
    }
}

注意：如果异常发生时响应已经提交（比如已经发送了部分文件内容），此时无法修改状态码，但关闭流可以终止客户端的等待，避免卡顿。

三、使用StreamingResponseBody异步处理流 #

Spring的StreamingResponseBody可以让你在异步线程中处理流的复制，同样可以在异常发生时控制响应：

@GetMapping("/download")
public ResponseEntity<StreamingResponseBody> downloadFile(String path) {
    FileContentInformation fileContent = getInputContentFromSomewhere();
    HttpHeaders responseHeaders = createHttpHeaders(fileContent);

    StreamingResponseBody responseBody = outputStream -> {
        try (InputStream inputStream = fileContent.getInputStream()) {
            StreamUtils.copy(inputStream, outputStream);
        } catch (IOException e) {
            // 通过RequestContextHolder获取当前响应
            HttpServletResponse response = ((ServletRequestAttributes) RequestContextHolder.getRequestAttributes()).getResponse();
            if (response != null && !response.isCommitted()) {
                response.setStatus(HttpStatus.BAD_GATEWAY.value());
            }
            // 关闭流并记录日志
            outputStream.close();
            log.error("Download failed for path: {}", path, e);
        }
    };

    return new ResponseEntity<>(responseBody, responseHeaders, HttpStatus.OK);
}

这种方式适合需要异步处理的场景，但本质上和第一种方案类似，都是手动处理流的异常。

额外优化建议 #

• 可以在前端增加校验：下载完成后对比文件实际大小和响应头中的Content-Length，如果不一致则提示用户下载失败
• 针对外部源的连接问题，可以增加重试机制（比如使用RetryTemplate），减少因临时网络波动导致的下载失败

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