如何在Spring MVC中实现大文件的octet-stream下载端点？

问题背景 #

我需要实现Spring MVC的大文件下载端点，但现有的两种方案都存在缺陷：

方案1：直接操作HttpServletResponse输出流 #

@PostMapping("/download")
void downloadFile(
     @PathVariable("path") String path,
     HttpServletResponse response
) throws Exception {
    try (var output = response.getOutputStream()) {
        response.setContentType(MediaType.APPLICATION_OCTET_STREAM_VALUE);
        service.readFilePart(path, output);
    }
}

缺陷：当service.readFilePart抛出异常时，端点仍返回HTTP 200状态码，无法返回带错误状态的JSON响应；同时直接操作HttpServletResponse破坏了Spring MVC的抽象层级。

方案2：加载全量文件到内存后返回ResponseEntity #

try (var output = new ByteArrayOutputStream()) {
    service.readFilePart(path, output);
    return ResponseEntity.ok()
                  .contentType(MediaType.APPLICATION_OCTET_STREAM)
                  .body(output.toByteArray());
}

缺陷：需要将整个文件加载到内存，无法处理大文件场景。

我需要一种方案，既能处理大文件（每次仅加载不超过1MB的块到内存），又能利用Spring MVC的标准特性（如全局异常处理器），同时避免直接操作HttpServletResponse。

最优解决方案：使用StreamingResponseBody #

StreamingResponseBody是Spring MVC提供的高层抽象，支持异步流式输出，完全满足大文件场景需求，同时兼容Spring的异常处理机制。

核心实现代码 #

import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody;

@PostMapping("/download")
public ResponseEntity<StreamingResponseBody> downloadFile(@PathVariable("path") String path) {
    // 提前校验文件合法性（如存在性、权限），避免流式输出启动后抛出异常
    if (!service.isFileExist(path)) {
        throw new FileNotFoundException("指定文件不存在：" + path);
    }

    // 定义流式响应体
    StreamingResponseBody responseBody = outputStream -> {
        // 此处service.readFilePart需实现分块读取文件并写入输出流（每次读取≤1MB块）
        service.readFilePart(path, outputStream);
    };

    return ResponseEntity.ok()
            .contentType(MediaType.APPLICATION_OCTET_STREAM)
            // 可选：添加下载文件名头
            .header("Content-Disposition", "attachment; filename=\"" + service.getFileName(path) + "\"")
            .body(responseBody);
}

关键优势 #

1. 流式输出，低内存占用：StreamingResponseBody的writeTo方法由Spring MVC框架调用，文件数据会分块写入响应输出流，不会一次性加载全量文件到内存，适配大文件场景。
2. 兼容Spring异常处理：无论是提前校验阶段抛出的异常，还是流式输出过程中service.readFilePart抛出的异常，都会被Spring的全局异常处理器捕获，返回正确的HTTP错误状态码和JSON响应。
3. 保持Spring MVC抽象层级：无需直接操作HttpServletResponse，完全基于Spring高层API实现，符合框架设计规范。

配套：全局异常处理器示例 #

为了统一处理异常并返回JSON格式错误响应，可定义全局异常处理器：

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import java.io.FileNotFoundException;
import java.io.IOException;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(FileNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleFileNotFound(FileNotFoundException ex) {
        ErrorResponse error = new ErrorResponse(HttpStatus.NOT_FOUND.value(), ex.getMessage());
        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
    }

    @ExceptionHandler(IOException.class)
    public ResponseEntity<ErrorResponse> handleIoException(IOException ex) {
        ErrorResponse error = new ErrorResponse(HttpStatus.INTERNAL_SERVER_ERROR.value(), "文件读取失败，请稍后重试");
        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
    }

    // 自定义错误响应实体
    public static class ErrorResponse {
        private int status;
        private String message;

        public ErrorResponse(int status, String message) {
            this.status = status;
            this.message = message;
        }

        // Getter和Setter方法
        public int getStatus() {
            return status;
        }

        public void setStatus(int status) {
            this.status = status;
        }

        public String getMessage() {
            return message;
        }

        public void setMessage(String message) {
            this.message = message;
        }
    }
}

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