Java实现ZIP压缩包的生成方案

文件/字节流输入
      │
      ▼
固定清单、权限检查、数量/大小限制
      │
      ▼
归档内路径规范化、排序、去重
      │
      ▼
写入 *.part 临时文件
      │  └─ 每个条目：putNextEntry → copy → closeEntry
      ▼
关闭 ZIP 流并重新打开校验
      │
      ├─ 失败：删除 *.part，记录 failureCode
      │
      ▼
原子移动为正式文件或上传对象存储
      │
      ▼
鉴权下载、短期链接、审计
      │
      ▼
保留期清理与失败告警

<properties>
    <maven.compiler.release>17</maven.compiler.release>
</properties>

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.FileVisitResult;
import java.nio.file.Files;
import java.io.IOException;
import java.nio.file.Path;
import java.nio.file.SimpleFileVisitor;
import java.nio.file.StandardCopyOption;
import java.nio.file.StandardOpenOption;
import java.nio.file.attribute.BasicFileAttributes;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import java.util.zip.ZipEntry;
import java.util.zip.ZipFile;
import java.util.zip.ZipOutputStream;

public final class ZipDirectoryDemo {

    private static final int BUFFER_SIZE = 8 * 1024;

    private ZipDirectoryDemo() {
    }

    /**
     * 将目录下的普通文件递归写入 ZIP，并在完成后校验条目列表。
     *
     * @param sourceRoot 源目录
     * @param targetZip  目标 ZIP 文件
     * @return 实际写入的条目数量
     * @throws IOException 文件访问、压缩或校验失败
     */
    public static int zipDirectory(Path sourceRoot, Path targetZip) throws IOException {
        Path normalizedRoot = sourceRoot.toAbsolutePath().normalize();
        if (!Files.isDirectory(normalizedRoot)) {
            throw new IOException("源目录不存在或不是目录: " + normalizedRoot);
        }

        List<Path> files = collectRegularFiles(normalizedRoot);
        List<String> expectedNames = files.stream()
                .map(path -> toArchiveName(normalizedRoot, path))
                .sorted()
                .toList();

        Path parent = targetZip.toAbsolutePath().normalize().getParent();
        if (parent != null) {
            Files.createDirectories(parent);
        }

        Path partFile = targetZip.resolveSibling(targetZip.getFileName() + ".part");
        try {
            try (OutputStream output = Files.newOutputStream(
                    partFile,
                    StandardOpenOption.CREATE,
                    StandardOpenOption.TRUNCATE_EXISTING,
                    StandardOpenOption.WRITE);
                 ZipOutputStream zipOutput = new ZipOutputStream(output)) {

                for (Path file : files.stream()
                        .sorted(Comparator.comparing(path -> toArchiveName(normalizedRoot, path)))
                        .toList()) {
                    String archiveName = toArchiveName(normalizedRoot, file);
                    ZipEntry entry = new ZipEntry(archiveName);
                    zipOutput.putNextEntry(entry);
                    try (InputStream input = Files.newInputStream(file)) {
                        copy(input, zipOutput);
                    } finally {
                        zipOutput.closeEntry();
                    }
                }
                zipOutput.finish();
            }

            validateZip(partFile, expectedNames);
            Files.move(
                    partFile,
                    targetZip,
                    StandardCopyOption.REPLACE_EXISTING,
                    StandardCopyOption.ATOMIC_MOVE);
            return expectedNames.size();
        } catch (IOException | RuntimeException ex) {
            Files.deleteIfExists(partFile);
            throw ex;
        }
    }

