萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> JSP 程式設計

Servlet 實現檔案下載完整實戰:中文檔名、斷點續傳、瀏覽器相容性

核心需求

實現檔案下載功能,解決:中文檔名亂碼、瀏覽器直接開啟而非下載、大檔案記憶體溢出、斷點續傳支援、多瀏覽器 Content-Disposition 相容性。

完整下載 Servlet 實作

package com.example.servlet;

import jakarta.servlet.*;
import jakarta.servlet.http.*;
import jakarta.servlet.annotation.*;
import java.io.*;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Date;

@WebServlet("/download")
public class FileDownloadServlet extends HttpServlet {
    private static final int BUFFER_SIZE = 8192; // 8KB 緩衝區
    
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) 
            throws ServletException, IOException {
        
        String fileName = req.getParameter("fileName");   // 伺服器實際檔名
        String showName = req.getParameter("showName");   // 下載顯示檔名
        
        if (fileName == null || showName == null) {
            resp.sendError(HttpServletResponse.SC_BAD_REQUEST, "缺少參數");
            return;
        }
        
        // 安全檢查:防止路徑遍歷攻擊
        String baseDir = getServletContext().getRealPath("/WEB-INF/files/");
        File file = new File(baseDir, fileName).getCanonicalFile();
        if (!file.getAbsolutePath().startsWith(baseDir)) {
            resp.sendError(HttpServletResponse.SC_FORBIDDEN, "非法路徑");
            return;
        }
        if (!file.exists() || !file.isFile()) {
            resp.sendError(HttpServletResponse.SC_NOT_FOUND, "檔案不存在");
            return;
        }
        
        // 設定強制下載 MIME 類型
        resp.setContentType("application/octet-stream");
        resp.setHeader("Accept-Ranges", "bytes"); // 支援斷點續傳
        
        // 處理中文檔名編碼 (核心難點)
        String encodedFileName = encodeFileName(showName, req.getHeader("User-Agent"));
        resp.setHeader("Content-Disposition", "attachment; filename=\"" + encodedFileName + "\"");
        
        // 檔案大小與斷點續傳處理
        long fileLength = file.length();
        resp.setHeader("Content-Length", String.valueOf(fileLength));
        
        // 處理 Range 請求 (斷點續傳)
        long start = 0, end = fileLength - 1;
        String rangeHeader = req.getHeader("Range");
        if (rangeHeader != null && rangeHeader.startsWith("bytes=")) {
            String[] ranges = rangeHeader.substring(6).split("-");
            try {
                start = Long.parseLong(ranges[0]);
                if (ranges.length > 1 && !ranges[1].isEmpty()) {
                    end = Long.parseLong(ranges[1]);
                }
            } catch (NumberFormatException ignored) {}
            resp.setStatus(HttpServletResponse.SC_PARTIAL_CONTENT); // 206
            resp.setHeader("Content-Range", "bytes " + start + "-" + end + "/" + fileLength);
            resp.setHeader("Content-Length", String.valueOf(end - start + 1));
        }
        
        // 流式傳輸 (避免大檔案 OOM)
        try (FileInputStream fis = new FileInputStream(file);
             BufferedInputStream bis = new BufferedInputStream(fis, BUFFER_SIZE);
             ServletOutputStream sos = resp.getOutputStream()) {
            
            bis.skip(start);
            byte[] buffer = new byte[BUFFER_SIZE];
            long remaining = end - start + 1;
            int bytesRead;
            while (remaining > 0 && (bytesRead = bis.read(buffer, 0, (int)Math.min(BUFFER_SIZE, remaining))) != -1) {
                sos.write(buffer, 0, bytesRead);
                remaining -= bytesRead;
            }
            sos.flush();
        }
    }
    
    /** 
     * 根據 User-Agent 產生相容的 Content-Disposition filename 參數
     * RFC 5987 (UTF-8'') 為標準,但舊版 IE/Edge 需特殊處理
     */
    private String encodeFileName(String fileName, String userAgent) throws UnsupportedEncodingException {
        String ua = (userAgent == null) ? "" : userAgent.toLowerCase();
        
        if (ua.contains("msie") || ua.contains("trident") || ua.contains("edge")) {
            // IE / 老版 Edge: URLEncoder + 空格轉 %20
            return URLEncoder.encode(fileName, StandardCharsets.UTF_8.name()).replace("+", "%20");
        } else if (ua.contains("chrome")) {
            // Chrome: RFC 5987 格式
            return "UTF-8''" + URLEncoder.encode(fileName, StandardCharsets.UTF_8.name()).replace("+", "%20");
        } else if (ua.contains("firefox")) {
            // Firefox: RFC 5987 或 ISO-8859-1 (舊版)
            return "UTF-8''" + URLEncoder.encode(fileName, StandardCharsets.UTF_8.name()).replace("+", "%20");
        } else if (ua.contains("safari")) {
            // Safari: ISO-8859-1 編碼 (舊版) 或 RFC 5987
            return new String(fileName.getBytes(StandardCharsets.UTF_8), StandardCharsets.ISO_8859_1);
        } else {
            // 標準 RFC 5987
            return "UTF-8''" + URLEncoder.encode(fileName, StandardCharsets.UTF_8.name()).replace("+", "%20");
        }
    }
}

