一、概述

导出数据功能是知识库系统的重要组成部分,支持用户将文档内容导出为 PDF 或 Markdown 格式。

本文详细介绍如何在 kb-document 服务中实现完整的文档导出功能,包括单文档导出和批量导出。

1.1 功能定位

导出数据功能提供以下核心能力:

功能模块说明使用场景
单文档导出PDF将文档内容转换为PDF并返回下载链接文档阅读、分享
单文档下载PDF直接将PDF文件流输出到浏览器快速下载
批量导出PDF多文档打包为PDF格式的ZIP压缩包批量归档
批量导出Markdown多文档打包为Markdown格式的ZIP压缩包内容迁移
文档筛选按标题、状态筛选要导出的文档精确选择

1.2 技术架构

图片.png

1.3 技术实现

  • PDF生成:使用 Apache PDFBox 将 Markdown 内容渲染为 PDF
  • 中文字体支持:多级回退策略,优先从classpath加载,再尝试系统字体
  • Markdown解析:支持标题、代码块、表格、图片、列表、粗体/斜体等格式
  • 批量打包:使用 Java ZipOutputStream 将多个文件打包为 ZIP
  • 文件下载:通过 Content-Disposition 响应头触发浏览器下载
  • Blob处理:前端使用 Blob + URL.createObjectURL 处理二进制响应

二、DTO 设计

2.1 创建 BatchExportRequest

导出功能只需一个请求 DTO,用于接收批量导出的请求参数。

创建 kb-document/src/main/java/com/knowledge/base/document/dto/BatchExportRequest.java:

package com.knowledge.base.document.dto;

import jakarta.validation.constraints.NotEmpty;
import jakarta.validation.constraints.NotNull;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.util.List;

/**
 * 批量导出请求DTO
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
public class BatchExportRequest {

    /** 文档ID列表(使用String避免JavaScript精度丢失) */
    @NotEmpty(message = "文档ID列表不能为空")
    private List<String> documentIds;

    /** 导出格式:pdf / markdown */
    @NotNull(message = "导出格式不能为空")
    private String format;
}

2.2 设计说明

为什么使用 String 类型的 ID?

JavaScript 的 Number 类型只能安全表示 -(253 - 1) 到 (253 - 1) 范围内的整数。知识库系统使用 Snowflake 雪花算法生成的 64 位长整型 ID,超出了 JavaScript 的安全范围,直接从 JSON 反序列化会导致精度丢失。

因此,导出请求中的 documentIds 使用 List<String> 类型:

  1. 前端将选中的文档ID以字符串形式传递
  2. 后端接到请求后,使用 Long.parseLong() 转换为 Long 类型
  3. 避免了跨语言数据传递中的精度丢失问题

三、业务逻辑层

3.1 创建 PdfExportService 接口

创建 kb-document/src/main/java/com/knowledge/base/document/service/PdfExportService.java:

package com.knowledge.base.document.service;

import java.util.List;

/**
 * PDF导出服务接口
 *
 * @author 苏三
 * @since 1.0.0
 */
public interface PdfExportService {

    /**
     * 导出文档为PDF
     *
     * @param documentId 文档ID
     * @return PDF下载URL
     */
    String exportDocumentToPdf(Long documentId);

    /**
     * 导出文档为PDF(直接返回字节数组)
     *
     * @param documentId 文档ID
     * @return PDF文件字节数组
     */
    byte[] exportDocumentToPdfBytes(Long documentId);

    /**
     * 生成PDF文件名
     *
     * @param documentId 文档ID
     * @param title 文档标题
     * @return 文件名
     */
    String generatePdfFileName(Long documentId, String title);

    /**
     * 批量导出文档
     *
     * @param documentIds 文档ID列表(String类型,避免JavaScript精度丢失)
     * @param format 导出格式(pdf / markdown)
     * @return ZIP文件字节数组
     */
    byte[] batchExportDocuments(List<String> documentIds, String format);
}

接口提供两种导出模式:

  • 单文档导出:返回 PDF URL(文件上传到文件服务器)或直接返回字节数组
  • 批量导出:返回 ZIP 文件字节数组,由 Controller 直接写入 HTTP 响应流

3.2 创建 PdfExportServiceImpl 实现类

创建 kb-document/src/main/java/com/knowledge/base/document/service/impl/PdfExportServiceImpl.java:

package com.knowledge.base.document.service.impl;

import cn.hutool.core.io.FileUtil;
import com.knowledge.base.common.exception.BusinessException;
import com.knowledge.base.document.entity.Category;
import com.knowledge.base.document.entity.Document;
import com.knowledge.base.document.entity.mongodb.DocumentContent;
import com.knowledge.base.document.mapper.CategoryMapper;
import com.knowledge.base.document.service.DocumentContentService;
import com.knowledge.base.document.service.DocumentService;
import com.knowledge.base.document.service.FileUploadService;
import com.knowledge.base.document.service.PdfExportService;
import jakarta.annotation.Resource;
import lombok.extern.slf4j.Slf4j;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.PDPage;
import org.apache.pdfbox.pdmodel.PDPageContentStream;
import org.apache.pdfbox.pdmodel.common.PDRectangle;
import org.apache.pdfbox.pdmodel.font.PDType0Font;
import org.apache.pdfbox.pdmodel.font.PDType1Font;
import org.apache.pdfbox.pdmodel.graphics.image.PDImageXObject;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;

import javax.imageio.ImageIO;
import java.awt.Color;
import java.awt.image.BufferedImage;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import java.util.zip.ZipEntry;
import java.util.zip.ZipOutputStream;

