Java ZipEntry 怎么读取和保留 extra 元数据

Java 的 ZipEntry 不只有名称、时间和压缩方法，还可以携带 ZIP 条目的 optional extra field data。要在转存或重建归档时保留它，核心做法是读取 getExtra() 返回的字节，在创建目标条目后调用 setExtra(byte[])；这段数据应先按“不透明字节”处理，只有明确支持某种格式时才解析其中的字段。

官方资料：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/zip/ZipEntry.html

这篇文章只讨论 ZipEntry extra 的读取、复制和归档转存边界，不解析厂商私有字段。这样既能避免转换器无意丢失元数据，也能把未知字段带来的输入风险限制在可审计的范围内。

先划定 ZipEntry extra 的数据边界

getExtra() 返回条目的 extra field data；如果条目没有这类数据，返回值是 null。它的类型是 byte[]，不是已经拆好的键值表，也不是可以默认按 UTF-8 解码的文本。ZIP 生态中的扩展字段可能来自不同工具，字节的具体布局必须由对应规范或明确的供应方协议解释。

这给转存程序划出了三层边界：

• 名称、注释、压缩方法和时间等普通属性，由 ZipEntry 的专用方法管理。
• extra 是一段可选的原始字节，保留它不等于理解它。
• 厂商私有字段只有在项目明确支持、限制长度并处理格式错误时才适合解析。

因此，最稳妥的默认策略是“读取—复制—记录长度”，而不是“读取—猜测格式—重编码”。

用 getExtra 和 setExtra 复制原始字节

下面的辅助方法只负责创建一个带有相同名称、注释、时间和 extra 的目标条目。它不复制文件内容，也不替调用方决定未知字段的含义；真正写入内容时，仍需由调用方把源条目的数据流写入目标归档。

import java.io.IOException;
import java.util.Arrays;
import java.util.zip.ZipEntry;

final class ZipEntryMetadata {
    static ZipEntry copyMetadata(ZipEntry source) throws IOException {
        if (source == null) {
            // 入口参数为空时立即失败，避免把错误拖到写 ZIP 的阶段。
            throw new NullPointerException("source entry");
        }

        ZipEntry target = new ZipEntry(source.getName());

        // 只复制已知的普通属性；压缩数据本身由 ZipOutputStream 负责写入。
        if (source.getMethod() >= 0) {
            target.setMethod(source.getMethod());
        }
        if (source.getComment() != null) {
            target.setComment(source.getComment());
        }
        if (source.getLastModifiedTime() != null) {
            target.setLastModifiedTime(source.getLastModifiedTime());
        }

        byte[] extra = source.getExtra();
        if (extra != null) {
            // 复制数组，避免调用方后续修改 source 的字节影响 target。
            target.setExtra(Arrays.copyOf(extra, extra.length));
        }
        return target;
    }
}

这里对 extra 使用 Arrays.copyOf 有两个作用：保留 null 与“没有 extra”的语义，并让目标条目持有自己的数组副本。若业务明确需要保留创建时间或访问时间，也应在确认目标 JDK 和归档策略后单独复制，不要把所有未知字节自动拆开。

把普通属性与扩展字段分开处理

如果只是复制同一个条目的元数据，也可以使用 new ZipEntry(source)。Oracle API 将它描述为使用指定条目的字段创建新条目，这适合“整体复制”的场景。但在跨系统归档、清洗输入或安全边界较严格的场景，显式白名单更容易审计：代码能清楚地表达哪些普通属性被保留，以及 extra 是否作为原始字节转存。

写入新归档时，建议把属性复制和内容复制放在同一个条目生命周期内：

import java.io.IOException;
import java.util.zip.ZipEntry;
import java.util.zip.ZipInputStream;
import java.util.zip.ZipOutputStream;

static void copyOneEntry(ZipInputStream in, ZipOutputStream out,
                         ZipEntry source) throws IOException {
    ZipEntry target = ZipEntryMetadata.copyMetadata(source);

    // 先注册目标条目，再复制当前条目的内容字节。
    out.putNextEntry(target);
    byte[] buffer = new byte[8192];
    int read;
    while ((read = in.read(buffer)) != -1) {
        // 循环只处理当前条目数据，不把下一个条目读入目标条目。
        out.write(buffer, 0, read);
    }
    // 关闭条目而不是关闭整个归档流，便于继续处理后续条目。
    out.closeEntry();
}

对 STORED 条目，还要特别注意大小和 CRC 等写入前提；不能因为 extra 被复制了，就认为目标条目的压缩属性已经自动满足。本文的重点是 extra 的生命周期，内容复制和压缩方法应按你的输入流实现另行处理。

为长度和未知字段设置防护

Oracle 文档说明，调用 setExtra 可能改变由扩展时间字段提供的时间属性；同时，条目名称、注释、extra 与中央目录头组合后的长度超过 ZIP 限制时会抛出 IllegalArgumentException。这意味着 extra 不是“随便塞进 byte[] 就一定能写出”的旁路字段。

面对外部 ZIP 文件，可以在复制前做轻量的输入控制，但不要把控制写成对未知字段的猜测解析：

import java.util.Arrays;
import java.util.zip.ZipEntry;

static void applyOpaqueExtra(ZipEntry target, byte[] sourceExtra) {
    if (sourceExtra == null) {
        // null 表示没有 extra；不要为了方便改成一个空数组。
        return;
    }
    if (sourceExtra.length > 60_000) {
        // 留出名称、注释和中央目录头空间，先拒绝异常大的扩展字段。
        throw new IllegalArgumentException("extra field is too large");
    }
    try {
        // 未知格式只原样保存；只有明确协议才进入专用解析器。
        target.setExtra(Arrays.copyOf(sourceExtra, sourceExtra.length));
    } catch (IllegalArgumentException ex) {
        // 将格式边界转换成调用方可记录的业务错误，不继续写入半成品条目。
        throw new IllegalArgumentException("invalid ZipEntry extra field", ex);
    }
}

这里的 60,000 字节是示例中的保守业务阈值，不是 ZIP 规范的通用最大值。实际项目要把名称、注释、供应方字段上限和部署资源预算一起纳入配置，并在拒绝时记录条目名称、extra 是否存在和长度，不要把整段原始内容写进普通日志。

用审计清单确认转存没有丢字段

发布归档转换器前，可以围绕每个条目留下以下几类记录：

这类审计记录证明的是“转换器执行了什么策略”，不是证明未知字段的业务含义。若确实需要读取某种扩展字段，应为该字段单独建立版本、长度、重复字段和错误处理规则，并把解析结果与原始字节分开保存。

常见问题

getExtra() 返回 null 还是空数组？

官方 API 说明没有 extra 时返回 null。复制时应保留这个语义，除非你的业务层已经明确定义空数组和缺失字段等价。

复制 extra 后就能恢复所有时间属性吗？

不能简单这样保证。扩展时间字段可能影响条目的时间属性，而 ZipEntry 也提供了专门的时间方法。需要保留时间时，应按目标归档实现明确复制时间属性并处理范围差异。

可以把 extra 当成字符串保存吗？

不建议。它是原始字节，除非对应字段规范明确规定字符编码，否则转成字符串可能破坏字节内容。默认应复制字节；需要解析时使用该字段的正式格式。

小结

Java ZipEntry 保留 extra 元数据的关键不是记住一个 setter，而是保持数据边界：用 getExtra() 读取，用独立数组和 setExtra() 原样复制，把普通属性列入显式策略，对长度异常和未知厂商字段设置防护，再用条目级审计记录确认转存没有悄悄丢失。这样做既满足归档兼容性，也不会把未解析的输入误当成可信结构。