iText 7 实战：用 PdfDocument 和 PdfWriter 优雅处理空数据PDF生成（Java版）

在数据处理和报表生成的实际业务场景中，我们经常会遇到一个看似简单却令人头疼的问题——当数据源为空时，如何优雅地生成PDF文档？传统解决方案往往需要在业务逻辑中增加大量条件判断，而iText 7的全新API设计为我们提供了更优雅的解决之道。

1. 从iText 5到iText 7：架构革新与问题根源

iText库从5.x升级到7.x并非简单的版本迭代，而是一次彻底的重构。新版本在保持核心功能的同时，对API进行了全面优化，特别是在异常处理和空数据场景下表现更为健壮。

1.1 经典问题的重现

在iText 5中，开发者经常会遇到这样的异常堆栈：

com.itextpdf.text.DocumentException: The document has no pages.
    at com.itextpdf.text.pdf.PdfWriter.close(PdfWriter.java:1226)
    at com.itextpdf.text.Document.close(Document.java:416)

这个异常的本质原因是：当尝试关闭一个未添加任何页面的PDF文档时，iText 5会主动抛出异常。这种设计在早期版本中被认为是合理的——毕竟没有内容的文档确实没有实际意义。

1.2 iText 7的哲学转变

iText 7对此问题采取了完全不同的处理策略：

1. 宽容性设计 ：允许创建和保存空文档
2. 明确状态管理 ：通过PdfDocument对象清晰跟踪文档状态
3. 智能默认值 ：当未添加内容时自动生成合规的基础结构

这种转变反映了现代API设计理念——库应该处理边缘情况，而不是将问题抛给开发者。

2. 核心API对比：新旧解决方案剖析

让我们通过一个典型场景来对比两种版本的实现差异：当数据列表为空时，生成带有默认提示的PDF文档。

2.1 iText 5的典型解决方案

// iText 5传统方案
Document document = new Document();
PdfWriter writer = PdfWriter.getInstance(document, outputStream);
document.open();

if(dataList.isEmpty()) {
    // 必须手动添加默认内容
    document.add(new Paragraph("No data available"));
} else {
    // 正常处理数据
    processData(document, dataList);
}

document.close();

这种实现存在几个明显问题：

• 业务逻辑与异常处理耦合 ：必须提前判断空状态
• 代码重复 ：每个生成点都需要相同检查
• 维护困难 ：默认内容分散在各处

2.2 iText 7的现代化实现

// iText 7改进方案
PdfDocument pdfDoc = new PdfDocument(new PdfWriter(outputStream));
Document document = new Document(pdfDoc);

try {
    processData(document, dataList);
} catch (EmptyDataException e) {
    // 集中处理空状态
    document.add(new Paragraph("No data available"));
} finally {
    document.close();
}

新版本的优势显而易见：

1. 异常处理集中化 ：通过统一捕获EmptyDataException处理空状态
2. 自动空文档支持 ：即使不添加内容也不会抛出异常
3. 资源管理更安全 ：使用try-with-resources或finally块确保关闭

3. 实战：构建健壮的PDF生成服务

基于iText 7的新特性，我们可以设计一个更健壮的PDF生成服务。以下是一个完整实现示例：

3.1 基础服务架构

public class PdfGenerator {
    private static final Font DEFAULT_FONT = PdfFontFactory.createFont(StandardFonts.HELVETICA);
    private static final float DEFAULT_MARGIN = 36f; // 0.5英寸
    
    public void generatePdf(OutputStream output, List<Data> data) {
        PdfDocument pdfDoc = new PdfDocument(new PdfWriter(output));
        try (Document document = new Document(pdfDoc)) {
            document.setMargins(DEFAULT_MARGIN, DEFAULT_MARGIN, 
                              DEFAULT_MARGIN, DEFAULT_MARGIN);
            
            if (data == null || data.isEmpty()) {
                addDefaultContent(document);
            } else {
                addDataContent(document, data);
            }
        }
    }
    
    private void addDefaultContent(Document document) {
        document.add(new Paragraph("No data available")
            .setFont(DEFAULT_FONT)
            .setFontSize(12));
    }
    
    private void addDataContent(Document document, List<Data> data) {
        // 实际数据处理逻辑
    }
}

3.2 高级特性集成

iText 7还支持更灵活的内容生成策略：

