Spring Boot 实现 DOCX 转 PDF（基于 docx4j）

Spring Boot 实现 DOCX 转 PDF（基于 docx4j） | 极客日志

<dependencies>
    <!-- Spring Boot Starter Web (提供 RESTful 支持) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- docx4j 核心库 -->
    <dependency>
        <groupId>org.docx4j</groupId>
        <artifactId>docx4j</artifactId>
        <version>11.4.4</version>
    </dependency>
    <!-- docx4j 导出 PDF 模块 (使用 Plutext PDF 转换器) -->
    <dependency>
        <groupId>org.docx4j</groupId>
        <artifactId>docx4j-export-PDF</artifactId>
        <version>11.4.4</version>
    </dependency>
    <!-- Apache FOP (可选，但 docx4j-export-PDF 内部可能使用或需要其部分功能) -->
    <dependency>
        <groupId>org.apache.xmlgraphics</groupId>
        <artifactId>fop</artifactId>
        <version>2.7</version>
    </dependency>
    <!-- FOP 需要 XML Graphics Commons -->
    <dependency>
        <groupId>org.apache.xmlgraphics</groupId>
        <artifactId>xmlgraphics-commons</artifactId>
        <version>2.7</version>
    </dependency>
    <!-- 日志依赖 (SLF4J + Logback, 通常由 Spring Boot starter 提供) -->
</dependencies>

import org.docx4j.openpackaging.exceptions.Docx4JException;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;

public WordprocessingMLPackage loadDocx(File docxFile) throws Docx4JException {
    return WordprocessingMLPackage.load(docxFile);
}

public WordprocessingMLPackage loadDocx(InputStream inputStream) throws Docx4JException {
    return WordprocessingMLPackage.load(inputStream);
}

import org.docx4j.convert.out.pdf.PdfConversion;
import org.docx4j.convert.out.pdf.PdfSettings;

public PdfSettings createPdfSettings() {
    PdfSettings pdfSettings = new PdfSettings();
    // 使用 Plutext 转换器 (通常是默认)
    pdfSettings.setFoProcessorName("Plutext");
    // 是否混淆字体 (一般保持 false)
    pdfSettings.setObfuscateFonts(false);
    // 其他设置...
    return pdfSettings;
}

import org.docx4j.Docx4J;
import org.docx4j.openpackaging.exceptions.Docx4JException;

public void convertToPdf(WordprocessingMLPackage wordMLPackage, PdfSettings pdfSettings, OutputStream outputStream) throws Docx4JException {
    Docx4J.toPDF(wordMLPackage, outputStream, pdfSettings);
}

package com.example.docx2pdf.service;

import org.docx4j.Docx4J;
import org.docx4j.convert.out.pdf.PdfConversion;
import org.docx4j.convert.out.pdf.PdfSettings;
import org.docx4j.openpackaging.exceptions.Docx4JException;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import org.springframework.stereotype.Service;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;

@Service
public class DocxToPdfService {

    /**
     * 将输入的 DOCX 文件流转换为 PDF，并写入输出流
     *
     * @param docxInputStream   DOCX 文件输入流
     * @param pdfOutputStream   PDF 输出流
     * @throws Docx4JException  DOCX 处理或转换错误
     * @throws IOException      流操作错误
     */
    public void convertDocxToPdf(InputStream docxInputStream, OutputStream pdfOutputStream) throws Docx4JException, IOException {
        // 1. 加载 DOCX 文档
        WordprocessingMLPackage wordMLPackage = WordprocessingMLPackage.load(docxInputStream);
        // 2. 创建 PDF 设置 (使用默认或自定义设置)
        PdfSettings pdfSettings = createPdfSettings();
        // 3. 执行转换
        Docx4J.toPDF(wordMLPackage, pdfOutputStream, pdfSettings);
        // 4. 重要：确保刷新输出流 (通常在调用方处理关闭)
        pdfOutputStream.flush();
    }

    /**
     * (可选) 创建并配置 PDF 设置
     *
     * @return PdfSettings 对象
     */
    private PdfSettings createPdfSettings() {
        PdfSettings pdfSettings = new PdfSettings();
        // 使用 Plutext 转换器 (通常是默认，显式设置也可)
        pdfSettings.setFoProcessorName("Plutext");
        // 设置其他选项，例如字体映射等 (见高级配置)
        return pdfSettings;
    }

