本地存档核心组件通过封装字节流容器实现高内聚：仅提供archiveto、listentries、extractto三个业务接口，隐藏buffer、zip.writer等细节，统一处理校验、错误恢复与格式控制，确保安全可复用的zip归档与解包。
用字节流容器配合封装思想构建本地存档核心组件，关键在于把“数据写入/读取逻辑”、“缓存策略”、“归档格式控制”和“错误边界处理”全部收束到一个职责明确、对外接口简洁的类中。它不暴露内部缓冲区、不依赖具体文件路径硬编码、不直接暴露InputStream/OutputStream实例——所有操作都通过受控方法完成。
明确核心职责与边界
这个组件只做一件事：安全、可复用地将一组字节数据打包为本地归档（如 ZIP），并支持后续按需解包。它不负责网络上传、不解析业务语义、不管理元数据生命周期。高内聚就体现在这里——所有与“本地字节归档”强相关的逻辑都在类内部闭环。
- 输入：原始字节数据（
byte[]或InputStream）+ 文件名映射关系 - 输出：生成一个合法 ZIP 文件（
File对象或Path） - 隐藏：
bytes.Buffer、zip.Writer、临时段管理、CRC 校验等细节 - 禁止外部直接调用
close()或修改内部Buffer，必须走组件提供的archive()和extract()
用私有字段封装字节流容器与状态
组件内部使用 bytes.Buffer 作为内存归档容器，但它绝不作为 public 字段或 getter 返回。整个生命周期由组件自己掌控：
- 构造时初始化
private final Buffer buffer = new Buffer()（Go 示例）或 Java 中用ByteArrayOutputStream+ZipOutputStream组合封装 - 所有写入操作仅通过
addEntry(String name, byte[] content)方法进入，该方法内部调用zipWriter.putNextEntry()和write()，并自动处理异常与资源清理 - 归档完成前禁止外部访问 buffer 内容；归档成功后只提供
toFile(Path target)方法一次性落盘，避免中间态被误用
行为封装：每个操作都带校验与一致性保障
不是简单转发 IO 调用，而是注入业务规则和防御逻辑：
-
addEntry会校验文件名是否含非法字符（如../）、内容长度是否超限、是否重复添加同名 entry -
archive()方法内部确保zipWriter.close()必然执行——这是 ZIP 完整性的生死线，用 try-finally 或 try-with-resources 封装，不交给调用方 - 若某次写入失败，整个归档视为无效，buffer 清空重置，不留下半成品
- 提供
isValidArchive()方法，基于 ZIP 格式头和中央目录结构做轻量验证，而不是只检查文件是否存在
接口暴露：稳定、语义清晰、无泄漏
对外只暴露三个核心方法，全部使用业务语言命名，不出现 “stream”、“buffer”、“writer” 等底层词：
-
ArchiveResult archiveTo(Path outputPath)：执行归档，返回包含成功状态、文件大小、entry 数量的结果对象 -
List<archiveentry> listEntries()</archiveentry>：返回归档内文件清单（不含字节内容），用于预览或校验 -
boolean extractTo(Path targetDir)：解压到指定目录，自动创建父级路径，拒绝路径遍历攻击
所有参数类型都是高层抽象（Path、String、自定义 ArchiveEntry），返回值不泄露任何流对象或缓冲区引用。内部实现哪怕从 ZIP 切换到 TAR.GZ，只要接口不变，上层代码完全无感。