/**
 * PDF导出服务实现类
 *
 * <p>使用Apache PDFBox将文档内容转换为PDF格式</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Slf4j
@Service
public class PdfExportServiceImpl implements PdfExportService {

    @Resource
    private DocumentService documentService;

    @Resource
    private DocumentContentService documentContentService;

    @Resource
    private FileUploadService fileUploadService;

    @Resource
    private CategoryMapper categoryMapper;

    @Value("${file.upload.path:/data/knowledge-base/uploads}")
    private String uploadPath;

    // ======================== 布局常量 ========================

    private static final float MARGIN = 50;
    private static final float LINE_HEIGHT = 20;
    private static final float FONT_SIZE = 12;
    private static final float TITLE_FONT_SIZE = 18;
    private static final float SUBTITLE_FONT_SIZE = 10;
    private static final float CODE_FONT_SIZE = 9;
    private static final float CODE_LINE_HEIGHT = 14;

    // One Dark Pro 代码编辑器配色
    private static final Color CODE_BG = new Color(40, 44, 52);
    private static final Color CODE_BORDER = new Color(62, 68, 81);
    private static final Color CODE_HEADER_BG = new Color(33, 37, 43);
    private static final Color CODE_TEXT = new Color(171, 178, 191);
    private static final Color TABLE_HEADER_BG = new Color(240, 242, 245);
    private static final Color TABLE_BORDER = new Color(200, 200, 200);

    // ======================== Markdown 正则匹配 ========================

    private static final Pattern MARKDOWN_HEADING = Pattern.compile("^(#{1,6})\\s+(.+)$");
    private static final Pattern MARKDOWN_CODE = Pattern.compile("^```(\\w*)\\s*$");
    private static final Pattern MARKDOWN_BOLD = Pattern.compile("\\*\\*(.+?)\\*\\*");
    private static final Pattern MARKDOWN_ITALIC = Pattern.compile("\\*(.+?)\\*");
    private static final Pattern MARKDOWN_LINK = Pattern.compile("\\[(.+?)\\]\\((.+?)\\)");
    private static final Pattern MARKDOWN_LIST = Pattern.compile("^[-*+]\\s+(.+)$");
    private static final Pattern MARKDOWN_NUMBER_LIST = Pattern.compile("^\\d+\\.\\s+(.+)$");
    private static final Pattern MARKDOWN_IMAGE = Pattern.compile("!\\[([^\\]]*)\\]\\(([^)]+)\\)");

    // ======================== 中文字体路径 ========================

    /**
     * 系统中文字体路径(按优先级排序)
     */
    private static final String[] CHINESE_FONT_PATHS = {
            "/System/Library/Fonts/Supplemental/Arial Unicode.ttf",  // macOS
            "/Library/Fonts/Arial Unicode.ttf",
            "/usr/share/fonts/wqy/wqy-zenhei.ttc",   // Linux 文泉驿正黑
            "C:\\Windows\\Fonts\\simsun.ttc",          // Windows 宋体
    };

    // ======================== 单文档导出 ========================

    @Override
    public String exportDocumentToPdf(Long documentId) {
        log.info("导出文档为PDF:documentId={}", documentId);

        // 1. 获取文档信息
        Document document = documentService.getById(documentId);
        if (document == null) {
            throw new BusinessException("文档不存在");
        }

        // 2. 从MongoDB获取文档内容
        DocumentContent documentContent = documentContentService.getContentById(document.getContentId());
        String content = documentContent != null ? documentContent.getContent() : "";
        if (content == null || content.isEmpty()) {
            content = "";
        }

        // 3. 获取分类名称
        String categoryName = resolveCategoryName(document.getCategoryId());

        // 4. 生成PDF
        byte[] pdfBytes = generatePdf(document.getTitle(), content,
                document.getAuthorName(), categoryName,
                document.getSummary(), document.getPublishTime());

        // 5. 生成文件名并上传到文件服务器
        String fileName = generatePdfFileName(documentId, document.getTitle());
        String pdfUrl = fileUploadService.uploadBytes(pdfBytes, fileName, "application/pdf");

        log.info("PDF导出成功:documentId={}, pdfUrl={}", documentId, pdfUrl);
        return pdfUrl;
    }

    @Override
    public byte[] exportDocumentToPdfBytes(Long documentId) {
        log.info("导出文档为PDF字节数组:documentId={}", documentId);

        Document document = documentService.getById(documentId);
        if (document == null) {
            throw new BusinessException("文档不存在");
        }

        DocumentContent documentContent = documentContentService.getContentById(document.getContentId());
        String content = documentContent != null ? documentContent.getContent() : "";
        if (content == null || content.isEmpty()) {
            content = "";
        }

        String categoryName = resolveCategoryName(document.getCategoryId());
        return generatePdf(document.getTitle(), content,
                document.getAuthorName(), categoryName,
                document.getSummary(), document.getPublishTime());
    }

    @Override
    public String generatePdfFileName(Long documentId, String title) {
        String safeTitle = FileUtil.mainName(FileUtil.cleanInvalid(title));
        if (safeTitle == null || safeTitle.isEmpty()) {
            safeTitle = "document";
        }
        if (safeTitle.length() > 50) {
            safeTitle = safeTitle.substring(0, 50);
        }

        String timestamp = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));
        return String.format("%s_%s.pdf", safeTitle, timestamp);
    }

    // ======================== 批量导出 ========================

    @Override
    public byte[] batchExportDocuments(List<String> documentIds, String format) {
        log.info("批量导出文档:documentIds={}, format={}", documentIds, format);

        // 将String ID转为Long,避免JavaScript精度丢失
        List<Long> longIds = documentIds.stream()
                .map(Long::parseLong)
                .collect(Collectors.toList());

        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        try (ZipOutputStream zos = new ZipOutputStream(baos)) {

            List<Document> documents = documentService.listByIds(longIds);
            log.info("查询到{}个文档(请求{}个)", documents.size(), documentIds.size());

            for (Document document : documents) {
                DocumentContent documentContent = documentContentService.getContentById(document.getContentId());
                String content = documentContent != null ? documentContent.getContent() : "";
                if (content == null) content = "";

                String fileName;
                byte[] fileBytes;

                if ("markdown".equalsIgnoreCase(format)) {
                    // Markdown格式:直接导出原始Markdown内容
                    fileName = sanitizeFileName(document.getTitle()) + ".md";
                    fileBytes = content.getBytes(StandardCharsets.UTF_8);
                } else {
                    // PDF格式:渲染为PDF
                    String categoryName = resolveCategoryName(document.getCategoryId());
                    byte[] pdfBytes = generatePdf(document.getTitle(), content,
                            document.getAuthorName(), categoryName,
                            document.getSummary(), document.getPublishTime());
                    fileName = generatePdfFileName(document.getId(), document.getTitle());
                    fileBytes = pdfBytes;
                }

                ZipEntry entry = new ZipEntry(fileName);
                zos.putNextEntry(entry);
                zos.write(fileBytes);
                zos.closeEntry();
            }

            zos.finish();
        } catch (IOException e) {
            log.error("批量导出失败", e);
            throw new RuntimeException("批量导出失败:" + e.getMessage());
        }

        log.info("批量导出成功:共{}个文档", documentIds.size());
        return baos.toByteArray();
    }

    private String sanitizeFileName(String title) {
        if (title == null || title.isEmpty()) {
            return "untitled";
        }
        return title.replaceAll("[\\\\/:*?\"<>|]", "_").trim();
    }
}

