如何通过PDFBox程序化捕获异常PDF加载时的警告并获取告警信息

• PDFBox 本身没有提供内置属性，用于存储、读取文档加载阶段产生的所有警告信息
• 要捕获加载过程的警告，2.x 版本需要通过接管对应模块的日志输出来实现，3.x 版本可以通过加载方法内置的回调参数精准获取，完全不需要依赖 PDFBox-Preflight 组件

• 加载存在轻微内容错误的 PDF 时，PDFBox 会通过内置容错机制正常完成解析，仅输出日志级别的警告，不会抛出加载失败的异常

典型警告日志示例：
Dez 08, 2020 9:14:41 AM org.apache.pdfbox.pdfparser.COSParser validateStreamLength
WARNING: The end of the stream doesn't point to the correct offset, using workaround to read the stream, stream start position: 3141, length: 1674, expected end position: 4815

• 此前尝试使用 PDFBox-Preflight 组件校验警告，但该组件的核心定位是 PDF/A 标准合规性校验，会输出大量与加载容错无关的规则类报错，无法匹配仅捕获加载原生警告的需求

适配 PDFBox 2.x 版本 #

该版本所有解析阶段的警告都基于 java.util.logging 日志机制输出，可以通过给对应解析模块的 Logger 挂载自定义日志 Handler 的方式定向捕获警告：

• 实现逻辑：在执行 PDF 加载前，为 org.apache.pdfbox 包路径下的 Logger 绑定自定义 Handler，仅捕获 WARNING 级别的日志存入自定义集合，加载完成后立即移除 Handler，避免干扰项目其他模块的日志输出
• 示例代码：

// 定义容器存储捕获到的加载警告
List<String> loadWarnings = new ArrayList<>();
// 获取 PDFBox 解析模块对应的 Logger
Logger parserLogger = Logger.getLogger("org.apache.pdfbox");
// 自定义日志 Handler，专门抓取警告级日志
Handler warningCaptureHandler = new Handler() {
    @Override
    public void publish(LogRecord record) {
        // 仅收录 WARNING 及以上级别的日志
        if (record.getLevel().intValue() >= Level.WARNING.intValue()) {
            loadWarnings.add(String.format("[%s] %s", 
                record.getSourceClassName(), 
                record.getMessage()));
        }
    }
    @Override
    public void flush() {}
    @Override
    public void close() {}
};
// 绑定 Handler 后加载 PDF
parserLogger.addHandler(warningCaptureHandler);
PDDocument doc = PDDocument.load(new File(filename));
// 加载完成后解绑 Handler，避免全局日志干扰
parserLogger.removeHandler(warningCaptureHandler);
// 此时 loadWarnings 中即为本次加载捕获的全部警告

• 注意事项：如果项目中已经将 JUL 日志桥接为 SLF4J、Logback 等其他日志框架，需要在对应日志框架的拦截层实现定向捕获，直接绑定原始 JUL Logger 可能无法拿到日志内容

适配 PDFBox 3.x 版本 #

3.x 版本重构了加载入口，不再完全依赖日志输出警告，而是提供了内置的警告回调接口，可以在加载时直接传入监听逻辑，实现零侵入捕获：

• 实现逻辑：使用 Loader.loadPDF() 的重载方法，在参数中传入警告事件的监听逻辑，所有解析过程产生的警告都会直接回调到监听方法中，不需要接管全局日志
• 示例代码：

List<String> loadWarnings = new ArrayList<>();
// 加载 PDF 时传入警告监听逻辑
PDDocument doc = Loader.loadPDF(
    new File(filename),
    null, // PDF 加密密码，无密码则传 null
    MemoryUsageSetting.setupMainMemoryOnly(), // 内存使用配置
    warningEvent -> loadWarnings.add(warningEvent.getMessage())
);
// 加载完成后 loadWarnings 中即为本次加载捕获的全部警告

不推荐方案澄清 #

• 不要使用 PDFBox-Preflight 做警告捕获：该组件的校验规则是严格对齐 PDF/A 文档标准，哪怕是完全可以正常打开的普通 PDF，也会输出大量关于字体、色彩配置、元数据的合规类报错，和「捕获加载时的内容流容错警告」的需求完全不匹配，会产生大量无效信息

内容的提问来源于stack exchange，提问作者tombo_189