JAVA HTML 转 PDF 和增加水印

一、背景与问题

在现代Web应用中，将动态生成的HTML内容转换为PDF文档是一种常见需求。例如：在线文档系统、报表生成系统、电子发票系统等场景都需要将用户界面内容持久化为可打印的PDF格式。同时，出于版权保护的需要，还需要在PDF中添加水印。

传统方案存在显著痛点：

HTML转PDF时需要处理复杂的布局和样式
水印需要在PDF层级上实现，而非简单叠加在HTML层
不同浏览器渲染差异导致的PDF格式不一致
大量文本生成时的性能瓶颈

二、基本原理

1. HTML转PDF的核心流程

HTML转PDF本质上是将网页的DOM结构和CSS样式转换为PDF的页面布局。这个过程包含三个核心阶段：

解析阶段：将HTML和CSS解析为DOM树和样式信息
布局阶段：根据CSS规范计算每个元素的布局位置
渲染阶段：将布局结果转换为PDF的图形指令

PDF的生成涉及两个关键技术点：

PDF文档结构：包含页眉页脚、字体定义、页面布局等
图形绘制：通过PDF的图形指令实现文本、图像、表格等元素的绘制

2. 水印的实现原理

水印的实现需要在PDF的底层进行操作，通常采用两种方式：

覆盖层水印：在每个页面绘制半透明文本/图像
图像叠加水印：将水印作为图层叠加在PDF内容上

需要注意PDF的层结构特性，不同内容的绘制顺序会影响最终显示效果。

三、环境准备

1. 依赖库选择

推荐使用以下技术栈：

iText：用于PDF的创建和内容绘制（推荐版本：7.1.14）
Flying Saucer：用于HTML转PDF（推荐版本：1.5.3）
wkhtmltopdf：基于WebKit的命令行工具（推荐版本：0.12.6）

Maven依赖配置：

<dependencies>
    <dependency>
        <groupId>com.itextpdf</groupId>
        <artifactId>itextpdf</artifactId>
        <version>7.1.14</version>
    </dependency>
    <dependency>
        <groupId>org.xhtmlrenderer</groupId>
        <artifactId>flying-saucer-pdf</artifactId>
        <version>1.5.3</version>
    </dependency>
</dependencies>

2. 环境配置

对于wkhtmltopdf，需要在服务器上安装：

# Ubuntu/Debian
sudo apt-get install wkhtmltopdf

# Windows
# 下载安装包：https://wkhtmltopdf.org/downloads.html

四、核心实现

1. 基础HTML转PDF

使用Flying Saucer库实现HTML转PDF：

public class HtmlToPdfConverter {
    public static byte[] convertHtmlToPdf(String htmlContent) throws Exception {
        ITextRenderer renderer = new ITextRenderer();
        renderer.setDocumentFromString(htmlContent);
        renderer.layout();
        
        ByteArrayOutputStream os = new ByteArrayOutputStream();
        renderer.getPDFDocument().save(os);
        return os.toByteArray();
    }
}

关键代码解释：

setDocumentFromString：将HTML内容解析为文档
layout()：执行布局计算
save()：生成PDF二进制数据

2. 基础水印添加

使用iText在PDF上添加水印：

public class WatermarkPdfGenerator {
    public static byte[] addWatermarkToPdf(byte[] pdfBytes, String watermarkText) throws Exception {
        PdfReader reader = new PdfReader(pdfBytes);
        PdfStamper stamper = new PdfStamper(reader, new ByteArrayOutputStream());
        
        int pages = reader.getNumberOfPages();
        BaseFont baseFont = BaseFont.createFont();
        
        for (int i = 1; i <= pages; i++) {
            PdfContentByte content = stamper.getUnderContent(i);
            content.beginText();
            content.setRGBColorFill(128, 128, 128);
            content.showTextAligned(
                BaseFont.ITALIC,
                watermarkText,
                360, 700,
                45,
                baseFont
            );
            content.endText();
        }
        
        stamper.close();
        return stamper.getOutputStream().toByteArray();
    }
}

