Java通过输入流高效获取PDF总页数

本文介绍使用 Apache PDFBox 库，从 InputStream（如网络响应流、文件流或内存流）中无需完全加载 PDF 到内存，即可准确、安全地获取其总页数的核心方法与最佳实践。

在企业级文档处理中，常常遇到一个看似简单却暗藏风险的需求：快速获取 PDF 文件的总页数。无论是来自网络响应的合同，还是本地存储的扫描件报表，如果直接将整个文件读入内存来数页数，对于动辄上百兆的文件而言，极易引发内存溢出问题。

那么，是否存在一种方法，既能准确获取页数，又能像“蜻蜓点水”一样只读取文件的结构信息，而不触及庞大的内容数据？答案是肯定的。关键在于采用流式解析（stream-based parsing）思路，仅读取 PDF 文件头部的目录和页面树结构，跳过图像、字体等具体内容。Apache PDFBox 库的 PDDocument.load(InputStream) 方法正是为此设计，它采用延迟加载策略，内存占用极低（通常小于 1MB），执行速度可达毫秒级。

推荐实现：封装健壮的流式页数统计工具类

下面是一个封装好的工具类，它安全、高效，并考虑了资源管理和异常处理。

import org.apache.pdfbox.pdmodel.PDDocument;
import java.io.IOException;
import java.io.InputStream;

public class PdfStreamPageCounter {
    /**
     * 从输入流安全获取 PDF 总页数
     * @param inputStream PDF 数据流（支持 FileInputStream, ByteArrayInputStream, HTTP 响应流等）
     * @return 页数（成功返回 ≥ 1；失败返回 0）
     */
    public static int getPageCount(InputStream inputStream) {
        if (inputStream == null) {
            return 0;
        }
        PDDocument document = null;
        try {
            // 关键：PDFBox 自动识别流格式，无需 reset() 或 mark()
            document = PDDocument.load(inputStream);
            return document.getNumberOfPages();
        } catch (IOException e) {
            // 捕获常见异常：损坏文件、加密PDF、IO中断、不支持的PDF版本
            System.err.println("Failed to read PDF page count: " + e.getMessage());
            return 0;
        } finally {
            // 必须关闭，释放资源（即使流由外部管理，document 内部仍持有缓冲区）
            if (document != null) {
                try {
                    document.close();
                } catch (IOException ignored) {
                    // close() 失败不影响主逻辑，静默忽略
                }
            }
        }
    }
}

重要注意事项

在实际使用中，有几个细节需要特别注意，它们直接关系到代码的健壮性和兼容性。

流可读性要求：PDFBox 要求 InputStream 支持 mark() 和 reset() 方法。如果你的原始流不支持（例如某些简单的 HTTP 响应流），务必先将其包装成 BufferedInputStream：

InputStream safeStream = new BufferedInputStream(inputStream);
int pages = PdfStreamPageCounter.getPageCount(safeStream);

加密 PDF 处理：如果 PDF 文件设置了打开密码，直接调用 load() 方法会抛出 InvalidPasswordException。此时需要使用带密码参数的重载方法：

document = PDDocument.load(inputStream, "user_password");

Maven 依赖：确保引入最新稳定版的 PDFBox 依赖，以获得最佳的性能和兼容性。

    org.apache.pdfbox
    pdfbox
    2.0.29 

性能与准确性对比：有些人可能会尝试用正则表达式匹配 /Type /Page 或者手动解析交叉引用表（XRef）来获取页数。这些方法虽然看似取巧，但很容易在遇到结构复杂的 PDF（如包含嵌套页面树、间接对象引用）时出错。PDFBox 的方案具备语义正确性，它严格按照 PDF 规范解析页面树结构，因此结果最为可靠。

使用示例：从 HTTP 流获取页数（Spring Boot 场景）

该工具类可以轻松集成到多种应用场景中。例如，在 Spring Boot 项目中，从远程 URL 获取 PDF 并统计页数：

import org.springframework.web.client.RestTemplate;
import java.io.InputStream;
import java.net.URL;

// 模拟从 URL 获取 PDF 流
public void fetchAndCountPages(String pdfUrl) {
    try {
        URL url = new URL(pdfUrl);
        InputStream stream = url.openStream(); // 或使用 RestTemplate + ResponseEntity
        int pageCount = PdfStreamPageCounter.getPageCount(stream);
        System.out.printf("PDF '%s' contains %d page(s)%n", pdfUrl, pageCount);
    } catch (Exception e) {
        System.err.println("Cannot fetch or parse PDF: " + e.getMessage());
    }
}

总结一下：PDDocument.load(InputStream).getNumberOfPages() 这套组合拳，堪称 Java 生态中处理此类需求的“标准答案”。它完美规避了内存瓶颈，兼容主流的 PDF 规范，API 设计也简洁明了。无论是构建文档预览系统、进行批量归档，还是做合规性校验，这都应该成为你的首选技术方案。