快捷導(dǎo)航

SpringBoot中文件下載與JSON響應(yīng)沖突的深度解析與解決方案

更新時間：2026年03月27日 09:13:19 作者：繳鴻劍Jackson

在Spring Boot開發(fā)中,我們經(jīng)常遇到需要同時處理文件下載和JSON響應(yīng)的場景,很多開發(fā)者會遇到這樣一個困惑：明明已經(jīng)正確配置了文件下載,但瀏覽器要么無法下載文件,要么返回的JSON數(shù)據(jù)混亂,本文將深入分析這個問題的本質(zhì),并提供多種優(yōu)雅的解決方案

引言

在Spring Boot開發(fā)中，我們經(jīng)常遇到需要同時處理文件下載和JSON響應(yīng)的場景。很多開發(fā)者會遇到這樣一個困惑：明明已經(jīng)正確配置了文件下載，但瀏覽器要么無法下載文件，要么返回的JSON數(shù)據(jù)混亂。本文將深入分析這個問題的本質(zhì)，并提供多種優(yōu)雅的解決方案。

一.先看一段典型的錯誤代碼

@RestController
public class FileController {
    
    @GetMapping("/download/pdf")
    public R downCustStmt(CustStmtReq req, HttpServletResponse response) {
        // 設(shè)置PDF響應(yīng)頭
        response.setContentType("application/pdf");
        response.setHeader("Content-Disposition", "attachment; filename=simple.pdf");
        
        try {
            Document document = new Document();
            PdfWriter.getInstance(document, response.getOutputStream());
            document.open();
            document.add(new Paragraph("Hello PDF"));
            document.close();
            
            // 問題所在：PDF已經(jīng)寫入，卻還要返回R對象
            return R.ok("接口正在開發(fā)中，敬請期待~");
            
        } catch (Exception e) {
            e.printStackTrace();
            return R.error("PDF生成失敗");
        }
    }
}

這段代碼看似合理，但實際上存在嚴重問題：一個HTTP請求只能返回一種類型的響應(yīng)。

而這段代碼中，返回了兩種類型的響應(yīng)：①文件流 ②響應(yīng)體R

正確的做法應(yīng)該是二選一才對。

二.問題分析

1. HTTP響應(yīng)的單一性原理

HTTP協(xié)議規(guī)定，一個請求-響應(yīng)周期中，服務(wù)器只能返回一種類型的數(shù)據(jù)。當我們在代碼中：

先通過 response.getOutputStream() 寫入PDF數(shù)據(jù)
再通過方法返回值 R.ok() 返回JSON數(shù)據(jù)

這就導(dǎo)致響應(yīng)流被雙重寫入，造成數(shù)據(jù)混亂。

2. Spring MVC的處理機制

Spring MVC處理控制器方法返回值的流程：

執(zhí)行控制器方法
根據(jù)返回值類型選擇相應(yīng)的 HandlerMethodReturnValueHandler
將返回值寫入響應(yīng)流

當我們在方法內(nèi)部已經(jīng)通過 response.getOutputStream() 寫入數(shù)據(jù)后，Spring MVC后續(xù)的寫入操作就會導(dǎo)致異常。

3. 響應(yīng)流的互斥性

HttpServletResponse 提供了兩種輸出方式：

getOutputStream()：用于輸出二進制數(shù)據(jù)
getWriter()：用于輸出字符數(shù)據(jù)

這兩種方式互斥，一旦調(diào)用就不能切換。同樣，它們與方法的返回值也是互斥的。

三.解決方案：響應(yīng)類型必須二選一

如下圖，我們只返回文件流，就不弄響應(yīng)體R了。

@GetMapping("/download/pdf")
public void downloadPdf(CustStmtReq req, HttpServletResponse response) {
    try {
        // 1. 設(shè)置響應(yīng)頭
        response.setContentType("application/pdf");
        response.setHeader("Content-Disposition", 
            "attachment; filename=" + URLEncoder.encode("對賬單.pdf", "UTF-8"));
        
        // 2. 生成PDF
        Document document = new Document(PageSize.A4);
        PdfWriter.getInstance(document, response.getOutputStream());
        document.open();
        
        // 添加PDF內(nèi)容
        document.add(new Paragraph("客戶對賬單"));
        document.add(new Paragraph("生成時間：" + LocalDateTime.now()));
        document.add(new Paragraph("請求參數(shù)：" + req.toString()));
        
        document.close();
        
    } catch (Exception e) {
        log.error("PDF生成失敗", e);
        throw new RuntimeException("PDF生成失敗", e);
    }
}