    private static List<Path> collectRegularFiles(Path root) throws IOException {
        List<Path> result = new ArrayList<>();
        Files.walkFileTree(root, new SimpleFileVisitor<>() {
            @Override
            public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
                if (attrs.isRegularFile()) {
                    result.add(file.toAbsolutePath().normalize());
                }
                return FileVisitResult.CONTINUE;
            }
        });
        return result;
    }

    private static String toArchiveName(Path root, Path file) {
        String name = root.relativize(file).toString().replace('\\', '/');
        validateArchiveName(name);
        return name;
    }

    private static void validateArchiveName(String name) {
        if (name.isBlank() || name.startsWith("/") || name.indexOf('\\0') >= 0) {
            throw new IllegalArgumentException("非法 ZIP 条目名称");
        }
        String[] segments = name.split("/");
        for (String segment : segments) {
            if (segment.isBlank() || segment.equals(".") || segment.equals("..")) {
                throw new IllegalArgumentException("ZIP 条目包含非法路径段: " + name);
            }
        }
    }

    private static void copy(InputStream input, OutputStream output) throws IOException {
        byte[] buffer = new byte[BUFFER_SIZE];
        int read;
        while ((read = input.read(buffer)) != -1) {
            output.write(buffer, 0, read);
        }
    }

    private static void validateZip(Path zipFile, List<String> expectedNames) throws IOException {
        Set<String> actualNames = new HashSet<>();
        try (ZipFile zip = new ZipFile(zipFile.toFile())) {
            zip.stream().forEach(entry -> actualNames.add(entry.getName()));
        }
        if (!actualNames.equals(new HashSet<>(expectedNames))) {
            throw new IOException("ZIP 条目校验失败，expected=" + expectedNames + ", actual=" + actualNames);
        }
    }

    public static void main(String[] args) throws IOException {
        Path source = Files.createTempDirectory("zip-source-");
        Files.createDirectories(source.resolve("reports"));
        Files.writeString(source.resolve("README.txt"), "zip demo");
        Files.writeString(source.resolve("reports/年报.csv"), "月份,金额\n1月,100\n");

        Path target = source.resolveSibling("zip-result.zip");
        int count = zipDirectory(source, target);
        System.out.printf("created=%s, entries=%d, bytes=%d%n", target, count, Files.size(target));
    }
}

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

zip:
  temp-dir: /var/app/zip-tmp
  allowed-root: /var/app/export-source
  max-entry-count: 10000
  max-entry-size-bytes: 536870912
  max-total-size-bytes: 2147483648
  buffer-size: 8192
  retention: 24h
  download-url-expire: 10m

import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.LinkOption;
import java.nio.file.Path;
import java.util.OptionalLong;

@FunctionalInterface
public interface ZipContent {

    /**
     * 每次调用都返回一个新的输入流；调用方负责关闭。
     */
    InputStream openStream() throws IOException;

    /**
     * 返回已知大小；未知时返回空。
     */
    default OptionalLong declaredSize() {
        return OptionalLong.empty();
    }

    static ZipContent fromPath(Path path) {
        Path normalized = path.toAbsolutePath().normalize();
        return new ZipContent() {
            @Override
            public InputStream openStream() throws IOException {
                return Files.newInputStream(normalized);
            }

            @Override
            public OptionalLong declaredSize() {
                try {
                    if (!Files.isRegularFile(normalized, LinkOption.NOFOLLOW_LINKS)) {
                        return OptionalLong.empty();
                    }
                    return OptionalLong.of(Files.size(normalized));
                } catch (IOException ex) {
                    return OptionalLong.empty();
                }
            }
        };
    }
}

import java.io.InputStream;
import java.util.Objects;

public record ZipEntrySpec(String archiveName, ZipContent content) {

    public ZipEntrySpec {
        Objects.requireNonNull(archiveName, "archiveName");
        Objects.requireNonNull(content, "content");
    }
}

import java.nio.file.Path;
import java.time.Duration;
import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "zip")
public class ZipArchiveProperties {

    /** ZIP 临时文件目录。 */
    private Path tempDir;

    /** 允许作为输入来源的根目录。 */
    private Path allowedRoot;

    /** 单个归档允许的最大条目数。 */
    private int maxEntryCount = 10_000;

    /** 单个条目的最大原始字节数。 */
    private long maxEntrySizeBytes = 512L * 1024 * 1024;

    /** 所有条目的最大原始字节总数。 */
    private long maxTotalSizeBytes = 2L * 1024 * 1024 * 1024;

    /** 流复制缓冲区大小。 */
    private int bufferSize = 8192;

    /** 临时文件保留时间。 */
    private Duration retention = Duration.ofHours(24);

    public Path getTempDir() {
        return tempDir;
    }

    public void setTempDir(Path tempDir) {
        this.tempDir = tempDir;
    }

    public Path getAllowedRoot() {
        return allowedRoot;
    }

    public void setAllowedRoot(Path allowedRoot) {
        this.allowedRoot = allowedRoot;
    }

    public int getMaxEntryCount() {
        return maxEntryCount;
    }

    public void setMaxEntryCount(int maxEntryCount) {
        this.maxEntryCount = maxEntryCount;
    }

    public long getMaxEntrySizeBytes() {
        return maxEntrySizeBytes;
    }

    public void setMaxEntrySizeBytes(long maxEntrySizeBytes) {
        this.maxEntrySizeBytes = maxEntrySizeBytes;
    }

