Spring Boot 整合 x-easypdf：5 分钟搞定 PDF 生成与中文排版
摘要：在 Java 开发中，生成 PDF 文档常面临中文乱码、排版困难、依赖库收费等痛点。本文推荐一款基于 PDFBox 深度封装的国产开源神器 —— x-easypdf。它内置中文字体，API 简洁易用，支持组件化开发。本文将通过一个“企业录用通知书生成器”的实战 Demo，带你体验 5 分钟快速实现 PDF 生成的全过程。
声明：本文内容基于 x-easypdf v3.5.5 版本编写，仅代表个人使用心得。如需最新 API 文档及技术支持，请以 x-easypdf 官网 为准。本文代码仅供学习参考，生产环境请根据实际需求调整。
作为一名 Java 程序员，你是否曾被 PDF 生成的需求折磨得痛不欲生？
- 坐标计算繁琐，调整一个表格的边距要重启项目十几次。
- 中文乱码问题像幽灵一样，本地好了，服务器上又挂了。
- 官方文档晦涩难懂，API 复杂得像在解微积分。
如果你也有这些痛点，那么今天我要推荐的这款开源神器 —— x-easypdf，绝对能拯救你的发际线。
为什么要选择 x-easypdf？
在 Java 生态中，生成 PDF 通常有几种选择：iText、PDFBox、JasperReports 等。但它们要么收费（iText），要么过于底层（PDFBox），要么配置繁琐（JasperReports）。
x-easypdf 的出现，填补了“简单易用”与“功能强大”之间的空白。
核心优势
- 极简 API 设计：基于 PDFBox 深度封装，无需关注底层坐标和流操作，全部采用声明式组件调用。
- 天然支持中文：内置华为鸿蒙字体等中文字体，彻底告别中文乱码和字体缺失的烦恼，开箱即用。
- 丰富组件：内置文本域、表格、图像、条形码、二维码等常用组件，满足 99% 的业务需求。
- 完全开源免费：基于 MulanPSL2 协议（兼容 Apache 2.0），个人和企业均可免费使用。
适合场景与人群
适合人群：
- 需要快速上线 PDF 功能的 Java 后端开发。
- 厌倦了计算坐标和调试样式的全栈开发。
典型场景：
- 电子合同/协议：动态填充用户信息，生成法律效力的文档。
- 发票/收据：格式固定，内容动态的票据生成。
- 报表导出：将数据以图文并茂的形式导出为 PDF。
- 录用通知书 (Offer Letter)：HR 系统自动生成个性化 Offer。
与其他框架对比
| 特性 | PDFBox (原生) | iText 7 | x-easypdf |
|---|---|---|---|
| 上手难度 | 高 (需懂 PDF 规范) | 中 | 极低 (组件化) |
| 中文支持 | 需手动加载字体 | 需额外配置 | 内置支持 |
| API 风格 | 绘图式 (坐标) | 声明式 | 声明式 + 链式 |
| 开源协议 | Apache 2.0 | AGPL/商业授权 | MulanPSL2 (友好) |
| 表格支持 | 极难实现 | 强大 | 简单易用 |
实战演示：5 分钟实现“录用通知书”生成器
为了让你直观感受它的强大，我写了一个简单的 Demo。这是一个录用通知书生成器，前端输入信息，后端实时生成 PDF 下载。
1. 引入依赖 (Maven)
在你的 Spring Boot 3 项目的 pom.xml 中加入以下依赖。注意我们使用的是基于 PDFBox 的模块，版本为 3.5.5。
<!-- x-easypdf pdfbox 模块 -->
<dependency>
<groupId>org.dromara</groupId>
<artifactId>x-easypdf-pdfbox</artifactId>
<version>3.5.5</version>
</dependency>
2. 核心代码实现
看看生成一个包含标题和正文的 PDF 有多简单。你不需要计算 (x, y) 坐标，只需要告诉它“居中”、“字号”即可。
package com.ttk.demo.service.impl;
import com.ttk.demo.dto.OfferRequest;
import com.ttk.demo.service.PdfService;
import org.dromara.pdf.pdfbox.core.base.Document;
import org.dromara.pdf.pdfbox.core.base.Page;
import org.dromara.pdf.pdfbox.core.component.Textarea;
import org.dromara.pdf.pdfbox.core.enums.HorizontalAlignment;
import org.dromara.pdf.pdfbox.handler.PdfHandler;
import org.springframework.stereotype.Service;
import java.awt.Color;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
@Service
public class PdfServiceImpl implements PdfService {
@Override
public byte[] generateOfferPdf(OfferRequest request) {
try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
// 1. 创建文档并设置字体 (内置微软雅黑/鸿蒙字体，直接支持中文)
Document document = PdfHandler.getDocumentHandler().create();
document.setFontName("微软雅黑");
// 2. 创建页面
Page page = new Page(document);
// 3. 创建标题组件
Textarea title = new Textarea(page);
title.setText("录用通知书");
title.setFontSize(30F);
title.setFontColor(Color.DARK_GRAY);
// 水平居中，无需计算页面宽度
title.setHorizontalAlignment(HorizontalAlignment.CENTER);
title.setMarginTop(50F);
title.render();
// 4. 创建正文组件 (自动换行)
String bodyText = String.format("亲爱的 %s：\n\n" +
"我们非常高兴地通知您，您已被录用为我们公司的 %s。\n" +
"您的起薪为 %s。\n" +
"我们期待您在 %s 入职。\n\n" +
"诚挚地，\n" +
"人力资源部",
request.getName(), request.getPosition(), request.getSalary(), request.getDate());
Textarea body = new Textarea(page);
body.setText(bodyText);
body.setFontSize(14F);
body.setMarginTop(150F);
body.setMarginLeft(50F);
body.setMarginRight(50F); // 设置右边距，防止文字超出
body.setLeading(25F); // 设置行间距，增加可读性
body.render();
// 5. 添加页面并保存
document.appendPage(page);
document.save(outputStream);
document.close();
return outputStream.toByteArray();
} catch (IOException e) {
throw new RuntimeException("生成 PDF 失败", e);
}
}
}
3. 效果展示
前端页面简洁干练，输入信息后点击下载，一份排版精美的 PDF 就生成好了。
总结
x-easypdf 真正做到了“把复杂留给自己，把简单留给用户”。如果你正在寻找一个轻量级、高性能且对中文友好的 Java PDF 解决方案，它绝对是目前的不二之选。
赶紧去 官网 体验一下吧，相信你会爱上它的！