    /**
     * 便捷方法：将 DOCX 文件转换为 PDF 文件
     *
     * @param inputDocxFile  输入 DOCX 文件
     * @param outputPdfFile  输出 PDF 文件
     * @throws Docx4JException
     * @throws IOException
     */
    public void convertDocxFileToPdfFile(File inputDocxFile, File outputPdfFile) throws Docx4JException, IOException {
        try (FileOutputStream fos = new FileOutputStream(outputPdfFile)) {
            convertDocxToPdf(new java.io.FileInputStream(inputDocxFile), fos);
        }
    }
}

import org.docx4j.fonts.MappedFonts;
import org.docx4j.fonts.PhysicalFont;
import org.docx4j.fonts.PhysicalFonts;
import org.docx4j.fonts.FontMapper;

private PdfSettings createPdfSettings() {
    PdfSettings pdfSettings = new PdfSettings();
    pdfSettings.setFoProcessorName("Plutext");
    // 创建字体映射器
    FontMapper fontMapper = new BestMatchingMapper(); // 或者 PhysicalFontMapper
    
    // 关键：注册中文字体映射
    // 假设服务器安装了 SimSun (宋体) 和 SimHei (黑体)
    // 将 DOCX 中的 "宋体" 映射到物理字体 "SimSun"
    fontMapper.put("宋体", PhysicalFonts.get("SimSun"));
    fontMapper.put("SimSun", PhysicalFonts.get("SimSun"));
    // 有时字体名是英文的
    fontMapper.put("黑体", PhysicalFonts.get("SimHei"));
    fontMapper.put("SimHei", PhysicalFonts.get("SimHei"));
    
    // 如果需要，映射其他常用字体
    fontMapper.put("Calibri", PhysicalFonts.get("Calibri")); // 假设服务器有
    fontMapper.put("Arial", PhysicalFonts.get("Arial"));
    
    // 将 FontMapper 设置到 PdfSettings 的 MappedFonts 中
    MappedFonts mappedFonts = new MappedFonts();
    mappedFonts.setMapper(fontMapper);
    pdfSettings.setFontMapping(mappedFonts);
    return pdfSettings;
}

// 示例：加载资源目录下的字体文件 (打包在 JAR 内)
PhysicalFonts.addPhysicalFont("/fonts/simsun.ttf"); // 注意路径，可能需要使用 ClassLoader
PhysicalFonts.addPhysicalFont("/fonts/simhei.ttf");
// 然后在 FontMapper 中映射
fontMapper.put("宋体", PhysicalFonts.get("simsun")); // 注意这里用的是注册时的名字，可能不是"SimSun"

private PdfSettings createPdfSettings() {
    PdfSettings pdfSettings = new PdfSettings();
    pdfSettings.setFoProcessorName("Plutext");
    // 创建 PdfConversion 实例进行更详细的设置
    PdfConversion pdfConversion = pdfSettings.getPdfConversion();
    
    // 设置 PDF 标题、作者等元数据 (可选)
    pdfConversion.setTitle("Converted Document");
    pdfConversion.setAuthor("My Application");
    
    // 设置 PDF 权限 (可选，需要了解 iText 的 PdfWriter 常量)
    // 注意：docx4j 内部使用 iText 5.x (AGPL 许可) 或 Flying Saucer 等，权限设置可能受限或复杂。
    // pdfConversion.setPdfPermissions(...); // 通常需要直接操作底层 iText PdfWriter
    // 其他高级设置...
    // pdfConversion.setPdfVersion(...);
    // pdfConversion.setTagged(...); // 可访问性
    
    return pdfSettings;
}

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

@Service
public class DocxToPdfService {
    private static final Logger logger = LoggerFactory.getLogger(DocxToPdfService.class);

    public void convertDocxToPdf(InputStream docxInputStream, OutputStream pdfOutputStream) throws Docx4JException, IOException {
        try {
            WordprocessingMLPackage wordMLPackage = WordprocessingMLPackage.load(docxInputStream);
            PdfSettings pdfSettings = createPdfSettings();
            Docx4J.toPDF(wordMLPackage, pdfOutputStream, pdfSettings);
            pdfOutputStream.flush();
        } catch (Docx4JException e) {
            logger.error("DOCX 处理或转换失败", e);
            throw e; // 重新抛出，由调用方处理
        } catch (IOException e) {
            logger.error("IO 操作失败", e);
            throw e;
        }
    }
}

@RestController
@RequestMapping("/api/convert")
public class ConversionController {
    @Autowired
    private DocxToPdfService docxToPdfService;