    public long getMaxTotalSizeBytes() {
        return maxTotalSizeBytes;
    }

    public void setMaxTotalSizeBytes(long maxTotalSizeBytes) {
        this.maxTotalSizeBytes = maxTotalSizeBytes;
    }

    public int getBufferSize() {
        return bufferSize;
    }

    public void setBufferSize(int bufferSize) {
        this.bufferSize = bufferSize;
    }

    public Duration getRetention() {
        return retention;
    }

    public void setRetention(Duration retention) {
        this.retention = retention;
    }
}

import java.nio.file.Path;

public record ZipArchiveResult(
        Path archivePath,
        int entryCount,
        long sourceBytes,
        long archiveBytes,
        String sha256) {
}

public class ZipArchiveException extends RuntimeException {

    private final String failureCode;

    public ZipArchiveException(String failureCode, String message, Throwable cause) {
        super(message, cause);
        this.failureCode = failureCode;
    }

    public String getFailureCode() {
        return failureCode;
    }
}

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.AtomicMoveNotSupportedException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.nio.file.StandardOpenOption;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.HashSet;
import java.util.HexFormat;
import java.util.List;
import java.util.Objects;
import java.util.Set;
import java.util.stream.Collectors;
import java.util.zip.ZipEntry;
import java.util.zip.ZipFile;
import java.util.zip.ZipOutputStream;
import org.springframework.stereotype.Service;

@Service
public class ZipArchiveService {

    private final ZipArchiveProperties properties;

    public ZipArchiveService(ZipArchiveProperties properties) {
        this.properties = properties;
    }

    /**
     * 将多个内容源流式写入 ZIP 文件，并在发布前完成完整性校验。
     *
     * @param requestedEntries 输入条目；归档名必须唯一
     * @param archiveFileName  目标文件名，只允许普通文件名
     * @return 已发布的 ZIP 结果
     * @throws ZipArchiveException 参数、读取、校验或文件系统失败
     */
    public ZipArchiveResult create(List<ZipEntrySpec> requestedEntries, String archiveFileName) {
        List<ZipEntrySpec> entries = snapshotAndValidate(requestedEntries);
        Path tempDir = requireTempDir();
        Path target = tempDir.resolve(validateFileName(archiveFileName)).normalize();
        if (!target.getParent().equals(tempDir.toAbsolutePath().normalize())) {
            throw new ZipArchiveException("INVALID_ARCHIVE_NAME", "目标文件名不能包含路径", null);
        }
        Path part = target.resolveSibling(target.getFileName() + ".part");

        long sourceBytes = 0;
        try {
            Files.createDirectories(tempDir);
            try (OutputStream output = Files.newOutputStream(
                    part,
                    StandardOpenOption.CREATE,
                    StandardOpenOption.TRUNCATE_EXISTING,
                    StandardOpenOption.WRITE);
                 ZipOutputStream zipOutput = new ZipOutputStream(output)) {

                byte[] buffer = new byte[properties.getBufferSize()];
                for (ZipEntrySpec spec : entries) {
                    ZipEntry zipEntry = new ZipEntry(spec.archiveName());
                    zipOutput.putNextEntry(zipEntry);
                    try (InputStream input = spec.content().openStream()) {
                        long entryBytes = copyWithLimit(
                                input,
                                zipOutput,
                                buffer,
                                properties.getMaxEntrySizeBytes(),
                                sourceBytes,
                                properties.getMaxTotalSizeBytes());
                        sourceBytes = Math.addExact(sourceBytes, entryBytes);
                    } finally {
                        zipOutput.closeEntry();
                    }
                }
                zipOutput.finish();
            }

            validateZip(part, entries);
            moveAsPublished(part, target);
            return new ZipArchiveResult(
                    target,
                    entries.size(),
                    sourceBytes,
                    Files.size(target),
                    sha256(target));
        } catch (IOException | ArithmeticException ex) {
            deleteQuietly(part);
            throw new ZipArchiveException("ZIP_CREATE_FAILED", "ZIP 生成失败", ex);
        }
    }