3.3 PDF 渲染引擎

PDF渲染是导出功能的核心,负责将 Markdown 内容转换为可视化页面。

3.3.1 页面布局

使用 A4 纸张大小(210mm × 297mm),设置上下左右各 50 点的页边距:

PDPage page = new PDPage(PDRectangle.A4);
float yPosition = page.getMediaBox().getHeight() - MARGIN;
float pageWidth = page.getMediaBox().getWidth() - 2 * MARGIN;

3.3.2 中文字体加载

采用多级回退策略,确保在不同操作系统上都能正确渲染中文:

  1. 优先 classpath 资源:/fonts/Arial Unicode.ttf(部署到服务器后保证可用)
  2. 备用 classpath:/fonts/simsun.ttc
  3. 系统字体路径:macOS / Linux / Windows 按优先级尝试
private PDType0Font loadChineseFont(PDDocument document) throws IOException {
    // 优先从classpath资源文件加载
    try (InputStream is = getClass().getResourceAsStream("/fonts/Arial Unicode.ttf")) {
        if (is != null) {
            log.info("从classpath资源加载中文字体:Arial Unicode.ttf");
            return PDType0Font.load(document, is);
        }
    }
    // 备用:尝试其他classpath资源
    try (InputStream is = getClass().getResourceAsStream("/fonts/simsun.ttc")) {
        if (is != null) {
            return PDType0Font.load(document, is);
        }
    }
    // 回退:尝试从系统字体路径加载
    for (String fontPath : CHINESE_FONT_PATHS) {
        Path path = Paths.get(fontPath);
        if (Files.exists(path)) {
            return PDType0Font.load(document, path.toFile());
        }
    }
    throw new IOException("未找到可用的中文字体");
}

3.3.3 Markdown 内容渲染

PDF引擎按行解析 Markdown 内容,根据不同格式调用对应的渲染方法:

