1. 项目背景与核心需求最近在做一个政务文档管理系统时遇到个典型需求需要自动生成带二维码和单位公章的红头文件。原始方案是手动操作Word模板但领导要求全流程自动化。这个场景其实很常见——合同生成、证书打印、报告签发等业务都需要类似功能。用SpringBootPOI实现这套流程后我梳理出几个关键技术点模板替换用Apache POI操作Word模板中的书签或占位符二维码植入通过ZXing生成二维码图片插入指定位置水印防护防止电子文档被篡改的关键措施PDF转换保证跨平台显示一致性数字签章赋予电子文件法律效力的最后一步这套方案在政务、金融、教育等领域都有广泛应用场景。比如学校批量打印获奖证书时通过模板替换学生姓名自动生成带防伪二维码的PDF版本。2. 技术选型与准备2.1 基础环境搭建!-- pom.xml关键依赖 -- dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.3/version /dependency dependency groupIdcom.google.zxing/groupId artifactIdcore/artifactId version3.5.1/version /dependency dependency groupIdorg.apache.pdfbox/groupId artifactIdpdfbox/artifactId version2.0.27/version /dependency注意POI不同版本对Word格式支持差异较大建议使用4.1.2版本以获得更好的DOCX兼容性2.2 模板设计规范制作Word模板时要注意使用${variable}格式的占位符二维码预留位置用表格固定尺寸签章区域留出5cm×5cm空白模板中不要使用复杂排版如文字环绕实测发现用表格控制二维码位置比浮动图片更稳定特别是在后续PDF转换时不易错位。3. 核心实现步骤3.1 模板内容替换public void fillTemplate(MapString, String params, String templatePath) { try (XWPFDocument doc new XWPFDocument(new FileInputStream(templatePath))) { // 替换段落中的变量 for (XWPFParagraph p : doc.getParagraphs()) { String text p.getText(); for (Map.EntryString, String entry : params.entrySet()) { if (text.contains(entry.getKey())) { text text.replace(entry.getKey(), entry.getValue()); p.getRuns()[0].setText(text, 0); } } } // 替换表格中的变量 for (XWPFTable table : doc.getTables()) { for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { String text cell.getText(); for (Map.EntryString, String entry : params.entrySet()) { if (text.contains(entry.getKey())) { text text.replace(entry.getKey(), entry.getValue()); cell.removeParagraph(0); cell.addParagraph().createRun().setText(text); } } } } } } }踩坑记录直接setText会导致格式丢失必须先remove再add才能保留原格式3.2 二维码生成与插入public void insertQRCode(XWPFDocument doc, String content, int width, int height) { MapEncodeHintType, Object hints new HashMap(); hints.put(EncodeHintType.MARGIN, 1); BitMatrix matrix new QRCodeWriter().encode( content, BarcodeFormat.QR_CODE, width, height, hints); BufferedImage image MatrixToImageWriter.toBufferedImage(matrix); ByteArrayOutputStream baos new ByteArrayOutputStream(); ImageIO.write(image, png, baos); XWPFParagraph paragraph doc.createParagraph(); XWPFRun run paragraph.createRun(); run.addPicture(new ByteArrayInputStream(baos.toByteArray()), XWPFDocument.PICTURE_TYPE_PNG, qrcode.png, Units.toEMU(width), Units.toEMU(height)); }关键参数说明MARGIN控制二维码白边大小建议1-2Units.toEMU()将像素转换为Word使用的EMU单位图片插入后会自动随文字缩放建议用表格固定尺寸3.3 水印添加方案推荐两种实现方式方案A文字水印适合防泄密public void addTextWatermark(XWPFDocument doc, String text) { CTSettings settings doc.getDocument().getBody().addNewSettings(); CTWatermark watermark settings.addNewWatermark(); watermark.setText(text); watermark.setFont(宋体); watermark.setColor(#FF0000); watermark.setStyle(horizontal); }方案B图片水印适合防伪public void addImageWatermark(XWPFDocument doc, InputStream imageStream) { for (XWPFParagraph p : doc.getParagraphs()) { XWPFRun run p.createRun(); run.addPicture(imageStream, XWPFDocument.PICTURE_TYPE_PNG, watermark.png, Units.toEMU(200), Units.toEMU(200)); run.getCTR().addNewDrawing().addNewInline().addNewExtent() .setCx(Units.toEMU(500)).setCy(Units.toEMU(500)); } }实测发现图片水印在PDF转换时更稳定但会增大文件体积4. PDF转换与签章4.1 Word转PDF实现public void convertToPDF(String wordPath, String pdfPath) { try (PDDocument pdfDoc new PDDocument(); InputStream docxStream new FileInputStream(wordPath)) { PDFRenderer renderer new PDFRenderer(pdfDoc); renderer.renderDocument(docxStream); pdfDoc.save(pdfPath); } }转换时常见问题处理中文乱码确保系统安装中文字体排版错乱检查原始文档是否使用非常用样式图片丢失确认图片嵌入方式为嵌入文件4.2 数字签章实现public void signPDF(String srcPdf, String signedPdf, KeyStore ks, String alias, char[] password) { PDDocument doc PDDocument.load(new File(srcPdf)); PDSignature signature new PDSignature(); signature.setFilter(PDSignature.FILTER_ADOBE_PPKLITE); signature.setSubFilter(PDSignature.SUBFILTER_ADBE_PKCS7_DETACHED); signature.setSignDate(Calendar.getInstance()); doc.addSignature(signature, new SignatureOptions(keystore.getPrivateKey(alias, password))); doc.saveIncremental(new FileOutputStream(signedPdf)); }签章准备步骤生成PKCS12格式的数字证书将证书导入Java KeyStore配置时间戳服务TSA确保签名时效性5. 性能优化与异常处理5.1 内存管理方案处理大文档时建议// 启用临时文件缓存 POIXMLDocumentPart.setUseDisk(true); // 分块处理文档 for (int i 0; i doc.getParagraphs().size(); i 100) { ListXWPFParagraph batch doc.getParagraphs() .subList(i, Math.min(i100, doc.getParagraphs().size())); // 处理批次数据... }5.2 常见异常处理异常类型原因分析解决方案OfficeXmlFileException文件不是有效OOXML格式用Word另存为docx格式IllegalStateException文档结构损坏使用POI的Recovery模式ImageFormatException二维码图片格式错误检查ZXing输出是否为PNG6. 完整流程示例public void generateOfficialDoc() { // 1. 加载模板 XWPFDocument doc new XWPFDocument(templateStream); // 2. 替换内容 MapString,String params new HashMap(); params.put(${title}, 关于2023年度考核的通知); fillTemplate(params, doc); // 3. 添加二维码 insertQRCode(doc, https://example.com/verify/123, 150, 150); // 4. 添加水印 addTextWatermark(doc, 机密文件); // 5. 保存Word doc.write(new FileOutputStream(output.docx)); // 6. 转为PDF convertToPDF(output.docx, output.pdf); // 7. 数字签章 KeyStore ks KeyStore.getInstance(PKCS12); ks.load(keystoreStream, password.toCharArray()); signPDF(output.pdf, signed.pdf, ks, mycert, password.toCharArray()); }实际项目中建议将各环节封装为独立Service通过消息队列实现异步处理避免阻塞主线程。对于批量生成场景可以采用模板预加载、连接池优化等手段提升性能。