快捷導(dǎo)航

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

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

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

引言

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

一.先看一段典型的錯(cuò)誤代碼

@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();
            
            // 問(wèn)題所在：PDF已經(jīng)寫(xiě)入，卻還要返回R對(duì)象
            return R.ok("接口正在開(kāi)發(fā)中，敬請(qǐng)期待~");
            
        } catch (Exception e) {
            e.printStackTrace();
            return R.error("PDF生成失敗");
        }
    }
}

這段代碼看似合理，但實(shí)際上存在嚴(yán)重問(wèn)題：一個(gè)HTTP請(qǐng)求只能返回一種類(lèi)型的響應(yīng)。

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

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

二.問(wèn)題分析

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

HTTP協(xié)議規(guī)定，一個(gè)請(qǐng)求-響應(yīng)周期中，服務(wù)器只能返回一種類(lèi)型的數(shù)據(jù)。當(dāng)我們?cè)诖a中：

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

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

2. Spring MVC的處理機(jī)制

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

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

當(dāng)我們?cè)诜椒▋?nèi)部已經(jīng)通過(guò) response.getOutputStream() 寫(xiě)入數(shù)據(jù)后，Spring MVC后續(xù)的寫(xiě)入操作就會(huì)導(dǎo)致異常。

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

HttpServletResponse 提供了兩種輸出方式：

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

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

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

如下圖，我們只返回文件流，就不弄響應(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("對(duì)賬單.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("客戶(hù)對(duì)賬單"));
        document.add(new Paragraph("生成時(shí)間：" + LocalDateTime.now()));
        document.add(new Paragraph("請(qǐng)求參數(shù)：" + req.toString()));
        
        document.close();
        
    } catch (Exception e) {
        log.error("PDF生成失敗", e);
        throw new RuntimeException("PDF生成失敗", e);
    }
}