内容类型检测方式渲染效果
标题 (H1-H6)^#{1,6}\s+(.+)$不同字号 + 加粗,H1=18pt,每降一级减2pt
代码块^```(\w*)\s*$One Dark Pro 深色主题背景 + 行号 + 等宽字体
表格\`...
图片![alt](url)从URL下载 + 嵌入PDF + 自适应缩放(最大400x300)
列表^[-*+]\s+(.+)$缩进20pt + 项目符号
有序列表^\d+\.\s+(.+)$缩进20pt + 数字序号
粗体\*\*(.+?)\*\*提取纯文本
斜体\*(.+?)\*提取纯文本
链接\[(.+?)\]\((.+?)\)提取链接文本
空行空字符串垂直间距缩小一半

3.3.4 代码块渲染

代码块采用程序员友好的深色主题效果:

// 绘制代码块背景
float codeBlockHeight = codeLines.size() * CODE_LINE_HEIGHT + 16;
contentStream.setNonStrokingColor(CODE_BG);
contentStream.addRect(MARGIN, yPosition - codeBlockHeight,
        pageWidth, codeBlockHeight);
contentStream.fill();

// 绘制顶部语言标签栏
contentStream.setNonStrokingColor(CODE_HEADER_BG);
contentStream.addRect(MARGIN, yPosition - 20, pageWidth, 20);
contentStream.fill();

// 绘制代码行号和内容
for (int j = 0; j < codeLines.size(); j++) {
    contentStream.beginText();
    contentStream.setFont(chineseFont, CODE_FONT_SIZE);
    contentStream.setNonStrokingColor(CODE_TEXT);
    contentStream.newLineAtOffset(MARGIN + 8, yPosition - 20 - (j + 1) * CODE_LINE_HEIGHT);
    contentStream.showText(String.format("%3d | %s", j + 1, codeLines.get(j)));
    contentStream.endText();
}

3.3.5 表格渲染

使用 Java 浮点运算绘制带对齐功能的完整表格:

private RenderResult renderTable(PDPageContentStream contentStream,
        PDDocument document, PDPage page, List<String[]> tableData,
        PDType0Font font, float yPosition, float pageWidth, float margin) {

    int colCount = tableData.get(0).length;

    // 计算列宽(平均分配)
    float tableWidth = pageWidth;
    float colWidth = tableWidth / colCount;
    float rowHeight = LINE_HEIGHT + 6;

    // 绘制表头
    for (int row = 0; row < tableData.size(); row++) {
        // 表头背景色
        if (row == 0) {
            contentStream.setNonStrokingColor(TABLE_HEADER_BG);
            contentStream.addRect(margin, yPosition - rowHeight, tableWidth, rowHeight);
            contentStream.fill();
        }

        // 绘制每列内容
        for (int col = 0; col < colCount; col++) {
            String cellText = tableData.get(row)[col].trim();
            contentStream.beginText();
            contentStream.setFont(font, FONT_SIZE);
            contentStream.setNonStrokingColor(Color.BLACK);
            contentStream.newLineAtOffset(margin + col * colWidth + 4,
                    yPosition - rowHeight + 4);
            contentStream.showText(cellText);
            contentStream.endText();
        }
        yPosition -= rowHeight;
    }

    return new RenderResult(contentStream, page, yPosition);
}

3.3.6 图片渲染

从远程 URL 下载图片并嵌入 PDF:

private RenderResult renderImage(PDPageContentStream contentStream,
        PDDocument document, PDPage page, String imageUrl, String imageAlt,
        float yPosition, float pageWidth, float margin) {
    try {
        // 从URL下载图片
        BufferedImage bufferedImage = ImageIO.read(new URL(imageUrl));
        float imageWidth = bufferedImage.getWidth();
        float imageHeight = bufferedImage.getHeight();

        // 缩放到合适大小(最大宽度=pageWidth,最大高度=400)
        float maxWidth = Math.min(pageWidth, 450);
        float maxHeight = 400;
        float scale = Math.min(maxWidth / imageWidth, maxHeight / imageHeight);
        float displayWidth = imageWidth * scale;
        float displayHeight = imageHeight * scale;

        // 嵌入图片到PDF
        PDImageXObject pdImage = PDImageXObject.createFromByteArray(
                document, /* image bytes */, "image");
        contentStream.drawImage(pdImage,
                margin + (pageWidth - displayWidth) / 2,
                yPosition - displayHeight,
                displayWidth, displayHeight);

        yPosition -= (displayHeight + 12);
    } catch (IOException e) {
        log.warn("无法加载图片:{}", imageUrl);
        // 图片加载失败时显示替代文本
    }

    return new RenderResult(contentStream, page, yPosition);
}

3.3.7 自动分页

当内容超出当前页面底部时,自动创建新页面:

if (yPosition < MARGIN + LINE_HEIGHT) {
    contentStream.close();
    page = new PDPage(PDRectangle.A4);
    document.addPage(page);
    contentStream = new PDPageContentStream(document, page,
            PDPageContentStream.AppendMode.OVERWRITE, true, true);
    yPosition = page.getMediaBox().getHeight() - MARGIN;
}

3.3.8 文本宽度测量和自动换行

精确测量每个字符在指定字体和字号下的宽度,超出页面宽度时自动换行:

private List<String> wrapTextByWidth(String text, float maxWidth,
        PDType0Font font, float fontSize) {
    List<String> result = new ArrayList<>();
    StringBuilder currentLine = new StringBuilder();
    float currentWidth = 0;

    for (char ch : text.toCharArray()) {
        float charWidth = getCharWidth(ch, font, fontSize);
        if (currentWidth + charWidth > maxWidth) {
            result.add(currentLine.toString());
            currentLine = new StringBuilder();
            currentWidth = 0;
        }
        currentLine.append(ch);
        currentWidth += charWidth;
    }

    if (currentLine.length() > 0) {
        result.add(currentLine.toString());
    }

    return result;
}

private float getCharWidth(char ch, PDType0Font font, float fontSize) {
    try {
        if (ch < 256) {
            return font.getStringWidth(String.valueOf(ch)) * fontSize / 1000f;
        }
        // CJK字符宽度 = 字号
        return fontSize;
    } catch (Exception e) {
        return fontSize;
    }
}

3.4 核心设计要点

1. 导出格式差异处理

格式处理方式说明
PDF通过 Apache PDFBox 渲染为可视化页面支持标题、代码、表格、图片等格式
Markdown直接输出原始 UTF-8 字节保留完整的 Markdown 语法

2. 文件命名规范

  • PDF文件:{标题}_{yyyyMMddHHmmss}.pdf,标题清理掉非法字符(\ / : * ? " < > |),截断为50字符
  • ZIP文件:documents_export_{yyyyMMddHHmmss}.zip
  • Markdown文件:{标题}.md

3. 错误处理策略

  • 文档不存在 → 抛出 BusinessException
  • 文档内容为空 → 允许导出(生成空白或只含标题的PDF)
  • 图片加载失败 → 跳过该图片,不影响其他内容导出
  • 字体加载失败 → 降级使用默认字体(无中文支持时仍有基本排版)

四、控制器层

4.1 添加导出接口到 DocumentController

在 kb-document/src/main/java/com/knowledge/base/document/controller/DocumentController.java 中添加三个导出相关接口:

/**
 * 导出文档为PDF
 *
 * @param documentId 文档ID
 * @return PDF下载URL
 */
@GetMapping("/{documentId}/export-pdf")
@Operation(summary = "导出PDF", description = "导出文档为PDF并返回下载链接")
public Result<String> exportDocumentToPdf(
    @Parameter(description = "文档ID", required = true)
    @PathVariable Long documentId) {
    log.info("导出PDF请求:documentId={}", documentId);

    String pdfUrl = pdfExportService.exportDocumentToPdf(documentId);
    return Result.success("PDF导出成功", pdfUrl);
}

/**
 * 下载文档PDF(直接返回文件流)
 *
 * @param documentId 文档ID
 * @param response HTTP响应
 */
@GetMapping("/{documentId}/download-pdf")
@Operation(summary = "下载PDF", description = "直接下载文档PDF文件")
public void downloadDocumentPdf(
    @Parameter(description = "文档ID", required = true)
    @PathVariable Long documentId,
    HttpServletResponse response) {
    log.info("下载PDF请求:documentId={}", documentId);

    try {
        byte[] pdfBytes = pdfExportService.exportDocumentToPdfBytes(documentId);

        DocumentVO document = documentService.getDocumentById(documentId);
        String fileName = pdfExportService.generatePdfFileName(documentId, document.getTitle());

        response.setContentType("application/pdf");

        // UTF-8 编码文件名,兼容各浏览器
        String encodedFileName = URLEncoder.encode(fileName, StandardCharsets.UTF_8)
                .replace("+", "%20");
        response.setHeader("Content-Disposition",
                "attachment; filename*=UTF-8''" + encodedFileName);
        response.setContentLength(pdfBytes.length);

        response.getOutputStream().write(pdfBytes);
        response.getOutputStream().flush();

        log.info("PDF下载成功:documentId={}", documentId);
    } catch (IOException e) {
        log.error("PDF下载失败:documentId={}", documentId, e);
        throw new RuntimeException("PDF下载失败:" + e.getMessage());
    }
}

/**
 * 批量导出文档
 *
 * @param request 批量导出请求
 * @param response HTTP响应
 */
@PostMapping("/batch-export")
@Operation(summary = "批量导出", description = "批量导出选中文档为PDF或Markdown格式的ZIP文件")
public void batchExportDocuments(
    @Parameter(description = "批量导出请求", required = true)
    @Valid @RequestBody BatchExportRequest request,
    HttpServletResponse response) {
    log.info("批量导出请求:documentIds={}, format={}",
            request.getDocumentIds(), request.getFormat());

    try {
        byte[] zipBytes = pdfExportService.batchExportDocuments(
                request.getDocumentIds(), request.getFormat());

        String fileName = "documents_export_" +
                LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss")) + ".zip";

        response.setContentType("application/zip");
        String encodedFileName = URLEncoder.encode(fileName, StandardCharsets.UTF_8)
                .replace("+", "%20");
        response.setHeader("Content-Disposition",
                "attachment; filename*=UTF-8''" + encodedFileName);
        response.setContentLength(zipBytes.length);

        response.getOutputStream().write(zipBytes);
        response.getOutputStream().flush();

        log.info("批量导出成功:共{}个文档", request.getDocumentIds().size());
    } catch (IOException e) {
        log.error("批量导出失败", e);
        throw new RuntimeException("批量导出失败:" + e.getMessage());
    }
}

4.2 API 端点设计

方法路径说明请求参数响应类型
GET/documents/{id}/export-pdf导出单文档为PDFdocumentId (路径参数)JSON (PDF URL)
GET/documents/{id}/download-pdf直接下载PDF文件documentId (路径参数)application/pdf (二进制流)
POST/documents/batch-export批量导出为ZIPBatchExportRequest (JSON请求体)application/zip (二进制流)

4.3 接口设计说明

两种单文档导出模式的区别:

模式请求路径返回内容适用场景
导出URLexport-pdfJSON格式的PDF下载链接前端展示下载地址,用户决定是否下载
直接下载download-pdf二进制PDF流(浏览器直接下载)一键下载,减少一次HTTP请求

批量导出使用 POST 方法的原因:

文档ID列表可能较长(上百个),GET方法的URL长度有限制(不同浏览器和服务器限值在2KB~8KB之间)。使用POST方法将ID列表放在请求体中,突破了URL长度限制。

Content-Disposition 文件名编码:

使用 filename*=UTF-8''{URL编码的文件名} 格式,这是 RFC 5987 标准,支持所有浏览器正确处理中文文件名。


五、前端实现

5.1 HTTP 请求扩展 - 下载模式

在 src/services/request.ts 中,Axios 配置需要扩展以支持文件下载场景:

// 扩展 Axios请求配置
interface CustomAxiosRequestConfig extends AxiosRequestConfig {
  skipAuth?: boolean;
  skipErrorToast?: boolean;
  showLoading?: boolean;
  // 下载模式:返回完整 AxiosResponse 以便读取 Content-Disposition 等响应头
  _download?: boolean;
}

当 _download: true 时,响应拦截器直接返回原始的 AxiosResponse(跳过标准的数据解包逻辑),这样才能获取 Content-Disposition 响应头中的文件名:

// 响应拦截器
request.interceptors.response.use((response) => {
    const customConfig = response.config as CustomAxiosRequestConfig;

    // 下载请求:直接返回完整的 AxiosResponse
    if (customConfig._download) {
      return response;
    }

    // 标准请求:解包数据
    const data = response.data;
    // ... 标准处理逻辑
});

同时提供通用的下载辅助函数:

/**
 * 下载文件
 */
download: (url: string, filename?: string): Promise<void> => {
    return request.get(url, {
      responseType: 'blob',
      _download: true,
    } as any).then((response: AxiosResponse) => {
      // 从 Content-Disposition 响应头中提取文件名
      let finalFilename = filename || 'download';
      const contentDisposition = response.headers?.['content-disposition'] || '';
      const match = contentDisposition.match(/filename\*=UTF-8''([^"';]+)/);
      if (match) {
        try {
          finalFilename = decodeURIComponent(match[1]);
        } catch {
          finalFilename = match[1];
        }
      }

      // 创建Blob并触发下载
      const blob = new Blob([response.data], { type: 'application/octet-stream' });
      const link = document.createElement('a');
      link.href = URL.createObjectURL(blob);
      link.download = finalFilename;
      document.body.appendChild(link);
      link.click();
      document.body.removeChild(link);
      URL.revokeObjectURL(link.href);
    });
},

5.2 前端 API 服务

在 src/services/document.service.ts 中添加三个导出接口方法:

// 导出文档为PDF(获取下载链接)
exportDocumentToPdf: (documentId: string) => {
    return http.get<string>(`/document/documents/${documentId}/export-pdf`);
},

// 下载文档PDF(直接下载)
downloadDocumentPdf: (documentId: string) => {
    return (http as any).download(`/document/documents/${documentId}/download-pdf`);
},

// 批量导出文档
batchExportDocuments: async (documentIds: string[], format: 'pdf' | 'markdown') => {
    // 使用 _download 模式获取完整响应(包括 headers)
    const response: any = await request.post('/document/documents/batch-export',
        { documentIds, format }, {
        responseType: 'blob',
        _download: true,
    } as any);

    // 检查响应是否为 JSON 错误(而非 ZIP 文件)
    const contentType = response.headers?.['content-type'] || '';
    if (contentType.includes('application/json')) {
        // 读取错误信息
        const text = await response.data.text();
        const errorData = JSON.parse(text);
        throw new Error(errorData.message || '导出失败');
    }

    // 从 Content-Disposition 中提取文件名
    const contentDisposition = response.headers?.['content-disposition'] || '';
    let filename = `documents_export_${new Date().toISOString().slice(0, 10)}.zip`;
    const match = contentDisposition.match(/filename\*=UTF-8''([^"';]+)/);
    if (match) {
        try {
            filename = decodeURIComponent(match[1]);
        } catch {
            filename = match[1];
        }
    }

    // 创建 Blob 并触发浏览器下载
    const blob = new Blob([response.data], { type: 'application/zip' });
    const link = document.createElement('a');
    link.href = URL.createObjectURL(blob);
    link.download = filename;
    document.body.appendChild(link);
    link.click();
    document.body.removeChild(link);
    URL.revokeObjectURL(link.href);
},

5.3 前端页面 - ExportDataPage

创建 src/pages/ExportDataPage.tsx:

import React, { useState, useEffect, useCallback } from 'react';
import {
  Card,
  Table,
  Button,
  Space,
  Input,
  Select,
  Radio,
  Row,
  Col,
  Typography,
  Alert,
  Tag,
} from 'antd';
import { App } from 'antd';
import {
  FileTextOutlined,
  FilePdfOutlined,
  FileMarkdownOutlined,
  SearchOutlined,
  ReloadOutlined,
  DownloadOutlined,
  ClearOutlined,
} from '@ant-design/icons';
import type { ColumnsType } from 'antd/es/table';
import dayjs from 'dayjs';
import { documentService } from '@/services';
import { Document } from '@/types';

const { Title, Text } = Typography;

const ExportDataPage: React.FC = () => {
  const { message } = App.useApp();
  const [loading, setLoading] = useState(false);
  const [exporting, setExporting] = useState(false);
  const [documents, setDocuments] = useState<Document[]>([]);
  const [total, setTotal] = useState(0);
  const [selectedRowKeys, setSelectedRowKeys] = useState<React.Key[]>([]);
  const [exportFormat, setExportFormat] = useState<'pdf' | 'markdown'>('pdf');
  const [keyword, setKeyword] = useState('');
  const [statusFilter, setStatusFilter] = useState<number | undefined>(undefined);
  const [pagination, setPagination] = useState({ current: 1, pageSize: 10 });

  // 获取文档列表
  const fetchDocuments = useCallback(async () => {
    setLoading(true);
    try {
      const result = await documentService.getDocuments({
        keyword: keyword || undefined,
        status: statusFilter,
        page: pagination.current,
        pageSize: pagination.pageSize,
        sortBy: 'updateTime',
        sortOrder: 'desc',
      });
      setDocuments(result.list);
      setTotal(result.total);
    } catch {
      message.error('获取文档列表失败');
    } finally {
      setLoading(false);
    }
  }, [keyword, statusFilter, pagination.current, pagination.pageSize, message]);

  useEffect(() => {
    fetchDocuments();
  }, [fetchDocuments]);

  // 批量导出处理
  const handleExport = async () => {
    if (selectedRowKeys.length === 0) {
      message.warning('请先选择要导出的文档');
      return;
    }
    setExporting(true);
    try {
      const ids = selectedRowKeys.map(String);
      await documentService.batchExportDocuments(ids, exportFormat);
      message.success(`成功导出 ${ids.length} 个文档`);
    } catch {
      message.error('导出失败,请重试');
    } finally {
      setExporting(false);
    }
  };

  // 表格列定义
  const columns: ColumnsType<Document> = [
    {
      title: '文档标题',
      dataIndex: 'title',
      key: 'title',
      ellipsis: true,
      render: (text: string) => (
        <Space>
          <FileTextOutlined style={{ color: '#2563eb' }} />
          <Text ellipsis={{ tooltip: text }} style={{ maxWidth: 300 }}>
            {text}
          </Text>
        </Space>
      ),
    },
    {
      title: '作者',
      dataIndex: 'authorName',
      key: 'authorName',
      width: 120,
    },
    {
      title: '状态',
      dataIndex: 'status',
      key: 'status',
      width: 100,
      render: (status: number) => {
        const statusMap: Record<number, { label: string; color: string }> = {
          0: { label: '草稿', color: 'default' },
          1: { label: '已发布', color: 'green' },
          2: { label: '已归档', color: 'orange' },
        };
        const info = statusMap[status] || { label: '未知', color: 'default' };
        return <Tag color={info.color}>{info.label}</Tag>;
      },
    },
    {
      title: '更新时间',
      dataIndex: 'updateTime',
      key: 'updateTime',
      width: 180,
      render: (time: string) => time ? dayjs(time).format('YYYY-MM-DD HH:mm:ss') : '-',
      sorter: true,
    },
  ];

  const hasSelected = selectedRowKeys.length > 0;

  return (
    <div style={{ padding: '16px 16px 32px 16px', minHeight: '100vh', background: '#f8fafc' }}>
      {/* 页面头部 */}
      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', marginBottom: 24 }}>
        <div>
          <Title level={1} style={{ fontSize: 32, fontWeight: 700, color: '#0f172a', marginBottom: 8 }}>
            导出数据
          </Title>
          <Text style={{ fontSize: 16, color: '#475569' }}>
            选择文档并导出为 PDF 或 Markdown 格式的 ZIP 压缩包
          </Text>
        </div>
      </div>
      {/* 筛选栏 */}
      <Card style={{ borderRadius: 12, marginBottom: 16 }} variant="borderless">
        <Row gutter={[16, 16]} align="middle">
          <Col xs={24} sm={8} lg={6}>
            <Input
              placeholder="搜索文档标题"
              allowClear
              prefix={<SearchOutlined />}
              value={keyword}
              onChange={(e) => {
                setKeyword(e.target.value);
                setPagination((prev) => ({ ...prev, current: 1 }));
              }}
            />
          </Col>
          <Col xs={24} sm={6} lg={4}>
            <Select
              placeholder="文档状态"
              allowClear
              style={{ width: '100%' }}
              value={statusFilter}
              onChange={(val) => {
                setStatusFilter(val === 'all' ? undefined : val);
                setPagination((prev) => ({ ...prev, current: 1 }));
              }}
            >
              <Select.Option value="all">全部状态</Select.Option>
              <Select.Option value={0}>草稿</Select.Option>
              <Select.Option value={1}>已发布</Select.Option>
              <Select.Option value={2}>已归档</Select.Option>
            </Select>
          </Col>
          <Col xs={24} sm={10} lg={14}>
            <Space>
              <Button icon={<ReloadOutlined />} onClick={fetchDocuments}>刷新</Button>
              {hasSelected && (
                <Button icon={<ClearOutlined />} onClick={() => setSelectedRowKeys([])}>
                  取消选择
                </Button>
              )}
            </Space>
          </Col>
        </Row>
      </Card>
      {/* 导出配置栏 */}
      <Card style={{ borderRadius: 12, marginBottom: 16 }} variant="borderless">
        <Row gutter={[24, 16]} align="middle">
          <Col xs={24} md={14}>
            <Space size="middle">
              <Text strong>导出格式:</Text>
              <Radio.Group value={exportFormat} onChange={(e) => setExportFormat(e.target.value)}>
                <Radio.Button value="pdf">
                  <Space>
                    <FilePdfOutlined />
                    PDF
                  </Space>
                </Radio.Button>
                <Radio.Button value="markdown">
                  <Space>
                    <FileMarkdownOutlined />
                    Markdown
                  </Space>
                </Radio.Button>
              </Radio.Group>
            </Space>
          </Col>
          <Col xs={24} md={10}>
            <Space style={{ float: 'right' }}>
              {hasSelected && (
                <Text style={{ color: '#2563eb', fontWeight: 500 }}>
                  已选择 <Text strong style={{ fontSize: 18 }}>{selectedRowKeys.length}</Text> 个文档
                </Text>
              )}
              <Button
                type="primary"
                icon={<DownloadOutlined />}
                onClick={handleExport}
                loading={exporting}
                disabled={!hasSelected}
                size="large"
              >
                导出选中文档
              </Button>
            </Space>
          </Col>
        </Row>
        {selectedRowKeys.length > 0 && (
          <Alert
            message={`将导出 ${selectedRowKeys.length} 个文档为 ${exportFormat.toUpperCase()} 格式的 ZIP 压缩包`}
            type="info"
            showIcon
            style={{ marginTop: 12 }}
          />
        )}
      </Card>
      {/* 文档表格 */}
      <Card style={{ borderRadius: 12 }} variant="borderless">
        <Table
          rowKey="id"
          columns={columns}
          dataSource={documents}
          loading={loading}
          rowSelection={{
            selectedRowKeys,
            onChange: (keys) => setSelectedRowKeys(keys),
          }}
          onChange={(pag: any) => {
            setPagination({ current: pag.current, pageSize: pag.pageSize });
          }}
          pagination={{
            ...pagination,
            total,
            showSizeChanger: true,
            showQuickJumper: true,
            showTotal: (t: number) => `共 ${t} 条`,
          }}
          scroll={{ x: 600 }}
        />
      </Card>
    </div>
  );
};

export default ExportDataPage;

5.4 前端设计说明

1. 状态管理

状态类型用途
loadingboolean文档列表加载中
exportingboolean导出进行中
documentsDocument[]当前页文档列表
totalnumber文档总数
selectedRowKeysReact.Key[]表格勾选的行
exportFormat'pdf''markdown'
keywordstring搜索关键词
statusFilternumberundefined
pagination{current, pageSize}分页参数

2. 筛选条件组合

前端发送请求时,undefined 的筛选参数不发送给后端,后端会忽略这些参数:

const result = await documentService.getDocuments({
    keyword: keyword || undefined,      // 空字符串转为 undefined
    status: statusFilter,               // undefined 时不传该参数
    page: pagination.current,
    pageSize: pagination.pageSize,
});

状态筛选支持"全部状态"选项(value="all"),选中时转为 undefined 表示不过滤状态。

3. 错误处理

// 检查响应是否为 JSON 错误(而非 ZIP 文件)
const contentType = response.headers?.['content-type'] || '';
if (contentType.includes('application/json')) {
    const text = await response.data.text();
    const errorData = JSON.parse(text);
    throw new Error(errorData.message || '导出失败');
}

当后端返回 JSON 错误信息(而非预期的 ZIP 文件流)时,前端能正确解读错误信息并给出提示,避免用户下载到一个包含错误消息的无效文件。

4. 文件名提取

从 HTTP 响应头的 Content-Disposition 中提取文件名的正则:

const match = contentDisposition.match(/filename\*=UTF-8''([^"';]+)/);

匹配的是 RFC 5987 编码格式的文件名,支持中文等非ASCII字符。


六、路由注册

6.1 添加导出页面路由

在 src/router/index.tsx 中注册导出页面路由:

// 1. 在文件顶部添加 lazy import
const ExportDataPage = lazy(() => import('@/pages/ExportDataPage'));

// 2. 在 MainLayout 路由下添加子路由
{
    path: 'documents/export',
    element: (
      <Suspense fallback={<LoadingFallback />}>
        <ExportDataPage />
      </Suspense>
    ),
},

完整路由路径为 /documents/export,需要用户登录后才能访问(受 ProtectedRoute 保护)。

6.2 访问方式

用户可以通过以下方式进入导出页面:

  1. 直接在浏览器地址栏输入 http://localhost:3002/documents/export
  2. 后续可以添加到侧边导航栏作为菜单项

七、项目依赖配置

7.1 Maven 依赖

PDF导出功能需要添加 Apache PDFBox 依赖到 kb-document/pom.xml:

<!-- Apache PDFBox - PDF生成 -->
<dependency>
    <groupId>org.apache.pdfbox</groupId>
    <artifactId>pdfbox</artifactId>
    <version>3.0.1</version>
</dependency>

7.2 字体资源

在 kb-document/src/main/resources/fonts/ 目录下放置中文字体文件:

  • Arial Unicode.ttf — 推荐使用(支持CJK字符集,文件较小)

字体文件用于 PDF 渲染中文内容。部署到服务器后,classpath资源会自动被加载,无需额外配置系统字体。

测试

按顺序启动下面这些微服务:

kb-gateway

kb-auth

kb-document

启动前端

cd knowledge-base-frontend

npm run dev

浏览器访问导出数据页面:

http://localhost:3002/documents/export

图片.png

选择需要导出的文档,导出PDF格式的文件:

图片.png

点击导出选中文档按钮,会导出一个zip压缩文件,解压之后有一个PDF文件:

图片.png

打开该PDF文件,里面的文档内容能够正常显示:

图片.png

然后回到数据导出页面,选择Markdown格式,再导出那篇文章:

里面能够看到markdown格式的文档。

总结

本文详细介绍了文档导出数据功能的完整实现,涵盖了以下核心内容:

已完成功能

功能实现方式说明
单文档导出PDFApache PDFBox获取下载链接
单文档下载PDFHTTP文件流浏览器直接下载
批量导出PDFZIP打包选中文档打包下载
批量导出MarkdownZIP打包原始MD内容打包
Markdown渲染正则解析 + PDFBox标题/代码/表格/图片/列表
中日文字体多级回退策略跨平台兼容
前端导出页面React + Ant Design搜索/筛选/多选/导出

技术要点

  1. Markdown到PDF转换:逐行解析Markdown语法,分别处理标题、代码块、表格、图片、列表等格式
  2. 中文字体处理:优先从classpath加载,再回退到系统路径,确保跨平台部署
  3. 自动分页:内容超出页面底部时自动创建新页面,代码块和表格也支持跨页
  4. JavaScript精度安全:使用String类型传递长整型ID,避免JSON序列化时的精度丢失
  5. Blob下载:前端通过Blob + URL.createObjectURL 实现浏览器下载,不跳转页面
  6. 文件名编码:使用RFC 5987标准的 filename*=UTF-8''{编码后的文件名} 格式

通过本文的学习,你应该能够掌握:

  • Apache PDFBox 的使用方法和 PDF 生成流程
  • Markdown 正则解析的技术方案
  • Spring Boot 文件下载接口的设计规范
  • 前端 Blob 文件下载的实现原理
  • 跨语言数据传输中精度丢失问题的解决方案
  • 批量文件打包(ZIP)的技术实现

祝你开发顺利!

最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