my-pdf: opendataloader-pdf 代码迁移 + 裁剪方案¶
日期: 2026-05-30
状态: 设计阶段(待审批)
1. 目标¶
将 opendataloader-pdf 中 PDF → JSON → Markdown 链路及其依赖的 veraPDF 代码迁移到新项目 my-pdf,使用 my.pdf 作为统一 package。要求:Maven 单模块可编译,精确裁剪不需要的代码。
2. 范围¶
2.1 保留¶
PDF 文件
→ DocumentProcessor (veraPDF 解析 + WCAG 版面分析)
→ ExtractionResult (内部中间结构)
→ JsonWriter → JSON 输出
→ MarkdownGenerator → Markdown 输出
来自 opendataloader-pdf 的包:
- json/ — JSON 输出(含 serializers/)
- markdown/ — Markdown 输出(含 MarkdownHTMLGenerator)
- processors/ — 主解析管线,仅保留 DocumentProcessor 引用的 processor
- cli/ — CLI 入口
- utils/、entities/、exceptions/ 等支撑类
来自 veraPDF 的模块(精确裁剪后):
- parser — COS 对象模型、Content Stream 解析、PDDocument 加载
- wcag-validation — ChunkParser、SA 层结构元素
- wcag-algorithms — 全部实体模型 + 版面分析管线
- validation-model — GF COS 适配层(仅保留被引用的类)
- core — 少量基础类型(仅保留被引用的类)
- xmp-core — 极少量 ThreadLocal 容器类
2.2 砍掉¶
| 模块 | 原因 |
|---|---|
hybrid/ (18 文件) |
不需要 hybrid 模式 |
html/ (3 文件) |
不需要 HTML 输出 |
text/ (1 文件) |
不需要纯文本输出 |
pdf/ (2 文件) |
不需要标注覆盖 PDF 输出 |
AutoTaggingProcessor |
不需要 tagged-pdf |
TaggedDocumentProcessor |
不需要结构树解析 |
HybridDocumentProcessor |
不需要 hybrid |
PDFStreamWriter |
tagged-pdf 内部实现 |
autotagging/ |
被 AutoTaggingProcessor 独占 |
| 整个 Apache PDFBox (~853 文件) | 唯一使用者 PDFWriter 已砍掉 |
veraPDF feature-reporting |
整模块排除 |
veraPDF metadata-fixer |
整模块排除 |
2.3 外部依赖(保留在 pom.xml 中)¶
| 依赖 | 来源 | 用途 |
|---|---|---|
com.fasterxml.jackson.core:jackson-databind |
odl-pdf | JSON 序列化 |
org.aspectj:aspectjrt + aspectjtools |
odl-pdf | AOP 编译时织入 |
org.mozilla:rhino |
veraPDF core | 待裁剪后判定 |
javax.xml.bind:jaxb-api + impl |
veraPDF core | 待裁剪后判定 |
net.sf.saxon:Saxon-HE |
veraPDF core | 待裁剪后大概率不需要 |
外部依赖的最终列表在阶段 4 据实确定。
3. 项目位置¶
4. 目录结构¶
my-pdf/
├── pom.xml
└── src/main/java/
└── my/pdf/
├── cli/ ← odl-pdf-cli
├── [odl-pdf-core 各子包] ← json/, markdown/, processors/, utils/, entities/, exceptions/
└── verapdf/ ← veraPDF 裁剪后全部
├── as/
├── containers/
├── cos/
├── exceptions/
├── factory/
├── gf/
├── io/
├── operator/
├── parser/
├── pd/
├── tools/
├── wcag/
└── xmp/
5. Package 映射¶
| 原始 package | 目标 package |
|---|---|
org.opendataloader.pdf.* |
my.pdf.* |
org.verapdf.* |
my.pdf.verapdf.* |
java.*, javax.* |
不变 |
com.fasterxml.*, org.aspectj.* |
不变 |
org.mozilla.*, net.sf.* |
不变 |
注:PDFBox 整棵砍掉,不需要映射。
6. 实施步骤¶
阶段 1:依赖扫描(产出精确文件清单)¶
- 从保留的 odl-pdf 入口文件(~80 个 .java)出发
- 提取所有
import org.verapdf.* - 将每个 import 映射到 competitors 下的具体源文件
- 递归追踪 veraPDF 模块间的内部交叉引用
- 输出完整的"可达文件集"清单
阶段 2:拷贝 + import 重写(Python 脚本一次性完成)¶
# 伪代码
for each file in reachable_set:
target_path = rewrite_path(file) # 目录 + package 映射
ensure_parent_dir(target_path)
copy_and_rewrite(file, target_path) # 逐行替换 package + import
重写规则:
^package org\.opendataloader\.pdf → package my.pdf
^package org\.verapdf → package my.pdf.verapdf
^import org\.opendataloader\.pdf → import my.pdf
^import org\.verapdf → import my.pdf.verapdf
(其他行不动)
阶段 3:边缘情况修复¶
- 代码中的 FQN 引用(
org.verapdf.xxx.Y形式)→ grep + 替换 META-INF/services/文件中的全限定类名 → 如有则同步改module-info.java→ 检查是否需要
阶段 4:pom.xml 编写¶
- 扫描新目录树中所有外部 import
- 编写 pom.xml(Java 11 + AspectJ 编译插件 + 外部依赖坐标)
mvn compile试编译
阶段 5:编译迭代修复¶
mvn compile循环修复,直到通过- 常见错误类型:
- 缺类 → 回到阶段 1 补充遗漏文件
- 缺外部依赖 → 补充 pom.xml
- import 遗漏 → 补充替换规则
阶段 6(可选):功能验证¶
- 用 PDF 测试 JSON → Markdown 输出,对比 odl-pdf 原始结果
7. 风险¶
| 风险 | 缓解 |
|---|---|
| veraPDF core/validation-model 内部耦合高,裁剪后编译通不过 | 阶段 1 先跑,如验证规则类大量相互引用,考虑保守保留 validation-model 全部 |
| AspectJ 织入导致切面相关类缺失 | 阶段 5 检查,必要时保留 DumpAspect 等 |
| 包名改后反射/配置字符串断裂 | 阶段 3 grep "org.verapdf 等字符串字面量 |
| 预估规模不准 | 阶段 1 产出实际清单后重新评估 |
8. 预估¶
| 来源 | 原始文件数 | 预估裁剪后 |
|---|---|---|
| odl-pdf | 111 | ~70 |
| veraPDF | ~1159 | ~600-800 |
| 合计 | ~1270 | ~700-900 |
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU