Spring Boot 整合 x-easypdf：5 分钟搞定 PDF 生成与中文排版

原创

天天困

发布于 2026-01-12 18:21:05

3790

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，绝对能拯救你的发际线。

官网地址：https://x-easypdf.cn/

为什么要选择 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);
        }
    }
}