    private List<ZipEntrySpec> snapshotAndValidate(List<ZipEntrySpec> requestedEntries) {
        if (requestedEntries == null || requestedEntries.isEmpty()) {
            throw new ZipArchiveException("EMPTY_ENTRIES", "至少需要一个 ZIP 条目", null);
        }
        if (requestedEntries.size() > properties.getMaxEntryCount()) {
            throw new ZipArchiveException("ENTRY_COUNT_LIMIT", "超过最大条目数", null);
        }

        List<ZipEntrySpec> snapshot = new ArrayList<>(requestedEntries);
        Set<String> names = new HashSet<>();
        long declaredTotal = 0;
        for (ZipEntrySpec spec : snapshot) {
            validateArchiveName(spec.archiveName());
            if (!names.add(spec.archiveName())) {
                throw new ZipArchiveException("DUPLICATE_ENTRY", "重复 ZIP 条目: " + spec.archiveName(), null);
            }
            long declaredSize = spec.content().declaredSize().orElse(-1);
            if (declaredSize > properties.getMaxEntrySizeBytes()) {
                throw new ZipArchiveException("ENTRY_SIZE_LIMIT", "单条目超过大小限制", null);
            }
            if (declaredSize >= 0) {
                declaredTotal = Math.addExact(declaredTotal, declaredSize);
            }
        }
        if (declaredTotal > properties.getMaxTotalSizeBytes()) {
            throw new ZipArchiveException("TOTAL_SIZE_LIMIT", "条目总大小超过限制", null);
        }
        snapshot.sort(java.util.Comparator.comparing(ZipEntrySpec::archiveName));
        return List.copyOf(snapshot);
    }

    private Path requireTempDir() {
        if (properties.getTempDir() == null) {
            throw new ZipArchiveException("TEMP_DIR_MISSING", "未配置 ZIP 临时目录", null);
        }
        return properties.getTempDir().toAbsolutePath().normalize();
    }

    private String validateFileName(String fileName) {
        if (fileName == null || fileName.isBlank()
                || fileName.contains("/")
                || fileName.contains("\\")
                || fileName.contains("..")
                || fileName.indexOf('\0') >= 0) {
            throw new ZipArchiveException("INVALID_ARCHIVE_NAME", "非法归档文件名", null);
        }
        return fileName.endsWith(".zip") ? fileName : fileName + ".zip";
    }

    private void validateArchiveName(String name) {
        if (name == null || name.isBlank() || name.startsWith("/")
                || name.contains("\\") || name.indexOf('\0') >= 0) {
            throw new ZipArchiveException("INVALID_ENTRY_NAME", "非法 ZIP 条目名", null);
        }
        for (String segment : name.split("/", -1)) {
            if (segment.isBlank() || segment.equals(".") || segment.equals("..")) {
                throw new ZipArchiveException("INVALID_ENTRY_NAME", "ZIP 条目包含路径穿越片段", null);
            }
        }
    }

    private long copyWithLimit(
            InputStream input,
            OutputStream output,
            byte[] buffer,
            long entryLimit,
            long alreadyWritten,
            long totalLimit) throws IOException {
        long entryBytes = 0;
        int read;
        while ((read = input.read(buffer)) != -1) {
            entryBytes = Math.addExact(entryBytes, read);
            long total = Math.addExact(alreadyWritten, entryBytes);
            if (entryBytes > entryLimit) {
                throw new IOException("单条目超过大小限制");
            }
            if (total > totalLimit) {
                throw new IOException("条目总大小超过限制");
            }
            output.write(buffer, 0, read);
        }
        return entryBytes;
    }

    private void validateZip(Path part, List<ZipEntrySpec> expected) throws IOException {
        Set<String> expectedNames = expected.stream()
                .map(ZipEntrySpec::archiveName)
                .collect(Collectors.toSet());
        Set<String> actualNames = new HashSet<>();
        try (ZipFile zipFile = new ZipFile(part.toFile())) {
            zipFile.stream().forEach(entry -> actualNames.add(entry.getName()));
        }
        if (!actualNames.equals(expectedNames)) {
            throw new IOException("ZIP 条目集合不一致");
        }
    }

    private void moveAsPublished(Path part, Path target) throws IOException {
        try {
            Files.move(part, target, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE);
        } catch (AtomicMoveNotSupportedException ex) {
            Files.move(part, target, StandardCopyOption.REPLACE_EXISTING);
        }
    }

    private String sha256(Path file) throws IOException {
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            try (InputStream input = Files.newInputStream(file)) {
                byte[] buffer = new byte[properties.getBufferSize()];
                int read;
                while ((read = input.read(buffer)) != -1) {
                    digest.update(buffer, 0, read);
                }
            }
            return HexFormat.of().formatHex(digest.digest());
        } catch (NoSuchAlgorithmException ex) {
            throw new IllegalStateException("JDK 未提供 SHA-256", ex);
        }
    }

    private void deleteQuietly(Path file) {
        try {
            Files.deleteIfExists(file);
        } catch (IOException ignored) {
            // 清理失败交给日志和定时清理任务兜底，不能覆盖原始失败原因。
        }
    }
}

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableConfigurationProperties(ZipArchiveProperties.class)
public class ZipConfiguration {
}

