Spring Boot中使用x-easypdf快速生成中文PDF报表

1. 项目背景与核心价值

在Java企业级开发中，PDF生成是常见的业务需求。传统方案如iText虽然功能强大，但存在API复杂、中文支持差、学习曲线陡峭等问题。x-easypdf作为国产开源PDF工具库，凭借其简洁的链式API和原生中文支持，正在成为Spring Boot开发者的新选择。

我最近在一个电商后台项目中实测发现：从引入依赖到生成带复杂中文排版的PDF报表，完整流程仅需5分钟。相比之下，传统方案仅解决中文乱码问题就需要额外30分钟配置。下面分享这套高效方案的完整实现过程。

2. 环境准备与基础配置

2.1 依赖引入要点

在pom.xml中添加以下关键依赖（Spring Boot 2.7.x示例）：

xml复制<dependency>
    <groupId>wiki.xsx</groupId>
    <artifactId>x-easypdf-boot-starter</artifactId>
    <version>2.3.1</version>
</dependency>

注意：必须排除默认的itext版本，避免与x-easypdf内置的itext冲突：

xml复制<exclusions>
    <exclusion>
        <groupId>com.itextpdf</groupId>
        <artifactId>itextpdf</artifactId>
    </exclusion>
</exclusions>

2.2 字体配置最佳实践

在resources目录下创建fonts文件夹，存放中文字体（如思源黑体）：

code复制src/main/resources/fonts/SourceHanSansCN-Regular.ttf

通过application.yml配置全局字体：

yaml复制x-easypdf:
  font:
    mapping:
      default: classpath:fonts/SourceHanSansCN-Regular.ttf
      bold: classpath:fonts/SourceHanSansCN-Bold.ttf

3. 核心API实战解析

3.1 基础文档生成

创建包含标题和段落的基础PDF：

java复制public void generateSimplePdf() throws IOException {
    XEasyPdfDocument document = XEasyPdfHandler.Document.build()
        .addPage(
            XEasyPdfHandler.Page.build()
                .addComponent(
                    XEasyPdfHandler.Text.build("订单明细报表")
                        .setFontSize(20)
                        .setBold(true)
                        .setMarginBottom(20)
                )
                .addComponent(
                    XEasyPdfHandler.Text.build("生成时间：" + LocalDateTime.now())
                        .setFontSize(12)
                )
        );
    document.save("simple.pdf");
}

3.2 复杂中文排版技巧

实现混合样式的段落文本：

java复制XEasyPdfHandler.Text.build()
    .addText("重要提示：", text -> text.setBold(true).setFontColor(Color.RED))
    .addText("本订单包含", text -> text.setFontSize(12))
    .addText("3件限时特惠商品", text -> text.setUnderline(true))
    .addText("，请优先处理。", text -> text.setItalic(true))
    .setLineSpacing(1.5f)
    .setFirstLineIndent(24);

3.3 表格数据导出实战

生成带中文表头的商品表格：

java复制XEasyPdfHandler.Table.build()
    .setWidth(500)
    .addRow(
        XEasyPdfHandler.Table.Row.build()
            .addCell("商品名称", cell -> cell.setBold(true).setBackgroundColor(Color.LIGHT_GRAY))
            .addCell("单价", cell -> cell.setBold(true))
            .addCell("数量", cell -> cell.setBold(true))
    )
    .addRow(
        XEasyPdfHandler.Table.Row.build()
            .addCell("无线蓝牙耳机")
            .addCell("¥299.00")
            .addCell("2")
    );

4. 高级功能实现

4.1 页眉页脚与页码

添加企业LOGO和动态页码：

java复制XEasyPdfHandler.Page.build()
    .setHeader(header -> header
        .addImage("classpath:images/logo.png", 100, 30)
        .addText("机密文档", text -> text.setFontSize(10))
    )
    .setFooter(footer -> footer
        .addPageNumber("第", "页", number -> number
            .setFontSize(10)
            .setHorizontalAlignment(Center)
        )
    );

4.2 PDF模板套打方案

基于现有PDF表单填充数据：

java复制XEasyPdfHandler.Form.build("template.pdf")
    .fillField("customerName", "张三")
    .fillField("orderNo", "20230815001")
    .save("filled_form.pdf");

5. 性能优化与问题排查

5.1 内存控制方案

处理大批量数据时采用分页生成：

java复制// 每100条数据生成一个PDF分片
List<Order> orders = getLargeOrderList();
for (int i = 0; i < orders.size(); i += 100) {
    List<Order> batch = orders.subList(i, Math.min(i + 100, orders.size()));
    generatePdfBatch("order_part_" + (i/100+1) + ".pdf", batch);
}

5.2 常见问题速查表

6. 实际项目经验分享

在电商订单导出功能中，我们遇到PDF生成速度随数据量增加明显下降的问题。通过以下优化使生成时间从15秒降至3秒：

1. 字体缓存：初始化时预加载字体

java复制@PostConstruct
public void initFont() {
    XEasyPdfHandler.Font.load("classpath:fonts/SourceHanSansCN-Regular.ttf");
}

2. 关闭冗余日志：在logback.xml中增加

xml复制<logger name="wiki.xsx.easypdf" level="WARN"/>

3. 使用BufferedOutputStream替代FileOutputStream：

java复制try (BufferedOutputStream out = new BufferedOutputStream(new FileOutputStream(file))) {
    document.save(out);
}