SpringBoot实战：基于EasyPoi与Docx4j的Word模板转PDF全流程解决方案

在企业级应用开发中，文档自动化生成是高频需求场景。合同、报告等标准化文档往往需要根据业务数据动态生成，并最终以PDF格式交付。本文将深入剖析SpringBoot环境下整合EasyPoi与Docx4j实现Word模板到PDF转换的完整技术方案，重点解决中文乱码、图片嵌入、依赖冲突等典型问题。

1. 技术选型与架构设计

文档自动化生成通常涉及三个核心环节：模板设计、数据填充和格式转换。在Java生态中，Apache POI是处理Office文档的事实标准，但其原生API较为底层。我们的技术栈组合如下：

• EasyPoi 4.3+ ：基于POI封装的模板引擎，支持类似Freemarker的表达式语法
• Docx4j 6.1+ ：专业Word文档处理库，提供高质量的PDF导出能力
• SpringBoot 2.7+ ：简化依赖管理和配置

典型系统架构如下图所示（伪代码表示处理流程）：

// 数据处理层
Map<String, Object> params = prepareBusinessData(); 

// 文档生成层
XWPFDocument doc = EasyPoi.processTemplate(templatePath, params);

// 格式转换层 
PDFConverter.convert(doc, pdfOutputPath);

2. 环境配置与依赖管理

2.1 Maven依赖关键配置

核心依赖需注意版本兼容性，特别要处理常见的SLF4J冲突：

<dependencies>
    <!-- EasyPoi核心 -->
    <dependency>
        <groupId>cn.afterturn</groupId>
        <artifactId>easypoi-base</artifactId>
        <version>4.3.0</version>
    </dependency>
    
    <!-- Docx4j转换模块 -->
    <dependency>
        <groupId>org.docx4j</groupId>
        <artifactId>docx4j-export-fo</artifactId>
        <version>6.1.0</version>
        <exclusions>
            <exclusion>
                <groupId>org.slf4j</groupId>
                <artifactId>slf4j-log4j12</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
</dependencies>

2.2 资源文件保护配置

必须防止Maven对DOCX模板的压缩处理，在pom.xml中添加：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-resources-plugin</artifactId>
            <configuration>
                <nonFilteredFileExtensions>
                    <nonFilteredFileExtension>docx</nonFilteredFileExtension>
                    <!-- 其他需要保留原格式的文件类型 -->
                </nonFilteredFileExtensions>
            </configuration>
        </plugin>
    </plugins>
</build>

3. Word模板开发规范

3.1 模板语法示例

EasyPoi支持多种模板表达式：

{{company.name}}               // 简单变量
{{?list = employeeList}}       // 列表迭代
{{!image:logo}}                // 图片嵌入

3.2 图片处理最佳实践

图片注入需使用ImageEntity对象：

ImageEntity logo = new ImageEntity();
logo.setUrl("classpath:/static/logo.png"); 
logo.setWidth(100);
logo.setHeight(50);
params.put("companyLogo", logo);

注意：网络图片需先下载到本地临时目录，直接使用URL会导致转换失败

4. 核心工具类实现

4.1 PDF转换关键代码

字体映射是解决中文乱码的核心：

public void convertDocxToPdf(String docxPath, String pdfPath) throws Exception {
    WordprocessingMLPackage wordMLPackage = WordprocessingMLPackage.load(new File(docxPath));
    
    // 字体映射配置
    IdentityPlusMapper fontMapper = new IdentityPlusMapper();
    fontMapper.put("微软雅黑", PhysicalFonts.get("Microsoft Yahei"));
    fontMapper.put("宋体", PhysicalFonts.get("SimSun"));
    // 添加更多中文字体...
    
    wordMLPackage.setFontMapper(fontMapper);
    
    // PDF输出配置
    OutputStream os = new FileOutputStream(pdfPath);
    FOSettings foSettings = Docx4J.createFOSettings();
    foSettings.setWmlPackage(wordMLPackage);
    Docx4J.toFO(foSettings, os, Docx4J.FLAG_EXPORT_PREFER_XSL);
}

4.2 SpringBoot集成方案

建议将转换器声明为Spring Bean：

@Component
public class DocumentGenerator {
    @Value("${doc.template.dir:classpath:/templates}")
    private Resource templateDir;
    
    public void generateContract(PdfRequest request) {
        // 模板路径解析
        String templatePath = resolveTemplate(request.getTemplateType());
        
        // 数据准备
        Map<String, Object> params = buildTemplateParams(request);
        
        // 生成PDF
        String pdfPath = pdfConverter.convert(templatePath, params);
        
        // 文件下载或存储逻辑...
    }
}

5. 生产环境问题排查

5.1 常见错误与解决方案

问题现象	可能原因	解决方案
中文显示为方框	字体未正确映射	检查PhysicalFonts.get()返回值
图片缺失	URL协议不支持	使用本地文件路径或byte[]
转换耗时过长	复杂样式处理	优化模板复杂度
内存溢出	大文档处理	增加JVM内存或分页处理

5.2 性能优化建议

1. 模板设计原则 ：

   • 避免嵌套过深的表格结构
   • 减少动态内容区块数量
   • 固定图片尺寸减少计算

2. 缓存策略 ：

   @Cacheable(value = "documentCache", key = "#templateName")
   public byte[] generateCachedDocument(String templateName, Map<String, Object> params) {
       // 生成逻辑
   }
   

3. 异步处理方案 ：

   @Async
   public CompletableFuture<String> asyncGenerate(PdfRequest request) {
       String result = syncGenerate(request);
       return CompletableFuture.completedFuture(result);
   }
   

6. 高级应用场景

6.1 动态表格生成

结合集合数据生成动态表格：

List<Map<String, Object>> items = new ArrayList<>();
// 添加行数据...
params.put("itemList", items);

模板中使用：

{{?list = itemList}}
{{#.name}} | {{#.price}} | {{#.quantity}}
{{/list}}

6.2 多文档合并

使用PDFBox实现合并：

PDDocument mergedDoc = new PDDocument();
for (String pdfPath : pdfPaths) {
    PDDocument doc = PDDocument.load(new File(pdfPath));
    for (PDPage page : doc.getPages()) {
        mergedDoc.addPage(page);
    }
}
mergedDoc.save(outputPath);

7. 安全与异常处理

7.1 输入验证机制

public void validateTemplateParams(Map<String, Object> params) {
    Assert.notNull(params, "模板参数不能为空");
    Assert.isTrue(params.containsKey("title"), "必须包含title字段");
    // 更多业务规则校验...
}

7.2 事务性文件处理

确保临时文件清理：

try {
    // 生成临时文件
} finally {
    Files.deleteIfExists(Paths.get(tempFilePath));
}

在实际项目部署中，我们发现Linux服务器往往缺少Windows字体库。解决方案是在Dockerfile中安装字体包：

RUN apt-get update && \
    apt-get install -y fonts-wqy-zenhei fonts-wqy-microhei