Apache Parquet-Java 中 ParquetWriter 重复初始化导致文件清空问题解析

问题现象

在使用 Apache Parquet-Java 库（1.14.1 版本）时，开发者遇到一个典型问题：当对同一个文件路径重复初始化 ParquetWriter 时，会导致已写入的 Parquet 文件内容被清空。具体表现为：

1. 第一次初始化 Writer 并写入数据后，文件正常保存
2. 在不关闭第一个 Writer 的情况下，对同一路径再次初始化 Writer
3. 原文件内容被清空，文件大小变为 0 字节
4. 尝试读取时出现"File cannot be read as parquet"错误

技术原理

这个现象背后涉及 Parquet 文件写入机制的两个关键点：

1. 文件句柄管理
   ParquetWriter 在初始化时会立即创建目标文件并获取写入句柄。当对同一路径重复初始化时，后创建的 Writer 会覆盖前一个文件句柄，导致文件被截断。

2. 写时提交机制
   Parquet 采用"写时提交"模式，数据实际写入发生在以下时机：

   • 达到行组(row group)大小阈值
   • 显式调用 flush() 方法
   • Writer 关闭时

问题复现与验证

通过以下典型错误代码可以复现该问题：

// 第一次初始化并写入
ParquetWriter<GenericRecord> writer = AvroParquetWriter
    .<GenericRecord>builder(new LocalOutputFile(path))
    .withSchema(schema)
    .build();
writer.write(record1);
writer.close();

// 错误操作：对同一路径再次初始化
writer = AvroParquetWriter
    .<GenericRecord>builder(new LocalOutputFile(path))  // 同一路径
    .withSchema(schema)
    .build();  // 此处会导致原文件被清空

解决方案

1. 正确做法
   确保每个输出路径只初始化一次 Writer，不同文件使用不同路径：

// 正确做法：使用不同路径
Path path1 = new Path("output1.parquet");
Path path2 = new Path("output2.parquet");

ParquetWriter writer1 = ...builder(path1)...;
ParquetWriter writer2 = ...builder(path2)...;

2. 防御性编程
   在初始化 Writer 前检查目标文件是否存在：

if (Files.exists(outputPath)) {
    throw new IllegalStateException("输出文件已存在");
}

3. 资源管理
   使用 try-with-resources 确保 Writer 正确关闭：

try (ParquetWriter writer = ...) {
    writer.write(records);
}

深入理解

这种现象实际上是设计使然，而非 bug。Parquet 采用这种设计是因为：

1. 保证写入原子性 - 避免产生部分写入的文件
2. 支持覆盖写入 - 某些场景需要替换整个文件
3. 与分布式文件系统兼容 - 如 HDFS 的写入语义

最佳实践建议

1. 对同一路径的写入操作应该复用同一个 Writer 实例
2. 需要并行写入时，确保使用不同的输出路径
3. 重要数据写入后立即验证文件完整性
4. 在生产环境中考虑使用 TemporaryFile 模式，写入完成后再重命名为最终文件名

通过理解这些底层机制，开发者可以避免类似问题，并编写出更健壮的 Parquet 文件处理代码。