关键代码解释：

getUnderContent：在页面内容下层绘制水印
setRGBColorFill：设置半透明灰色
showTextAligned：精确控制水印位置和角度

3. 综合方案实现

整合HTML转PDF和水印添加：

public class HtmlToPdfWithWatermark {
    public static byte[] generatePdfWithWatermark(String htmlContent, String watermarkText) 
        throws Exception {
        
        // 1. 转换HTML为PDF
        byte[] pdfBytes = HtmlToPdfConverter.convertHtmlToPdf(htmlContent);
        
        // 2. 添加水印
        byte[] finalPdfBytes = WatermarkPdfGenerator.addWatermarkToPdf(pdfBytes, watermarkText);
        
        return finalPdfBytes;
    }
}

五、完整案例

1. 前端HTML模板（Thymeleaf示例）

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>PDF生成示例</title>
    <style>
        body { font-family: Arial, sans-serif; }
        .section { margin-bottom: 40px; }
        .section h2 { color: #333; }
    </style>
</head>
<body>
    <div class="section">
        <h2>用户信息</h2>
        <p>姓名：[[${user.name}]]</p>
        <p>邮箱：[[${user.email}]]</p>
    </div>
    <div class="section">
        <h2>订单详情</h2>
        <ul>
            <li th:each="item : ${user.orders}">
                [[${item.product}]] - [[${item.quantity}]]
            </li>
        </ul>
    </div>
</body>
</html>

2. 后端生成PDF接口（Spring Boot示例）

@RestController
public class PdfController {
    @PostMapping("/generate-pdf")
    public ResponseEntity<byte[]> generatePdf(@RequestParam String htmlContent) {
        try {
            // 1. 生成PDF
            byte[] pdfBytes = HtmlToPdfWithWatermark.generatePdfWithWatermark(htmlContent, "Confidential");
            
            // 2. 设置响应头
            HttpHeaders headers = new HttpHeaders();
            headers.setContentType(MediaType.APPLICATION_PDF);
            headers.setContentDispositionFormData("attachment", "document.pdf");
            
            return new ResponseEntity<>(pdfBytes, headers, HttpStatus.OK);
        } catch (Exception e) {
            return new ResponseEntity<>(HttpStatus.INTERNAL_SERVER_ERROR);
        }
    }
}

3. 接口调用示例（Postman）

请求方式：POST
请求地址：http://localhost:8080/generate-pdf
请求体：JSON格式的HTML内容

六、源码解析

1. Flying Saucer的渲染流程

Flying Saucer内部使用了Apache FOP的布局引擎，其核心流程包括：

CSS解析：通过CSSOM解析样式信息
布局计算：基于CSS2.1规范计算元素位置
PDF生成：将布局结果转换为PDF的图形指令

关键代码片段：

// 布局计算
renderer.layout();

// 生成PDF
renderer.getPDFDocument().save(os);

2. iText的PDF绘制机制

iText的PDF绘制分为三个层级：

Page Content：页面内容绘制
Page Content Under：页面底层内容
Page Content Over：页面上层内容

水印的绘制需要使用getUnderContent()方法确保在内容下层显示。

七、进阶使用

1. 动态水印生成

根据用户角色生成不同水印：

public static byte[] addDynamicWatermarkToPdf(byte[] pdfBytes, String userRole) 
    throws Exception {
    
    PdfReader reader = new PdfReader(pdfBytes);
    PdfStamper stamper = new PdfStamper(reader, new ByteArrayOutputStream());
    
    for (int i = 1; i <= reader.getNumberOfPages(); i++) {
        PdfContentByte content = stamper.getUnderContent(i);
        String watermarkText = userRole.equals("admin") ? "Admin Preview" : "User Preview";
        content.beginText();
        content.setRGBColorFill(128, 128, 128);
        content.showTextAligned(
            BaseFont.ITALIC,
            watermarkText,
            360, 700,
            45,
            BaseFont.createFont()
        );
        content.endText();
    }
    
    stamper.close();
    return stamper.getOutputStream().toByteArray();
}

2. 多图层水印叠加

支持文本+图像的水印组合：

public static byte[] addMultiLayerWatermarkToPdf(byte[] pdfBytes, String text, byte[] imageBytes) 
    throws Exception {
    
    PdfReader reader = new PdfReader(pdfBytes);
    PdfStamper stamper = new PdfStamper(reader, new ByteArrayOutputStream());
    
    for (int i = 1; i <= reader.getNumberOfPages(); i++) {
        PdfContentByte content = stamper.getUnderContent(i);
        
        // 添加文本水印
        content.beginText();
        content.setRGBColorFill(128, 128, 128);
        content.showTextAligned(
            BaseFont.ITALIC,
            text,
            360, 700,
            45,
            BaseFont.createFont()
        );
        content.endText();
        
        // 添加图像水印
        BufferedImage image = ImageIO.read(new ByteArrayInputStream(imageBytes));
        content.addImage(
            Image.getInstance(image, BaseFont.CP1252, false)
        );
    }
    
    stamper.close();
    return stamper.getOutputStream().toByteArray();
}

八、性能与工程实践

1. 性能优化策略

缓存机制：对相同内容的PDF生成结果进行缓存
异步处理：将PDF生成任务放入消息队列处理
资源释放：及时关闭PDF读取/写入流
字体优化：预加载常用字体库

2. 异常处理方案

资源泄漏处理：确保所有PDF流在异常时正确关闭
超时控制：为PDF生成设置合理的时间限制
错误日志：记录详细的错误信息和堆栈跟踪

3. 安全防护措施

XSS过滤：对用户输入的HTML内容进行转义处理
PDF安全模式：禁用PDF的可编辑功能
内容验证：限制PDF生成的内容长度和复杂度

九、常见问题与踩坑

1. 常见错误及解决办法

错误现象	原因	解决方案
PDF空白	布局计算未执行	确保调用`renderer.layout()`
水印覆盖内容	绘制顺序错误	使用`getUnderContent()`
字体缺失	字体未注册	使用`BaseFont.createFont()`
PDF格式错误	未正确关闭流	确保使用try-with-resources
水印位置错误	坐标计算错误	使用`showTextAligned()`方法

2. 常见性能问题

大文档生成缓慢：使用PdfStamper的setAllOccurrences方法
内存溢出：限制PDF生成的最大页面数
并发处理问题：使用线程池控制并发数

十、最佳实践

1. 推荐方案选择

场景	推荐方案	说明
简单静态文档	Flying Saucer	易于使用，适合小型项目
复杂布局文档	iText	功能强大，适合复杂需求
高并发场景	wkhtmltopdf	通过外部进程处理，避免内存占用

2. 实现建议

预处理HTML：对用户输入的HTML进行清理和转义
分页控制：根据内容自动分页，避免大页面
版本控制：使用PDF/A格式确保长期可读性
安全策略：禁用PDF的可编辑和可打印功能

十一、总结

HTML转PDF和添加水印是Web应用中常见的功能需求，但其技术实现涉及多个复杂环节。本文深入探讨了该技术的实现原理，从HTML解析到PDF生成，从水印绘制到安全防护，提供了完整的解决方案。

在实际开发中，需要根据具体场景选择合适的实现方案。对于简单需求，Flying Saucer是轻量级的首选；对于复杂需求，iText提供了更灵活的控制；而对于需要高性能的场景，wkhtmltopdf则是值得考虑的替代方案。

需要注意的是，该技术存在一些潜在风险，如安全漏洞、性能瓶颈和格式兼容性问题。开发人员需要根据具体需求进行相应的优化和防护。通过合理的架构设计和规范的代码实现，可以有效地解决这些问题，确保系统稳定运行。

JAVA HTML 转 PDF和增加水印