iText接口API实战：PDF生成、生僻字与暗坑排查全解析

iText 这个库，在 Java 生态里摸爬滚打的程序员基本都绕不开。它的接口 API 覆盖面极广，从最简单的 PDF 生成，到复杂动态报表、电子签章，再到和 Flying Saucer 配合做 HTML 转 PDF，几乎所有“想把内容变成 PDF”的需求都能找到对应入口。这篇文章就结合我实际项目里踩过的坑，把 iText 接口 API 的关键用法、生僻字处理、暗坑排查一次讲透，适合刚接手 PDF 功能的开发同学，也适合已经在用但被乱码、分页折腾过的老手。

1. iText接口API是什么：先搞明白它能干嘛

1.1 一个PDF库能解决什么问题

iText 是一套用于生成和操作 PDF 文档的 Java 库，对外暴露的是一系列操作文档对象、内容元素、字体、图形、注解的接口 API。简单说，你在 Word 里做的事情——写字、画表格、插图片、设页眉页脚、搞目录——iText 都能用代码实现，而且是精确到坐标级别的控制。它不是“把 HTML 截个图”那种偏门方案，而是真正在 PDF 内部构建内容结构，生成的文档体积小、可检索、适合长期归档。

我最早接触 iText，是做一个电子合同项目。合同有固定模板，但是金额、日期、甲乙双方信息需要动态替换。用 iText 接口 API 可以直接在指定位置绘制文本和线条，比先生成 Word 再转 PDF 轻太多。后面又遇到过要批量导出上万份对账单、用 Flying Saucer 把前端写好的 HTML 报告转成 PDF 的场景，iText 都能稳稳接住。

适合谁来学？只要你需要在 Java 服务端生成 PDF，或者需要把 PDF 拆页、合并、加密、填表单，iText 就是绕不开的基础工具。前端也可以了解它的接口设计思路，很多 PDF 需求最终落到服务端都是这套逻辑。

1.2 iText5和iText7怎么选

这是新手问得最多的一个问题。iText 目前主流是 iText 5 和 iText 7 两个大版本，它俩的包名、API 风格差别很大。iText 5 的代码通常长这样：

java复制Document document = new Document();
PdfWriter.getInstance(document, new FileOutputStream("hello.pdf"));
document.open();
document.add(new Paragraph("Hello World"));
document.close();

iText 7 则是这样的：

java复制PdfWriter writer = new PdfWriter("hello.pdf");
PdfDocument pdf = new PdfDocument(writer);
Document document = new Document(pdf);
document.add(new Paragraph("Hello World"));
document.close();

包名从 com.itextpdf.text.* 变成了 com.itextpdf.kernel.*、com.itextpdf.layout.*。如果是从 iText 5 升级到 iText 7，基本等于重写一遍业务代码。我的建议很简单：新项目直接上 iText 7，生态和后续更新都在往 7 上靠。老项目维护就别强行升了，稳定压倒一切。

iText 7 的设计更贴近“对象组合”思路：PdfDocument 代表底层的 PDF 文档对象，Document 是面向排版的高级容器，Paragraph、Table 是内容元素，PdfFont 负责字体。分层更清晰，扩展时不容易改一处崩一片。

要注意许可问题，iText 是 AGPL 协议，商用闭源项目想要避开开源传染，需要买商业授权。这个属于法务范畴，但作为开发者心里要有数，别等代码写完了才发现授权堵路。

1.3 对比其他PDF生成方案

Java 世界里 PDF 方案不少，除了 iText，还有 Apache PDFBox、OpenPDF（iText 5 的分支）、以及晚近流行的 Html2Pdf、wkhtmltopdf、Chromium 无头浏览器打印等。如果项目里已经有人用了某一种，别急着替换，先看应用场景。

• PDFBox：更偏向 PDF 文档的低层操作，适合做表单填写、文本抽取、文档合并，但排版能力弱，写一段漂亮的段落和表格要写很多代码。
• OpenPDF：API 和 iText 5 很接近，胜在开源许可友好（LGPL/MPL），适合对 AGPL 敏感的项目。缺点是更新节奏一般。
• wkhtmltopdf / Chromium 打印：适合“前端页面转 PDF”，排版能力强，但依赖系统服务和浏览器内核，部署环境比较重，高并发下资源占用也大。
• iText + Flying Saucer：可以做到“HTML/CSS 精美排版 + 服务端精准控制”，比较适合报表、票据、合同这类对版式有要求的场景。

iText 真正的优势是接口 API 完整，从底层 IO 到顶层布局都有官方支持，操作空间大。缺点也明显：API 庞杂，很多方法名相似但行为不同，不踩几次坑记不住。

2. 上手实操：用iText接口API生成第一个PDF

2.1 引入依赖与中文字体准备

我以