Spring Boot 實現多種來源的 Zip 多層目錄打包下載（本地文件HTTP混合）

需要將一批文件（可能分布在不同目錄、不同來源）打包成Zip格式，按目錄結構導出給用戶下載。

1. 核心思路

支持將本地服務器上的文件（如/data/upload/xxx.jpg）打包進Zip，保持原有目錄結構。
支持通過HTTP下載遠程文件寫入Zip。
所有寫入Zip的目錄名、文件名均需安全處理。
統一使用流式IO，適合大文件/大量文件導出，防止內存溢出。
目錄下無文件時寫入empty.txt標識。

2. 代碼實現

2.1 工具類：本地&HTTP兩種方式寫入Zip

package com.example.xiaoshitou.utils;import org.apache.commons.compress.archivers.zip.ZipArchiveEntry;
import org.apache.commons.compress.archivers.zip.ZipArchiveOutputStream;
import org.springframework.util.StreamUtils;
import org.springframework.util.StringUtils;import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.*;
import java.net.URL;
import java.net.URLConnection;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.time.LocalDate;/**** @title* @author shijiangyong* @date 2025/4/28 16:34**/
public class ZipDownloadUtils {private static final String SUFFIX_ZIP = ".zip";private static final String UNNAMED = "未命名";/*** 安全處理文件名/目錄名* @param name* @return*/public static String safeName(String name) {if (name == null) return "null";return name.replaceAll("[\\\\/:*?\"<>|]", "_");}/*** HTTP下載寫入Zip* @param zipOut* @param fileUrl* @param zipEntryName* @throws IOException*/public static void writeHttpFileToZip(ZipArchiveOutputStream zipOut, String fileUrl, String zipEntryName) throws IOException {ZipArchiveEntry entry = new ZipArchiveEntry(zipEntryName);zipOut.putArchiveEntry(entry);try (InputStream in = openHttpStream(fileUrl, 8000, 20000)) {byte[] buffer = new byte[4096];int len;while ((len = in.read(buffer)) != -1) {zipOut.write(buffer, 0, len);}} catch (Exception e) {zipOut.write(("下載失敗: " + fileUrl).getBytes(StandardCharsets.UTF_8));}zipOut.closeArchiveEntry();}/*** 本地文件寫入Zip* @param zipOut* @param localFilePath* @param zipEntryName* @throws IOException*/public static void writeLocalFileToZip(ZipArchiveOutputStream zipOut, String localFilePath, String zipEntryName) throws IOException {File file = new File(localFilePath);if (!file.exists() || file.isDirectory()) {writeTextToZip(zipOut, zipEntryName + "_empty.txt", "文件不存在或是目錄: " + localFilePath);return;}ZipArchiveEntry entry = new ZipArchiveEntry(zipEntryName);zipOut.putArchiveEntry(entry);try (InputStream fis = new FileInputStream(file)) {byte[] buffer = new byte[4096];int len;while ((len = fis.read(buffer)) != -1) {zipOut.write(buffer, 0, len);}}zipOut.closeArchiveEntry();}/*** 寫入文本文件到Zip（如empty.txt）* @param zipOut* @param zipEntryName* @param content* @throws IOException*/public static void writeTextToZip(ZipArchiveOutputStream zipOut, String zipEntryName, String content) throws IOException {ZipArchiveEntry entry = new ZipArchiveEntry(zipEntryName);zipOut.putArchiveEntry(entry);zipOut.write(content.getBytes(StandardCharsets.UTF_8));zipOut.closeArchiveEntry();}/*** 打開HTTP文件流* @param url* @param connectTimeout* @param readTimeout* @return* @throws IOException*/public static InputStream openHttpStream(String url, int connectTimeout, int readTimeout) throws IOException {URLConnection conn = new URL(url).openConnection();conn.setConnectTimeout(connectTimeout);conn.setReadTimeout(readTimeout);return conn.getInputStream();}/*** 從url獲取文件名* @param url* @return* @throws IOException*/public static String getFileName(String url)  {return url.substring(url.lastIndexOf('/')+1);}/*** 設置response* @param request* @param response* @param fileName* @throws UnsupportedEncodingException*/public static void setResponse(HttpServletRequest request, HttpServletResponse response, String fileName) throws UnsupportedEncodingException {if (!StringUtils.hasText(fileName)) {fileName = LocalDate.now() + UNNAMED;}if (!fileName.endsWith(SUFFIX_ZIP)) {fileName = fileName + SUFFIX_ZIP;}response.setHeader("Connection", "close");response.setHeader("Content-Type", "application/octet-stream;charset=UTF-8");String filename = encodeFileName(request, fileName);response.setHeader("Content-Disposition", "attachment;filename=" + filename);}/*** 文件名在不同瀏覽器兼容處理* @param request 請求信息* @param fileName 文件名* @return* @throws UnsupportedEncodingException*/public static String encodeFileName(HttpServletRequest request, String fileName) throws UnsupportedEncodingException {String userAgent = request.getHeader("USER-AGENT");// 火狐瀏覽器if (userAgent.contains("Firefox") || userAgent.contains("firefox")) {fileName = new String(fileName.getBytes(), "ISO8859-1");} else {// 其他瀏覽器fileName = URLEncoder.encode(fileName, "UTF-8");}return fileName;}
}

2.2 Controller 示例：按本地目錄結構批量導出

假設有如下導出結構：

用戶A/身份證/xxx.jpg (本地)xxx.png (本地)頭像/xxx.jpg (HTTP)
用戶B/empty.txt

模擬數據結構：

zipGroup:

import lombok.AllArgsConstructor;
import lombok.Data;import java.util.List;/**** @title* @author shijiangyong* @date 2025/4/28 16:36**/
@Data
@AllArgsConstructor
public class ZipGroup {/*** 用戶名、文件名*/private String dirName;private List<ZipSubDir> subDirs;
}

zipGroupDir:

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;import java.util.List;/**** @title* @author shijiangyong* @date 2025/4/28 16:37**/
@Data
@AllArgsConstructor
@NoArgsConstructor
public class ZipSubDir {/*** 子目錄*/private String subDirName;private List<ZipFileRef> fileRefs;
}

ZipFileRef:

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;/**** @title* @author shijiangyong* @date 2025/4/28 16:38**/
@Data
@AllArgsConstructor
@NoArgsConstructor
public class ZipFileRef {/*** 文件名*/private String name;/*** 本地路徑*/private String localPath;/*** http路徑*/private String httpUrl;
}

Controller通用代碼：

package com.example.xiaoshitou.controller;import com.example.xiaoshitou.service.ZipService;
import lombok.AllArgsConstructor;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;/**** @title* @author shijiangyong* @date 2025/4/28 16:50**/
@RestController
@RequestMapping("/zip")
@AllArgsConstructor
public class ZipController {private final ZipService zipService;/***  打包下載* @param response*/@GetMapping("/download")public void downloadZip(HttpServletRequest request, HttpServletResponse response) {zipService.downloadZip(request,response);}
}

Service 層代碼：

package com.example.xiaoshitou.service.impl;import com.example.xiaoshitou.entity.ZipFileRef;
import com.example.xiaoshitou.entity.ZipGroup;
import com.example.xiaoshitou.entity.ZipSubDir;
import com.example.xiaoshitou.service.ZipService;
import com.example.xiaoshitou.utils.ZipDownloadUtils;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.compress.archivers.zip.ZipArchiveOutputStream;
import org.springframework.stereotype.Service;import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.BufferedOutputStream;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.zip.Deflater;/**** @title* @author shijiangyong* @date 2025/4/28 16:43**/
@Slf4j
@Service
public class ZipServiceImpl implements ZipService {@Overridepublic void downloadZip(HttpServletRequest request, HttpServletResponse response) {// ==== 示例數據 ====List<ZipGroup> data = Arrays.asList(new ZipGroup("小明", Arrays.asList(new ZipSubDir("身份證(本地)", Arrays.asList(new ZipFileRef("","E:/software/test/1.png",""),new ZipFileRef("","E:/software/test/2.png",""))),new ZipSubDir("頭像(http)", Arrays.asList(// 百度隨便找的new ZipFileRef("","","https://pic4.zhimg.com/v2-4d9e9f936b9968f53be22b594aafa74f_r.jpg"))))),new ZipGroup("小敏", Collections.emptyList()));try (BufferedOutputStream bos = new BufferedOutputStream(response.getOutputStream());ZipArchiveOutputStream zipOut = new ZipArchiveOutputStream(bos)) {String fileName = "資料打包_" + System.currentTimeMillis() + ".zip";ZipDownloadUtils.setResponse(request,response, fileName);// 快速壓縮zipOut.setLevel(Deflater.BEST_SPEED);for (ZipGroup group : data) {String groupDir = ZipDownloadUtils.safeName(group.getDirName()) + "/";List<ZipSubDir> subDirs = group.getSubDirs();if (subDirs == null || subDirs.isEmpty()) {groupDir = ZipDownloadUtils.safeName(group.getDirName()) + "(無資料)/";ZipDownloadUtils.writeTextToZip(zipOut, groupDir + "empty.txt", "該目錄無任何資料");continue;}for (ZipSubDir subDir : subDirs) {String subDirPath = groupDir + ZipDownloadUtils.safeName(subDir.getSubDirName()) + "/";List<ZipFileRef> fileRefs = subDir.getFileRefs();if (fileRefs == null || fileRefs.isEmpty()) {subDirPath = groupDir + ZipDownloadUtils.safeName(subDir.getSubDirName()) + "(empty)/";ZipDownloadUtils.writeTextToZip(zipOut, subDirPath + "empty.txt", "該類型無資料");continue;}for (ZipFileRef fileRef : fileRefs) {if (fileRef.getLocalPath() != null && !fileRef.getLocalPath().isEmpty()) {String name = ZipDownloadUtils.getFileName(fileRef.getLocalPath());fileRef.setName(name);ZipDownloadUtils.writeLocalFileToZip(zipOut, fileRef.getLocalPath(), subDirPath + ZipDownloadUtils.safeName(fileRef.getName()));} else if (fileRef.getHttpUrl() != null && !fileRef.getHttpUrl().isEmpty()) {String name = ZipDownloadUtils.getFileName(fileRef.getHttpUrl());fileRef.setName(name);ZipDownloadUtils.writeHttpFileToZip(zipOut, fileRef.getHttpUrl(), subDirPath + ZipDownloadUtils.safeName(fileRef.getName()));}}}}zipOut.finish();zipOut.flush();response.flushBuffer();} catch (Exception e) {throw new RuntimeException("打包下載失敗", e);}}
}