    @PostMapping("/docx-to-pdf")
    public ResponseEntity<Resource> convertDocxToPdf(@RequestParam("file") MultipartFile file) {
        try {
            // ... 创建临时文件或直接使用流 ...
            ByteArrayOutputStream pdfOutputStream = new ByteArrayOutputStream();
            docxToPdfService.convertDocxToPdf(file.getInputStream(), pdfOutputStream);
            ByteArrayResource resource = new ByteArrayResource(pdfOutputStream.toByteArray());
            return ResponseEntity.ok()
                    .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=converted.pdf")
                    .contentType(MediaType.APPLICATION_PDF)
                    .body(resource);
        } catch (Docx4JException | IOException e) {
            // 记录日志 (Controller 也可以有自己的 Logger)
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("转换失败：" + e.getMessage()); // 注意：简单返回字符串，生产环境应更友好
        }
    }
}

package com.example.docx2pdf.controller;

import com.example.docx2pdf.service.DocxToPdfService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.io.ByteArrayResource;
import org.springframework.core.io.Resource;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;
import org.docx4j.openpackaging.exceptions.Docx4JException;

import java.io.ByteArrayOutputStream;
import java.io.IOException;

@RestController
@RequestMapping("/api/convert")
public class ConversionController {
    private final DocxToPdfService docxToPdfService;

    @Autowired
    public ConversionController(DocxToPdfService docxToPdfService) {
        this.docxToPdfService = docxToPdfService;
    }

    @PostMapping("/docx-to-pdf")
    public ResponseEntity<Resource> convertDocxToPdf(@RequestParam("file") MultipartFile file) {
        // 1. 检查文件是否为空
        if (file.isEmpty()) {
            return ResponseEntity.badRequest().body("请上传一个 DOCX 文件");
        }
        // 2. 检查文件类型 (可选，非绝对可靠)
        String contentType = file.getContentType();
        if (contentType == null || !contentType.equals("application/vnd.openxmlformats-officedocument.wordprocessingml.document")) {
            return ResponseEntity.badRequest().body("仅支持 DOCX 格式 (.docx)");
        }
        // 3. 执行转换
        try (ByteArrayOutputStream pdfOutputStream = new ByteArrayOutputStream()) {
            docxToPdfService.convertDocxToPdf(file.getInputStream(), pdfOutputStream);
            // 4. 准备 PDF 响应
            byte[] pdfBytes = pdfOutputStream.toByteArray();
            ByteArrayResource resource = new ByteArrayResource(pdfBytes);
            // 5. 构建响应：PDF 文件下载
            String filename = file.getOriginalFilename();
            if (filename != null) {
                filename = filename.replaceFirst("\\.docx$", "") + ".pdf"; // 替换扩展名
            } else {
                filename = "converted.pdf";
            }
            return ResponseEntity.ok()
                    .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=" + filename)
                    .contentType(MediaType.APPLICATION_PDF)
                    .contentLength(pdfBytes.length)
                    .body(resource);
        } catch (IOException | Docx4JException e) {
            // 6. 处理错误
            return ResponseEntity.internalServerError()
                    .body("转换失败：" + e.getMessage()); // 生产环境应返回更友好的错误对象
        }
    }
}

try {
    File inputTempFile = File.createTempFile("upload-", ".docx");
    file.transferTo(inputTempFile); // 保存上传文件到临时位置
    File outputTempFile = File.createTempFile("converted-", ".pdf");
    docxToPdfService.convertDocxFileToPdfFile(inputTempFile, outputTempFile);
    Path pdfPath = outputTempFile.toPath();
    InputStreamResource resource = new InputStreamResource(new FileInputStream(outputTempFile));
    return ResponseEntity.ok()
            .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=converted.pdf")
            .contentType(MediaType.APPLICATION_PDF)
            .contentLength(Files.size(pdfPath))
            .body(resource);
} finally {
    // 尝试删除临时文件
    if (inputTempFile != null) inputTempFile.delete();
    if (outputTempFile != null) outputTempFile.delete();
}

curl -X POST -F "file=@/path/to/your/document.docx" http://localhost:8080/api/convert/docx-to-pdf --output converted.pdf

package com.example.docx2pdf.service;

import org.docx4j.openpackaging.exceptions.Docx4JException;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.core.io.ClassPathResource;
import org.springframework.util.StreamUtils;

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.IOException;
import java.nio.file.Files;

import static org.junit.jupiter.api.Assertions.*;