import jakarta.validation.constraints.NotBlank;

public record ZipDownloadRequest(@NotBlank String archiveId) {
}

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import org.springframework.core.io.FileSystemResource;
import org.springframework.core.io.Resource;
import org.springframework.http.ContentDisposition;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/zip-archives")
public class ZipDownloadController {

    private final ZipArchiveProperties properties;
    private final ZipArchiveAccessService accessService;

    public ZipDownloadController(
            ZipArchiveProperties properties,
            ZipArchiveAccessService accessService) {
        this.properties = properties;
        this.accessService = accessService;
    }

    @GetMapping("/{archiveId}/download")
    public ResponseEntity<Resource> download(@PathVariable String archiveId) throws IOException {
        Path archive = accessService.requireReadableArchive(archiveId);
        Resource resource = new FileSystemResource(archive);
        String downloadName = archive.getFileName().toString();
        ContentDisposition disposition = ContentDisposition.attachment()
                .filename(downloadName, StandardCharsets.UTF_8)
                .build();
        return ResponseEntity.ok()
                .contentType(MediaType.parseMediaType("application/zip"))
                .contentLength(Files.size(archive))
                .header(HttpHeaders.CONTENT_DISPOSITION, disposition.toString())
                .header(HttpHeaders.CACHE_CONTROL, "private, max-age=0, no-store")
                .body(resource);
    }
}

import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class ZipExceptionHandler {

    @ExceptionHandler(ZipArchiveException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public Map<String, String> handle(ZipArchiveException ex) {
        return Map.of(
                "code", ex.getFailureCode(),
                "message", "ZIP 处理失败");
    }
}

import java.io.IOException;
import java.io.OutputStream;

public interface ZipArchiveSink {

    OutputStream open(String archiveId) throws IOException;

    void publish(String archiveId, long size, String sha256) throws IOException;
}

requestId, archiveId, userId(脱敏), entryCount,
declaredBytes, writtenBytes, archiveBytes,
durationMs, status, failureCode

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;

import java.io.ByteArrayInputStream;
import java.nio.file.Path;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
import java.util.zip.ZipFile;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;

class ZipArchiveServiceTest {

    @TempDir
    Path tempDir;

    @Test
    void shouldCreateZipAndKeepDeterministicEntryNames() throws Exception {
        ZipArchiveProperties properties = new ZipArchiveProperties();
        properties.setTempDir(tempDir);
        properties.setMaxEntryCount(10);
        properties.setMaxEntrySizeBytes(1024);
        properties.setMaxTotalSizeBytes(4096);
        ZipArchiveService service = new ZipArchiveService(properties);

        ZipArchiveResult result = service.create(
                List.of(
                        new ZipEntrySpec("b.txt", () -> new ByteArrayInputStream("B".getBytes(StandardCharsets.UTF_8))),
                        new ZipEntrySpec("a/中文.txt", () -> new ByteArrayInputStream("A".getBytes(StandardCharsets.UTF_8)))),
                "demo");

        assertEquals(2, result.entryCount());
        try (ZipFile zipFile = new ZipFile(result.archivePath().toFile())) {
            assertEquals(2, zipFile.size());
            List<String> actualNames = zipFile.stream()
                    .map(entry -> entry.getName())
                    .collect(java.util.stream.Collectors.toCollection(ArrayList::new));
            assertEquals(List.of("a/中文.txt", "b.txt"), actualNames);
        }
    }

    @Test
    void shouldRejectDuplicateEntryName() {
        ZipArchiveProperties properties = new ZipArchiveProperties();
        properties.setTempDir(tempDir);
        ZipArchiveService service = new ZipArchiveService(properties);

        assertThrows(ZipArchiveException.class, () -> service.create(
                List.of(
                        new ZipEntrySpec("same.txt", () -> InputStream.nullInputStream()),
                        new ZipEntrySpec("same.txt", () -> InputStream.nullInputStream())),
                "duplicate.zip"));
    }
}

mvn -Dtest=ZipArchiveServiceTest test
unzip -l /var/app/zip-tmp/demo.zip
file /var/app/zip-tmp/demo.zip
sha256sum /var/app/zip-tmp/demo.zip