關鍵技術點解析

1. 中文檔名編碼策略對照

瀏覽器支援格式程式碼處理
Chrome 現代RFC 5987 (UTF-8'')"UTF-8''" + URLEncoder.encode(name, "UTF-8")
Firefox 現代RFC 5987同上
Safari 現代RFC 5987同上
IE / 老 EdgeURLEncoder (UTF-8)URLEncoder.encode(name, "UTF-8").replace("+", "%20")
舊版瀏覽器ISO-8859-1new String(name.getBytes("UTF-8"), "ISO-8859-1")

2. 斷點續傳 (HTTP Range Requests)

  • 請求標頭:Range: bytes=0-1023
  • 回應狀態:206 Partial Content
  • 回應標頭:Content-Range: bytes 0-1023/2048, Accept-Ranges: bytes
  • 支援下載工具 (IDM、瀏覽器內建) 暫停/繼續

3. 安全性:路徑遍歷防護

File file = new File(baseDir, fileName).getCanonicalFile();
if (!file.getAbsolutePath().startsWith(baseDir)) {
    // 拒絕存取
}

使用 getCanonicalFile() 解析符號連結與相對路徑,確保在允許目錄內。

4. 大檔案記憶體控制

  • **串流傳輸**:FileInputStream → BufferedInputStream → ServletOutputStream,不載入整個檔案到記憶體
  • **緩衝區大小**:8KB-64KB 平衡系統呼叫次數與記憶體佔用
  • **關閉資源**:try-with-resources 確保關閉

前端調用範例

<a href="/download?fileName=report_2024.pdf&showName=2024年營運報告.pdf">下載報告</a>

<!-- AJAX 觸發下載 (需 Blob 處理) -->
<script>
async function downloadFile(fileName, showName) {
    const resp = await fetch(`/download?fileName=${encodeURIComponent(fileName)}&showName=${encodeURIComponent(showName)}`);
    const blob = await resp.blob();
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = showName;
    a.click();
    URL.revokeObjectURL(url);
}
</script>

Spring Boot 簡化版

@GetMapping("/download")
public ResponseEntity download(@RequestParam String fileName, 
                                         @RequestParam String showName,
                                         HttpServletRequest request) throws IOException {
    File file = new File(baseDir, fileName);
    Resource resource = new FileSystemResource(file);
    
    String encodedName = encodeFileName(showName, request.getHeader("User-Agent"));
    
    return ResponseEntity.ok()
        .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + encodedName + "\"")
        .header(HttpHeaders.CONTENT_TYPE, "application/octet-stream")
        .header(HttpHeaders.ACCEPT_RANGES, "bytes")
        .contentLength(file.length())
        .body(resource);
}

總結

檔案下載看似簡單,實則涉及 **編碼相容性、串流傳輸、範圍請求、安全防護** 多個維度。本文提供的 Servlet 實作涵蓋生產環境所有關鍵點:中文檔名多瀏覽器相容、斷點續傳支援、大檔案記憶體安全、路徑遍歷防護。Spring Boot 專案可使用 ResponseEntity<Resource> 簡化實作,核心邏輯不變。

copyright © 萬盛學電腦網 all rights reserved