iText7实战指南：Java后端PDF生成、合并、表单与水印处理全解

写句实话PDF操作iText7实战指南这个系列我能写到第119篇不是因为PDF有多难而是因为PDF场景太碎了。搜索栏里天天有人搜“PDF合并免费软件”“PDF转Word”“PDF编辑器”可这些需求一到工程师手里就变成了完全不同的问题要不要保持原有页面结构是否保留书签表单字段要不要扁平化转出来的Word能不能被业务系统自动读取。每一层都要单独处理。这篇文章我不打算只贴一个hello world而是把项目里反复出现的真实场景串起来讲生成带中文的PDF报表、从已有PDF里提取文本、合并拆分文件、批量填表单、加水印、设置打印页面。这些能力全部基于iText7我会把代码、思路、踩坑记录都放出来。如果你是后端Java开发、做过报表系统或者正在搭文档中心这篇文章适合直接抄作业。1. 项目概述与整体思路1.1 这个系列到底在解决什么很多团队一遇到PDF问题第一反应是让员工用办公软件手工处理。但凡是数量一多手工方案一定出问题。比如运营每天要导出一批合同每个合同PDF里需要填批注、盖水印、再合并成一个附件财务系统要按账单周期生成对账单PDFHR要批量从一个几百页的薪资说明里提取关键字段。这些场景背后都有一个共同点PDF不是给人看的而是给系统跑批用的。iText7就是为这些场景准备的工具。它有非常成熟的页面对象模型能处理文档的树形结构支持对每个PdfPage做细粒度控制。和PDFBox相比它的写入能力、表单处理、签名加密、字体嵌入体系更完整和OpenPDF相比它还在持续维护新版本也有官方模块化路线。虽然iText7的AGPL许可要求商用项目购买商业许可但在功能表现上它仍然是Java生态里PDF操作的头部选手。1.2 为什么选iText7而不是别的库选型这件事我吃过不少亏。PDFBox读取文本能力强页面渲染也有一定支持但它要写入一段排版良好的中文文档需要自己动手拼坐标开发效率很低。OpenPDF是从老版本iText分叉出来的轻量但维护节奏偏慢复杂一点的水印、加密、数字签名支持并不可靠。iText7的优势在于模块化设计和对文档对象模型的控制力从页面、画布、字体到内容流都能操作同时表单和签名的API接口非常稳定。当然世上没有免费午餐。iText7的AGPL许可证意味着如果你要把系统商业化或对外提供SaaS服务需要购买商业许可。技术能力是一回事合规是另一回事我在自己的项目里只关注前者商业上的事情交给公司决策。如果纯内部使用AGPL带来的额外义务少一些但也要看清楚条件。整体来看在Java生态里iText7仍然是做PDF批量业务最省心的方案。1.3 项目结构怎么规划才不踩坑由于代码需要长期维护把PDF操作散落在Service里是一种灾难。比如某天要调水印发现五个地方各写了一遍PdfCanvas样式还不统一改起来想死的心都有。我在项目里的做法是三层结构基础层统一封装PdfWriter与PdfDocument生命周期用try-with-resources保证流关闭。操作层把生成表格、添加水印、设置页面、追加书签等动作抽成独立工具类例如PdfStampUtil.forceWatermark。业务层只关心数据模型比如订单、合同、账单调用操作层组合文档。这样设计之后最常见的收益是改字体、加LOGO、调页边距时只动操作层业务代码不用碰。另外测试也好写因为操作层收口的都是小函数输入输出都很清晰。2. 环境准备与依赖处理2.1 Maven依赖怎么配iText7和iText5最直观的差别就是产物不同。iText7把所有能力打成一个个模块核心模块包括kernel、io、layout、forms、pdfa、svg等。如果图省事直接引入itext7-core聚合模块它以POM类型把一堆模块带进来。可以这么写dependency groupIdcom.itextpdf/groupId artifactIditext7-core/artifactId version7.2.5/version typepom/type /dependency这个写法最大的好处是不会漏模块。比如需要处理PDF表单时很多人忘了引入forms模块结果类名报错折腾半天发现只是依赖没加。不过要注意itext7-core会把不需要的模块也带进来对体积敏感的微服务可以只引入kernel、io、layout、forms四个模块再按需补font-asian、pdfhtml。这里还有一个经验版本不要追太高。iText7的API在小版本之间偶有微调比如某些FontFactory枚举改名、PdfMerger被标记过时跟着最热版本走容易让代码在半年后变得不可控。项目里固定一个已验证版本升级前用测试用例跑一遍核心路径。2.2 中文与字体是第一个拦路虎写PDF绕不开中文字体。iText7里如果不指定PdfFont直接用Paragraph添加中文输出的PDF很可能全是方块或者空白。常见做法有两种。第一种用iText7自带的亚洲字体支持包PdfFont cnFont PdfFontFactory.createFont(STSongStd-Light, UniGB-UCS2-H);这种方式零成本编码正确文字能正常显示缺点是字形是固定的宋体风格而且嵌入字体时可控性一般。第二种使用业务自己携带的TTF/OTF文件。我推荐这种方式尤其是要统一品牌形象的时候。把字体文件放在classpath下用PdfFontFactory.createFont(fonts/NotoSansCJKsc-Regular.otf)再通过Paragraph.setFont指定。多语言混排时可以创建两个PdfFont让中文走CJK字体英文走Helvetica这样打印效果干净得多。注意判断中文乱码类问题先看字体有没有加载成功再看文本流的编码最后才是页面渲染。我见过最坑的一次是字体文件被Maven打包成了乱码路径本地能跑服务器上一跑就抛FileNotFoundException。2.3 许可协议和版本演进老读者可能还记得iText5时代代码习惯是Document加PdfWriter.getInstance。iText7里这一切都被重新组织了PdfWriter负责写流PdfReader负责读流PdfDocument负责管理文档Document是辅助布局的高层入口。如果你在网上找到5.x教程看到的是PdfWriter.getInstance那基本不能直接用。许可证也要专门说明。iText采用AGPL协议在线服务和一些分发场景需要把衍生代码开源供用户获取很多企业内部系统或者SaaS平台实际上需要商业授权。这里不做法律解释只提醒一点越早找公司确认许可状态越好别让法务在项目上线前突然找上门。选型阶段把风险想清楚后面能省很多心。3. 生成PDF从空白页到像样的文档3.1 最小可运行示例先写一个能跑起来的最小示例。这个例子会生成一个A4页面输出一行中文try (PdfWriter writer new PdfWriter(output/hello.pdf); PdfDocument pdf new PdfDocument(writer); Document doc new Document(pdf, PageSize.A4)) { PdfFont cnFont PdfFontFactory.createFont(STSongStd-Light, UniGB-UCS2-H); Paragraph p new Paragraph(你好iText7) .setFont(cnFont) .setFontSize(16); doc.add(p); }三行构造器的顺序很关键writer先建立输出流pdf持有文档上下文Document负责排版。用try-with-resources可以保证所有流正常关闭千万别在finally里自己调close那会破坏iText7已经处理好的资源释放顺序。运行以后会得到一个hello.pdf打开能看到中文这就是整套体系的基石。后面所有复杂页面都是在这个上下文里不断doc.add各种Element。理解这一点比背API重要。3.2 段落、字体、颜色与页面设置看iText7的代码很多时候感觉不像写PDF更像写HTML。Paragraph就是段落Text是文字片段setTextAlignment控制对齐setBackgroundColor控制背景Table负责表格。这种设计大大降低入门门槛。页面设置方面我建议固定使用PageSize.A4而不是直接new PdfDocument因为很多打印机默认就是A4。想留白边可以在new Document的时候传入MarginsDocument doc new Document(pdf, PageSize.A4, 40f, 40f, 60f, 60f);上边距留大一些方便放页眉。边距一旦确定后续的页眉页脚事件都要按同一个值计算别来回改动不然页码会跑到文字上。颜色设置上可以用ColorConstants里的常量也可以用CMYK模式。CMYK模式适合印刷场景屏幕预览会显得略暗但上印刷机更稳。如果只是打印普通报表直接用RGB就行。3.3 表格、图片和自动换行表格是业务报表里最常用的元素。iText7的Table可以按列宽的比例创建Table table new Table(new float[]{1.5f, 3f, 2f}); table.addCell(订单号); table.addCell(客户名称); table.addCell(金额); for (Order order : orders) { table.addCell(order.getOrderNo()); table.addCell(order.getCustomerName()); table.addCell(order.getAmount()); } doc.add(table);如果你不想让表头在分页时被拆散可以设置table.setHeaderRowCount(1);这个属性太容易被忽略但客户对分页表格的要求往往就卡在这一行。金额列建议右对齐数字不容易变形。图片用ImageDataFactory.create传入文件路径再配合scaleToFit控制大小否则一张大图直接撑爆页面。自动换行的坑主要在长字符串上。中文本身还好如果夹杂很长的URL或订单号需要设置单元格的固定宽度并且让文本自动断开。没有万能开关只能在业务侧做换行处理必要时用Text加换行符拼接。3.4 页眉页脚页码要给每一页自动加页码必须用页面事件在每次页面创建结束后回调。iText7里对应的抽象类是PdfPageEventHelper重写onPageEnd在这里拿当前PdfPagenew PdfCanvas把页码文字画到底部。这个方案最大的好处是不需要在业务代码里关心总页数事件驱动天然知道当前页。页眉同理。事件里绘制页眉时要额外注意字体建议直接复用创建文档时生成的中文PdfFont不要每次new。我踩过的一个坑是在事件里用了新字体对象结果生成300页文档后进程堆了好几百个字体实例内存直接涨上去。字体对象在PdfFontFactory里最好全局缓存一份。页码格式我习惯写“第 X 页 / 共 Y 页”。总页数在onPageEnd阶段不容易获取可以先把占位符加进去在closeDocument事件里统一替换文字内容。这个替换动作会操作内容流稍微繁琐但对客户体验提升非常明显。4. PDF解析与内容提取4.1 文件级信息读取有相当多需求不是生成PDF而是读取已有PDF。用iText7读取文件名参数换成new PdfReader模式自动变成读模式。可以拿到页面总数、文档标题、作者、创建时间、页面大小等元信息。try (PdfDocument pdf new PdfDocument(new PdfReader(source.pdf))) { int pageCount pdf.getNumberOfPages(); PdfPage firstPage pdf.getFirstPage(); Rectangle pageSize firstPage.getPageSize(); }这类信息通常用来做任务编排比如先判断页数和版本是否合法再决定是否继续处理。千万别在一个读流程里既想读又想写如果想要原地修改必须读和写同时成立new PdfDocument(new PdfReader(src), new PdfWriter(dst))。4.2 按页提取文本提取文本用的API是PdfTextExtractortry (PdfDocument pdf new PdfDocument(new PdfReader(report.pdf))) { for (int i 1; i pdf.getNumberOfPages(); i) { String text PdfTextExtractor.getTextFromPage(pdf.getPage(i)); System.out.println(text); } }默认的提取策略会把文本按照内容流读取但保留的换行、空格可能和视觉呈现不一致。刚接触的人会奇怪明明页面上是一行居中标题提取出来全是分散的词。这是PDF本身决定的文字在页面上的位置是坐标不是结构化的DOM顺序。如果你需要更稳的提取可以传SimpleTextExtractionStrategy参数。对于多列文本要按坐标去重排序这已经超出iText7默认能力了需要自己解析TextRenderInfo坐标。我的经验是提取纯文本用于检索、展示摘要没问题用于数据入库就要对每类文档写解析规则。4.3 表格数据提取的局限“PDF解析成Excel”是需求重灾区。我的结论先说清楚iText7不提供开箱即用的表格还原。它会告诉你每个字符的坐标、字号、所在页面你要自己做坐标聚类判断哪些字符属于同一列、同一行。遇到带边框的表格还好但遇到没有边线的排版表格插值难度陡增。可靠的做法是如果业务有原始Excel或数据库就从源头结构化导出拿PDF反推是下策。PDF只适合做展示归档不适合当数据结构。真到了必须从PDF拿数据的场景我会先用iText7把文本和坐标导出来再用规则引擎匹配保证可用率。这样至少比让业务人员手工复制粘贴强得多。5. 合并、拆分、水印、书签5.1 合并多个PDF合并PDF这个需求太普遍了。运营人员收集了一堆附件最终要合成一个PDF给客户。在iText7里合并可以用copyPagesTotry (PdfDocument outPdf new PdfDocument(new PdfWriter(merged.pdf))) { for (String file : fileList) { try (PdfDocument src new PdfDocument(new PdfReader(file))) { src.copyPagesTo(1, src.getNumberOfPages(), outPdf); } } }这段代码的精髓是从源文档逐页复制到目标文档而不是构建一个新页面再重新渲染。所以合并后的PDF仍然保持原始页面的大小、字体嵌入信息和书签结构。要注意源文档的字体如果没嵌入合并后又重新分发目标机器打开可能显示异常这类问题往往要回到生产源修正。另外如果页面尺寸不一致合并后的PDF每一页可以有自己的尺寸这是合法的。但打印时容易出状况我在合并前会检查一下pageSize必要时统一裁剪框或转成同一个页面尺寸。5.2 按范围拆分拆分比合并还简单copyPagesTo的from/to换成目标范围就行。比如要把一个PDF按第3页和第10页切两段try (PdfDocument out1 new PdfDocument(new PdfWriter(part1.pdf)); PdfDocument src new PdfDocument(new PdfReader(source.pdf))) { src.copyPagesTo(1, 3, out1); }拆分后的文件字体嵌入、压缩等属性都来自原始文件一般不会出问题。但有一个细节如果原始文档里有AcroForm表单拆分后表单字段关系可能变得不一致。尽量把表单扁平化之后再拆否则一部分字段会丢失。5.3 给每一页打水印水印是合同、报价单的刚需。iText7里拿到每个PdfPage通过PdfCanvas画文字就行try (PdfDocument pdf new PdfDocument(new PdfReader(src), new PdfWriter(out))) { PdfFont font PdfFontFactory.createFont(PdfFontFactory.StandardFonts.HELVETICA_BOLD); for (int i 1; i pdf.getNumberOfPages(); i) { PdfPage page pdf.getPage(i); PdfCanvas canvas new PdfCanvas(page); canvas.beginText() .setFontAndSize(font, 48) .moveText(180, 400) .showText(CONFIDENTIAL) .endText(); } }文字水印位置固定但这只是初版。真正实用的是旋转45度、半透明、铺满整个页面的水印。旋转需要canvas.concatMatrix透明度需要setExtGState更简单的方式是先用布局层的Paragraph添加到底层Canvas然后让内容覆盖上去。水印文字一定要用嵌入字体否则发给客户后机器没有对应字体水印位置会发生偏移这问题我遇到过一次。水印能不能做成可选中文字可以但没必要。水印的作用是提醒查看者不是数据层标记。如果要防止复制应该做权限加密而不是靠水印。5.4 添加书签大纲几十页的PDF如果没有书签用户体验很糟糕。iText7通过PdfOutline操作书签先获得根大纲然后逐级添加大纲项再为每个大纲项设置目标页。书签的目标页可以是翻页位置也可以跳转到具名目的地。做完书签之后客户在阅读器左侧就能像看目录一样跳转这比翻页高效太多了。在生成新文档时建议一边写段落一边同步添加大纲不要等文档全部生成完再回补那样会出现页码目标漂移尤其是在批量生成时很难排查。6. PDF表单操作6.1 如何判断PDF有没有表单客户常会发来一份可以做模板的PDF里面有可以填写文字的输入框、下拉框、复选框。如果你用PDF编辑器打开看到高亮区域那就是AcroForm。用iText7读取时通过PdfAcroForm.getAcroForm(pdfDocument, false)判断非空然后遍历表单字段。字段名是定位的关键很多设计师在做PDF时不会规范命名字段名可能叫Text1、Text2这就需要在开发前先写个小工具打印全部字段名。判断有没有表单是写自动化填表脚本的第一步这一步做对了后面就是setValue。做错了后面就会对着一个被扁平化的文档思考人生。6.2 填写表单并扁平化填写表单本身很简单try (PdfDocument pdf new PdfDocument(new PdfReader(src), new PdfWriter(out))) { PdfAcroForm form PdfAcroForm.getAcroForm(pdf, true); form.getField(customerName).setValue(张三); form.getField(orderAmount).setValue(12800.50); form.getField(signDate).setValue(2025-03-18); form.flattenFields(); }关键点是flattenFields()。如果不调用它PDF里依然保留可编辑字段客户打开后还能修改如果调用了字段就变成普通文字内容被固定死。业务上要区分内部使用的模板可能不扁平化对外下发的合同、回执必须扁平化还要顺手设置只读属性。填表单踩过的坑集中在日期格式和文件流上。日期格式要根据需求包装有的客户要yyyy-MM-dd有的要yyyyMMdd直接在setValue前做格式化即可。文件流方面读取源PDF时必须用读写模式否则调用form.getField时会抛出“The document has not been opened for modification”之类的错误。6.3 动态生成表单除了填固定模板iText7也能通过PdfTextFormField创建新的输入框。做法是建一个文本字段指定页面和矩形坐标然后用addField加入表单。这个能力适合做那种需要用户在线填写的电子审批单。不过说实话我自己做动态表单用的更多是pdfHTML或前端资源因为复杂的表单调优成本很高。iText7的优势在于后端没有HTML引擎也能生成一个可交互表单。7. 打印、预览与前端联动场景7.1 服务端生成打印友好的PDF“PDF虚拟打印”“web页面PDF打印”这些热词说明很多人的痛点是打印出来版面乱。从服务端角度打印友好PDF的第一原则是页面尺寸明确、边距统一、字体嵌入。字体不嵌入的PDF换电脑打印就可能缺字。我每次写生成代码都会给Paragraph设置明确的字体并确保字体文件被嵌入这是底线。当需要多个标签打印时尽量用固定模板避免动态浮动排版。因为在不同PDF阅读器里浮动位置可能差几个像素但累计到一页多标签位置偏移就很明显。用Table布局加固定列宽比用绝对坐标要稳得多。7.2 浏览器直接打印与缩略图思路真正要把PDF在浏览器里展示时一般分为在线预览、下载打印两种。如果只是预览可以给前端返回PDF流浏览器用自带插件打开这个场景后端不需要太多干预。如果想要页面上显示缩略图列表服务端通常先把PDF每页渲染成图片前端再用grid展示。iText7核心包不擅长把页面渲染成高保真的BufferedImage这个活儿更适合专门的渲染组件。我的经验是预览和缩略图不要混在纯后端方案里。要根据部署环境选择适合的渲染器比如客户端有浏览器、服务端有原生组件配合PDF.js这样的前端能力效果更自然。iText7主要负责保证生成和结构处理渲染展示交给更专业的环节。7.3 虚拟打印与格式转换的边界最后说一个容易混淆的概念。虚拟打印是操作系统提供的功能把PDF通过虚拟打印机转成另一个文件或者直接输出到物理打印机这更多是客户端和驱动层的事。iText7在服务端能做的是生成一个目标设备需要的文件不一定等同于用户点击虚拟打印。“PDF转Word”也一样iText7本身不维护PDF到Word的双向转换。因为PDF内容流只记录图形指令Word需要的是段落、样式、目录的语义结构从PDF反推必然损失版式。所以我在项目里定了一条规矩能拿原稿生成PDF就不要让PDF转来转去。把Word转PDF的源文件保管好才是正确的事情。8. 高频问题排查与实战避坑8.1 问题排查速查表现象原因处理方式中文显示为方块或空白未设置中文字体使用STSongStd-Light或嵌入TTF并确保Paragraph.setFont生成大文件OOM一次性加载大量页面分批写入、及时释放源文档、考虑拆成多线程读取PDF后无法修改使用了纯PdfReader改为new PdfReader(src)加new PdfWriter(dst)构造PdfDocument合并后字体缺失源PDF字体未嵌入从源头修复字体嵌入或选择相同字体的模板表单字段setValue报错字段被扁平化或已删除导出字段清单确认字段名必要时重新生成模板页面打印到一半偏移页面大小不统一在生成时统一PageSize设置统一边距这个速查表可以放在项目文档里团队其他人遇到问题时先查一遍比翻代码快。8.2 几个压箱底的实战经验第一所有PDF工具方法都要用try-with-resources管理流依赖iText7自己的close顺序。手动关闭顺序一旦错了可能出现文件损坏或内存泄漏。第二大批量处理时不要在一个PdfDocument里塞几百页再往磁盘写可以按批处理每50页写一次然后使用内存映射文件。我发现和数据库批量插入一样PDF生成也怕一次性做太多。第三在生成报表前先用一个最简单的PDF跑通字体、表格、水印三条链路再增加业务数据。这个习惯帮我节省了大量定位时间。PDF的问题往往不在业务字段而在渲染层。第四版本升级前把核心测试用例跑一遍生成中文、读取文本、表单填写、合并拆分。一套用例五分钟却能在发布前拦截九成兼容性问题。8.3 如果要继续扩展iText7还可以做数字签名、PDF/A归档、条形码与二维码、结构化目录、附件嵌入。如果把这些能力都铺开可以再写一百篇实战笔记。但无论扩展多少底层的PdfDocument生命周期管理和字体处理都是同一套思路。把这个基础打牢遇到新需求时你会发现自己打开API的速度都快了很多。这篇指南里的方案我都实际跑过直接复制基本可用。个别API在小版本之间可能有调整遇到编译差异优先看当前版本的官方文档而不是硬套旧代码。PDF处理的坑很多但只要第一版结构清晰后面修起来就没那么痛。