🔧 实战案例 | 如何优雅生成「多层级分类文件包」？Java 实现企业级 ZIP 打包方案

在开发企业管理系统时，我们常常会遇到这样的需求：

📥 管理员需要一键导出多个项目的交付资料，每份资料需按“项目类型”分类，内部再按“客户+项目名”组织，结构清晰，用户下载后开箱即用。

比如：

项目交付资料/
├── 客户A_智慧园区系统/
│   ├── 方案设计.pdf
│   └── 验收报告.docx
          
项目备份存档/
├── 客户A_智慧园区系统/
│   ├── 方案设计.pdf
│   └── 补充说明.xlsx

这个结构看似简单，但在 Java 中要动态生成带多级目录的 ZIP 包，并支持中文路径、避免覆盖、保证跨平台兼容性，其实并不容易。

今天，我们就来手把手实现一个 生产级可用的“多层级文件打包工具”，并封装成可复用的通用组件。

🎯 一、需求拆解

我们先明确目标：

需求点	说明
✅ 支持多个主分类	如“项目交付资料”、“项目备份存档”等
✅ 每个主分类下有子文件夹	格式：`客户名_项目名称`
✅ 子文件夹内存放各类文件	PDF、Word、Excel 等
✅ 中文路径不乱码	解压后目录结构完整
✅ 自动创建目录结构	不依赖脚本或临时文件
✅ 可扩展、可复用	封装为工具类，便于集成到各类系统

💡 二、技术选型与难点

Java 原生提供了 java.util.zip.ZipOutputStream，但：

❌ 默认不支持 UTF-8 路径（旧版 JDK 解压会乱码）
❌ ZIP 不自动创建目录（需手动添加目录条目）
❌ 多层级路径需精确拼接，容易出错

✅ 我们的解决方案：

使用 StandardCharsets.UTF_8 初始化 ZipOutputStream
显式添加目录条目（以 / 结尾的 ZipEntry）
用 Map<String, List<FileItem>> 管理“主分类 → 文件列表”的映射
封装为通用工具类，适用于档案、合同、交付物等场景

🛠️ 三、核心代码实现

1. 定义文件项实体类

public static class FileItem {
    private String filePath;     // 文件绝对路径
    private String clientName;   // 客户名称
    private String projectName;  // 项目名称

    public FileItem(String filePath, String clientName, String projectName) {
        this.filePath = filePath;
        this.clientName = clientName;
        this.projectName = projectName;
    }

    // 构建子文件夹名
    public String getSubFolderName() {
        return (clientName != null ? clientName : "未知客户") +
               "_" +
               (projectName != null ? projectName : "未知项目");
    }

    // getter 省略...
}

2. 多主分类压缩核心逻辑

public static File packFilesByCategories(
        String zipOutputPath,
        Map<String, List<FileItem>> categoryToFileItems) {

    if (categoryToFileItems == null || categoryToFileItems.isEmpty()) {
        throw new IllegalArgumentException("文件分类不能为空");
    }

    File zipFile = new File(zipOutputPath);
    if (!zipFile.getParentFile().exists()) {
        zipFile.getParentFile().mkdirs();
    }

    try (ZipOutputStream zos = new ZipOutputStream(
            new FileOutputStream(zipFile), StandardCharsets.UTF_8)) {

        byte[] buffer = new byte[8192];
        Set<String> createdFolders = new HashSet<>();

        for (Map.Entry<String, List<FileItem>> entry : categoryToFileItems.entrySet()) {
            String categoryName = entry.getKey(); // 如“项目交付资料”

            for (FileItem item : entry.getValue()) {
                File srcFile = new File(item.getFilePath());
                if (!srcFile.exists()) {
                    System.out.println("⚠️ 跳过不存在文件：" + srcFile.getAbsolutePath());
                    continue;
                }

                // 构建 ZIP 内路径：项目交付资料/客户A_智慧园区系统/方案设计.pdf
                String subFolder = item.getSubFolderName();
                String folderPath = categoryName + "/" + subFolder + "/";
                String entryName = folderPath + srcFile.getName();

                // 创建目录条目（避免重复）
                if (createdFolders.add(folderPath)) {
                    zos.putNextEntry(new ZipEntry(folderPath));
                    zos.closeEntry();
                }

                // 写入文件
                zos.putNextEntry(new ZipEntry(entryName));
                try (FileInputStream fis = new FileInputStream(srcFile)) {
                    int len;
                    while ((len = fis.read(buffer)) > 0) {
                        zos.write(buffer, 0, len);
                    }
                }
                zos.closeEntry();

                System.out.println("✅ 已添加：" + entryName);
            }
        }
        zos.flush();
    } catch (IOException e) {
        throw new RuntimeException("打包失败", e);
    }

    return zipFile;
}

🧪 四、使用案例：一键生成结构化文件包

// 准备数据
Map<String, List<FileItem>> fileMap = new LinkedHashMap<>();

// 第一类：项目交付资料
fileMap.put("项目交付资料", Arrays.asList(
    new FileItem("/tmp/设计文档.pdf", "客户A", "智慧园区系统"),
    new FileItem("/tmp/验收报告.docx", "客户A", "智慧园区系统")
));

// 第二类：历史存档备份
fileMap.put("项目备份存档", Arrays.asList(
    new FileItem("/tmp/设计文档.pdf", "客户A", "智慧园区系统"),
    new FileItem("/tmp/会议纪要.xlsx", "客户A", "智慧园区系统")
));

// 生成 ZIP
File zip = FilePackager.packFilesByCategories(
    "/Users/admin/Desktop/项目资料包.zip", 
    fileMap
);

System.out.println("🎉 打包完成：" + zip.getAbsolutePath());

✅ 生成结构如下：

项目交付资料/
└── 客户A_智慧园区系统/
    ├── 设计文档.pdf
    └── 验收报告.docx

项目备份存档/
└── 客户A_智慧园区系统/
    ├── 设计文档.pdf
    └── 会议纪要.xlsx

🌟 五、设计亮点

亮点	说明
🔹 多主分类支持	适用于“交付/存档/审核”等多场景
🔹 中文路径兼容	UTF-8 编码，Win/Mac/Linux 通用
🔹 结构清晰	用户解压即用，提升体验
🔹 可扩展性强	可接入合同系统、档案管理、客户门户
🔹 异常处理完善	跳过无效文件，关键错误抛出

🚀 六、可扩展方向

场景	扩展建议
Web 下载	返回 `ResponseEntity<Resource>`
加时间戳	主目录加日期：`项目交付资料_20250405`
支持子文件	每个项目可包含多个附件
密码压缩	使用 `zip4j` 支持加密压缩包
异步导出	大文件包走异步任务 + 邮件通知