ResponseEntity<byte[]>下载文件时如何正确设置响应头？

Question

在使用 `ResponseEntity` 实现文件下载时，如何正确设置响应头（如 Content-Type、Content-Disposition、Content-Length）以确保浏览器正确识别并下载文件？

Answer 1

一、使用 ResponseEntity 实现文件下载的基本原理

在 Spring Boot 应用中，使用 ResponseEntity 是一种常见的实现文件下载的方式。它允许将文件内容作为字节数组直接写入 HTTP 响应体中。

要确保浏览器正确识别并触发文件下载，关键在于设置正确的响应头（Response Headers），主要包括：

• Content-Type
• Content-Disposition
• Content-Length

这些响应头的作用分别如下：

Header Name	Description
Content-Type	告诉浏览器返回的数据类型，如 application/pdf、application/octet-stream 等
Content-Disposition	控制浏览器是显示还是下载文件，常用值为 attachment; filename="xxx"
Content-Length	指定响应体的字节长度，有助于浏览器显示下载进度

二、如何正确设置 ResponseEntity 的响应头

在 Spring Boot 控制器中，可以通过 HttpHeaders 对象来设置响应头。以下是一个典型的实现示例：

@GetMapping("/download")
public ResponseEntity downloadFile() throws IOException {
    String filePath = "path/to/your/file.pdf";
    byte[] fileContent = Files.readAllBytes(Paths.get(filePath));

    HttpHeaders headers = new HttpHeaders();
    headers.setContentType(MediaType.APPLICATION_OCTET_STREAM);
    headers.setContentDispositionFormData("attachment", "file.pdf");
    headers.setContentLength(fileContent.length);

    return new ResponseEntity<>(fileContent, headers, HttpStatus.OK);
}
    

在这个示例中：

• MediaType.APPLICATION_OCTET_STREAM 表示一个通用的二进制流，适用于任意类型的文件下载。
• setContentDispositionFormData 设置了下载时的文件名。
• setContentLength 告诉浏览器响应体的大小。

三、Content-Type 的选择与 MIME 类型的重要性

选择正确的 Content-Type 是非常关键的一步。不同的文件类型应使用对应的 MIME 类型。例如：

• PDF 文件：application/pdf
• Word 文档：application/vnd.openxmlformats-officedocument.wordprocessingml.document
• Excel 文件：application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
• 普通二进制文件：application/octet-stream

使用通用的 application/octet-stream 虽然可以保证下载，但不利于浏览器识别文件类型。推荐根据实际文件类型动态设置 MIME 类型：

String mimeType = Files.probeContentType(Paths.get(filePath));
if (mimeType == null) {
    mimeType = "application/octet-stream";
}
headers.setContentType(MediaType.parseMediaType(mimeType));
    

四、Content-Disposition 的作用与使用方式

Content-Disposition 告诉浏览器这是一个附件（attachment），应该下载而不是直接在浏览器中显示。其格式通常为：

Content-Disposition: attachment; filename="example.pdf"
    

在 Spring 中，可以通过以下方式设置：

headers.setContentDispositionFormData("attachment", "example.pdf");
    

注意：如果文件名包含中文或特殊字符，建议使用 URL 编码处理，防止浏览器解析失败。

五、Content-Length 的优化与性能考虑

Content-Length 是可选的，但强烈建议设置。它有助于浏览器显示下载进度条，并提高用户体验。

在设置时，需要注意：

• 确保字节数组长度正确。
• 大文件下载时，若一次性读取整个文件到内存可能造成性能问题，应考虑使用流式传输（如 ResponseEntity.BodyBuilder 和 InputStreamResource）。

流式传输示例代码如下：

@GetMapping("/stream-download")
public ResponseEntity streamDownloadFile() throws IOException {
    Path path = Paths.get("path/to/your/file.pdf");
    Resource resource = new UrlResource(path.toUri());

    return ResponseEntity.ok()
        .contentType(MediaType.APPLICATION_OCTET_STREAM)
        .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + resource.getFilename() + "\"")
        .body(resource);
}
    

六、完整流程图分析

以下是使用 ResponseEntity 实现文件下载的完整流程图：

graph TD
            A[开始] --> B[读取文件为byte[]]
            B --> C{文件存在?}
            C -->|是| D[探测MIME类型]
            D --> E[设置Content-Type]
            E --> F[设置Content-Disposition]
            F --> G[设置Content-Length]
            G --> H[构建ResponseEntity]
            H --> I[返回给客户端]
            C -->|否| J[抛出异常或返回404]