1. 模板方法模式 ：定义生成流程骨架
2. 策略模式 ：动态切换内容生成算法
3. 装饰器模式 ：增强基础文档功能

public interface ContentStrategy {
    void apply(Document document) throws IOException;
}

public class DefaultContentStrategy implements ContentStrategy {
    @Override
    public void apply(Document document) {
        document.add(new Paragraph("No data available"));
    }
}

public class PdfGenerationService {
    private ContentStrategy defaultStrategy = new DefaultContentStrategy();
    
    public void generate(PdfWriter writer, ContentStrategy strategy) {
        PdfDocument pdfDoc = new PdfDocument(writer);
        try (Document doc = new Document(pdfDoc)) {
            try {
                strategy.apply(doc);
            } catch (Exception e) {
                defaultStrategy.apply(doc);
            }
        }
    }
}

4. 迁移指南与最佳实践

对于从iText 5升级到iText 7的团队，以下建议可以帮助平滑过渡：

4.1 代码迁移检查清单

iText 5 类/方法	iText 7 替代方案	注意事项
Document	Document + PdfDocument	现在需要组合使用
PdfWriter.getInstance()	new PdfWriter()	构造函数简化
PdfStamper	PdfDocument + PdfPage	表单处理API变化较大
BaseFont	PdfFontFactory	字体处理更现代化

4.2 性能优化技巧

1. 对象复用 ：对于高频生成的PDF，复用 PdfDocument 配置
2. 内存管理 ：使用 ByteArrayOutputStream 缓冲大数据量
3. 字体缓存 ：预加载常用字体避免重复创建

// 字体缓存示例
public class FontProvider {
    private static final Map<String, PdfFont> cache = new ConcurrentHashMap<>();
    
    public static PdfFont getFont(String name) throws IOException {
        return cache.computeIfAbsent(name, 
            k -> PdfFontFactory.createFont(name));
    }
}

4.3 异常处理建议

iText 7引入了更精细的异常体系：

• PdfException ：基础异常类
• PdfDocumentException ：文档操作相关错误
• PdfFontException ：字体处理问题

推荐的处理模式：

try {
    // PDF生成代码
} catch (PdfDocumentException e) {
    // 文档结构问题
    logger.error("PDF document error", e);
    throw new GenerationException("Invalid document structure");
} catch (PdfFontException e) {
    // 字体相关问题
    logger.error("Font processing error", e);
    throw new GenerationException("Font configuration error");
} catch (IOException e) {
    // IO问题
    logger.error("IO error during generation", e);
    throw new GenerationException("Output stream error");
}

5. 高级场景：动态内容与条件生成

对于复杂业务系统，PDF生成往往需要更灵活的策略。iText 7的模块化设计完美支持这些高级用例。

5.1 动态页眉页脚

public class DynamicHeaderFooter implements IEventHandler {
    @Override
    public void handleEvent(Event event) {
        PdfDocumentEvent docEvent = (PdfDocumentEvent) event;
        PdfDocument pdfDoc = docEvent.getDocument();
        PdfPage page = docEvent.getPage();
        
        // 只在有内容时添加页眉
        if(pdfDoc.getNumberOfPages() > 0) {
            addHeader(page);
            addFooter(page);
        }
    }
    
    private void addHeader(PdfPage page) {
        // 具体实现
    }
}

// 使用示例
PdfDocument pdfDoc = new PdfDocument(new PdfWriter(out));
pdfDoc.addEventHandler(PdfDocumentEvent.START_PAGE, 
                      new DynamicHeaderFooter());

5.2 条件内容生成器

public interface ContentCondition {
    boolean shouldGenerate(DocumentContext context);
}

public class DataDrivenCondition implements ContentCondition {
    private final List<?> data;
    
    public boolean shouldGenerate(DocumentContext ctx) {
        return data != null && !data.isEmpty();
    }
}

public class PdfGenerator {
    public void generate(OutputStream out, 
                        ContentCondition condition, 
                        ContentProvider provider) {
        PdfDocument pdfDoc = new PdfDocument(new PdfWriter(out));
        try (Document doc = new Document(pdfDoc)) {
            if (condition.shouldGenerate(new DocumentContext(doc))) {
                provider.provide(doc);
            } else {
                // 默认内容
            }
        }
    }
}

在实际项目中，我们发现iText 7的这种设计模式特别适合需要生成复杂报表的系统。通过将内容生成逻辑与文档结构分离，代码的可维护性得到了显著提升。