springboot项目前后端通用下载方法、问题和解决方案

一、前言

下面是前后端下载通用方案，包括完整的下载方法（前端 + 后端）、可能遇到的问题、及解决方案，适用于Word、Excel、PDF 等常见导出文件的下载场景。

二、后端通用方法

1、工具类

import org.springframework.core.io.ClassPathResource;
import org.springframework.core.io.FileSystemResource;
import org.springframework.core.io.Resource;
import org.springframework.http.*;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class FileDownloadUtil {

    private static final String FILE_EXTENSION = ".xlsx";

    /**
     * 从 classpath 下载模板文件
     */
    public static ResponseEntity<?> downloadFromClasspath(String dirPath, String fileName) {
        // 路径校验
        if (!isValidFileName(fileName)) {
            return ResponseEntity
                    .badRequest()
                    .body(BaseResponse.error(HttpStatus.BAD_REQUEST.value(), "非法文件名"));
        }

        String fullFileName = fileName + FILE_EXTENSION;
        Resource resource = new ClassPathResource(dirPath + fullFileName);
        return buildResponseEntity(resource, fullFileName);
    }

    /**
     * 从文件系统下载文件
     */
    public static ResponseEntity<?> downloadFromFileSystem(String fullFilePath, String downloadFileNameWithoutExtension) {
        if (!isValidFileName(downloadFileNameWithoutExtension)) {
            return ResponseEntity
                    .badRequest()
                    .body(BaseResponse.error(HttpStatus.BAD_REQUEST.value(), "非法文件名"));
        }

        String fullFileName = downloadFileNameWithoutExtension + FILE_EXTENSION;
        Resource resource = new FileSystemResource(fullFilePath);
        return buildResponseEntity(resource, fullFileName);
    }

    /**
     * 封装 ResponseEntity 下载响应
     */
    private static ResponseEntity<?> buildResponseEntity(Resource resource, String fileName) {
        if (!resource.exists()) {
            return ResponseEntity
                    .status(HttpStatus.NOT_FOUND)
                    .body(BaseResponse.error(HttpStatus.NOT_FOUND.value(), "文件不存在"));
        }

        try {
            String encodedFileName = URLEncoder.encode(fileName, StandardCharsets.UTF_8.name());
            String contentDisposition = "attachment; filename=\"" +
                    new String(fileName.getBytes(StandardCharsets.UTF_8), StandardCharsets.ISO_8859_1) +
                    "\"; filename*=UTF-8''" + encodedFileName;

            return ResponseEntity.ok()
                    .contentType(MediaType.APPLICATION_OCTET_STREAM)
                    .header(HttpHeaders.CONTENT_DISPOSITION, contentDisposition)
                    .body(resource);

        } catch (UnsupportedEncodingException e) {
            return ResponseEntity
                    .status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body(BaseResponse.error(HttpStatus.INTERNAL_SERVER_ERROR.value(), "文件下载失败"));
        }
    }

    /**
     * 校验文件名合法性
     */
    private static boolean isValidFileName(String fileName) {
        return fileName != null &&
                !fileName.isEmpty() &&
                !fileName.contains("..") &&
                !fileName.contains("/") &&
                !fileName.contains("\\");
    }
}

如需支持不同扩展名（如 .xlsx, .docx, .csv 等），可以将 FILE_EXTENSION 提供为方法参数即可

2、接口，建议get请求

文件目录建议放在springboot项目的resources目录下

@GetMapping("/download-template")
public ResponseEntity<?> downloadTemplate(@RequestParam String fileName) {
    return FileDownloadUtil.downloadFromClasspath("files/", fileName);
}

• downloadFromClasspath(…): 用于从 classpath 中的某个目录（比如 /resources/files/）下载。
• downloadFromFileSystem(…): 如果你未来切换为磁盘路径文件下载，也可以使用。
• isValidFileName(…): 用于防止路径穿越攻击。
• 返回值 ResponseEntity<?> 支持直接被 Spring MVC 用作响应体返回，并兼容你的 BaseResponse 结构。

在 Spring Boot 项目中，后端提供下载模板接口时，选择 POST 或 GET 需综合考虑以下因素：

• 使用 POST 的情况

传输数据量大：如果下载模板需要附带参数（如筛选条件、动态数据），POST 无 URL 长度限制，适合传输较大数据。
安全性要求高：POST 请求的参数不会直接暴露在 URL 中，适合敏感数据（如权限校验信息）。
幂等性要求低：下载操作通常是非幂等的（多次请求可能生成不同内容），符合 POST 语义。

• 使用 GET 的情况

简单无参数：若模板是静态文件或仅需少量参数（如模板类型），GET 更简洁直观。
缓存友好：浏览器或网关可能缓存 GET 请求结果，提升重复下载效率。
符合 REST 语义：GET 通常用于获取资源，适合无副作用的下载操作。

• 推荐实践

优先 GET：若下载无需复杂参数且模板为静态资源，GET 更符合习惯。
选择 POST：若需动态生成模板、传递敏感数据或参数较多，使用 POST。
混合方案：通过 GET 获取预签名 URL（如 AWS S3），再由前端直接下载，分散服务器压力。

三、前端通用方法

以 Vue / Axios 为例

// 下载 Word/Excel/PDF 等二进制文件
export function downloadFileByPost(url: string, data: any, fileName: string) {
  axios.post(url, data, {
    responseType: 'blob',
  }).then((res) => {
    const blob = new Blob([res.data], { type: res.headers['content-type'] || 'application/octet-stream' });

    const link = document.createElement('a');
    const objectUrl = URL.createObjectURL(blob);
    link.href = objectUrl;
    link.download = fileName;
    link.click();
    URL.revokeObjectURL(objectUrl);
  }).catch((error) => {
    console.error('Download failed', error);
  });
}

四、常见问题与解决方案

我遇到过的问题就是：前端下载后文件里面是[object Object]，没有其他内容
最终原因是前端协议是http的，导致浏览器拒绝blob文件。

五、前后端协议一致性建议

六、总结