@SpringBootTest
public class DocxToPdfServiceTest {

    @Autowired
    private DocxToPdfService docxToPdfService;

    @Test
    public void testConvertSampleDocxToPdf() throws IOException, Docx4JException {
        // 1. 从测试资源目录加载一个小的 DOCX 样本文件
        ClassPathResource sampleDocxResource = new ClassPathResource("testfiles/sample.docx");
        byte[] docxBytes = StreamUtils.copyToByteArray(sampleDocxResource.getInputStream());
        
        // 2. 准备输入流和输出流
        ByteArrayInputStream docxInputStream = new ByteArrayInputStream(docxBytes);
        ByteArrayOutputStream pdfOutputStream = new ByteArrayOutputStream();
        
        // 3. 执行转换
        docxToPdfService.convertDocxToPdf(docxInputStream, pdfOutputStream);
        
        // 4. 验证输出
        byte[] pdfBytes = pdfOutputStream.toByteArray();
        assertNotNull(pdfBytes);
        assertTrue(pdfBytes.length > 0);
        
        // 5. (可选) 简单验证 PDF 头
        // PDF 文件通常以 "%PDF-" 开头
        String pdfHeader = new String(pdfBytes, 0, 5);
        assertEquals("%PDF-", pdfHeader);
        
        // 6. (可选) 将 PDF 写入临时文件检查
        File tempPdfFile = File.createTempFile("test-output", ".pdf");
        Files.write(tempPdfFile.toPath(), pdfBytes);
        System.out.println("Test PDF output: " + tempPdfFile.getAbsolutePath());
        // 手动检查 tempPdfFile 是否正确
        // tempPdfFile.deleteOnExit(); // 让 JVM 退出时删除
    }
}

Spring Boot 实现 DOCX 转 PDF（基于 docx4j）

1. 引言

1.1 DOCX 与 PDF 格式简介

1.2 转换需求与应用场景

1.3 方案选型：为什么选择 docx4j？

2. 环境准备

2.1 基础环境要求

2.2 创建 Spring Boot 项目

2.3 添加 docx4j 及相关依赖

3. 核心转换实现

3.1 基础转换流程

3.2 加载 DOCX 文档 (`WordprocessingMLPackage`)

3.3 配置 PDF 转换选项 (`PDFSettings`)

3.4 执行转换 (`Docx4J.toPDF`)

3.5 完整代码示例 (Service 层)

4. 高级配置与优化

4.1 处理中文字体与乱码问题

4.2 设置 PDF 输出属性 (权限、元数据)

4.3 处理转换异常与日志记录

4.4 性能考量与内存管理

5. 集成到 Spring Boot 应用

5.1 创建 RESTful API 接口 (Controller)

5.2 文件上传与下载处理

5.3 接口测试 (使用 Postman 或 curl)

6. 测试与验证

6.1 单元测试 (JUnit)

6.2 转换结果验证

7. 常见问题与解决方案 (FAQ)

8. 总结

更多推荐文章

相关免费在线工具

Spring Boot 实现 DOCX 转 PDF（基于 docx4j）

1. 引言

1.1 DOCX 与 PDF 格式简介

1.2 转换需求与应用场景

1.3 方案选型：为什么选择 docx4j？

2. 环境准备

2.1 基础环境要求

2.2 创建 Spring Boot 项目

2.3 添加 docx4j 及相关依赖

3. 核心转换实现

3.1 基础转换流程

3.2 加载 DOCX 文档 (WordprocessingMLPackage)

3.3 配置 PDF 转换选项 (PDFSettings)

3.4 执行转换 (Docx4J.toPDF)

3.5 完整代码示例 (Service 层)

4. 高级配置与优化

4.1 处理中文字体与乱码问题

4.2 设置 PDF 输出属性 (权限、元数据)

4.3 处理转换异常与日志记录

4.4 性能考量与内存管理

5. 集成到 Spring Boot 应用

5.1 创建 RESTful API 接口 (Controller)

5.2 文件上传与下载处理

5.3 接口测试 (使用 Postman 或 curl)

6. 测试与验证

6.1 单元测试 (JUnit)

6.2 转换结果验证

7. 常见问题与解决方案 (FAQ)

8. 总结

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具

3.2 加载 DOCX 文档 (`WordprocessingMLPackage`)

3.3 配置 PDF 转换选项 (`PDFSettings`)

3.4 执行转换 (`Docx4J.toPDF`)