Export4j

简体中文

English

简体中文

English

外观

Export4j 项目立项文档 ​

项目类型： 开源基础设施 / 文档生产引擎
首选实现语言： Java
构建工具： Gradle（多模块）
目标许可证： Apache License 2.0
文档性质： 初始立项与目标范围；当前项目已进入开发与分项验收阶段

本文保留初始规划及阶段目标，不作为已实现功能清单。当前支持范围、使用方式和剩余工作分别见文档导航、能力矩阵和能力缺口表。

1. 项目背景 ​

现有 PDF 生产方案通常存在以下问题：

  1. 底层 PDF 绘制 API 与高级排版逻辑耦合，难以扩展和替换。
  2. 不同编程语言的框架具有不同的文档模型和布局机制，跨语言迁移与统一抽象成本较高。
  3. PDF、DOCX 等格式在文档结构、布局语义和输出机制上存在差异，难以通过简单的格式转换接口统一处理。
  4. 复杂文档涉及字体度量、文字塑形、自动换行、表格布局、分页和资源管理，单纯封装现有 PDF 库无法满足通用排版引擎的设计目标。
  5. 部分成熟框架的许可证、商业使用限制或架构约束，不适合直接作为长期自主维护的项目基础。

因此，计划开发一套独立的文档生产引擎，采用模块化架构，将精确绘制、文档格式适配和高级排版能力分离，在复用成熟开源基础设施的同时，建立自主可控的核心模型与扩展体系。

2. 项目目标 ​

2.1 总体目标 ​

建设一套可扩展、可替换后端、支持多种文档格式的通用文档生产框架。

项目应具备以下核心能力：

  • 精确控制页面、文字、图形、图片和绘制坐标。
  • 支持基于约束的文档布局、文本换行、表格排版和自动分页。
  • 通过独立适配器支持不同文档格式的导入与导出。
  • 允许不同语言、不同实现的底层组件通过统一接口接入。
  • 提供可复现的排版结果、测试工具和扩展 API。
  • 采用 Apache-2.0 许可证发布自研项目代码，并对第三方依赖实施许可证审计。

2.2 项目定位 ​

本项目不是现有 PDF 库的简单封装，也不是对某个成熟框架的 Fork。

项目采用自主设计核心架构、复用成熟基础设施、独立实现关键排版算法的路线。

2.3 非目标 ​

第一阶段不以以下能力为交付目标：

  • 完整兼容 Microsoft Word 的全部排版行为。
  • 完整实现 PDF 规范的所有高级特性。
  • 从零实现字体解析、复杂文字塑形、图像解码和压缩算法。
  • 直接实现 PDF 数字签名、增量更新、完整 PDF 无损编辑等高级能力。
  • 以浏览器作为生产 PDF 的渲染引擎。
  • 一次性实现所有目标文档格式。

3. 总体架构 ​

系统采用分层、模块化设计，核心分为文档模型、布局引擎、精确绘制能力和格式适配器。

3.1 架构分层 ​

第一层：文档模型（Document Model）

负责表达文档的语义结构，包括：

  • 文档、章节与页面设置。
  • 段落、文本、字符样式和段落样式。
  • 表格、单元格、图片及其他内容元素。
  • 字体、颜色、资源引用和元数据。
  • 页眉、页脚、脚注、书签等高级结构。

该层不直接依赖 PDF 页面坐标、PDF 对象编号或具体后端 API。

第二层：布局引擎（Layout Engine）

负责将语义文档转换为确定的布局结果，包括：

  • 字体度量和文本测量。
  • 文本塑形与行布局。
  • 段落换行、对齐和缩进。
  • 约束布局与尺寸计算。
  • 表格列宽、行高及单元格布局。
  • 页面分割、自动分页和分页控制。
  • 页眉页脚、重复表头和页码处理。

布局引擎应与具体文件格式解耦，不在测量和布局阶段直接写入 PDF 文件。

第三层：精确绘制内核（Graphics Core）

负责统一表达精确绘制操作，包括：

  • 页面坐标和变换矩阵。
  • 路径、填充、描边和裁剪。
  • 文字与字形绘制。
  • 图片绘制及资源引用。
  • 颜色、透明度和图形状态管理。
  • Display List 的生成、存储和执行。

该层提供稳定的公共接口，并允许接入不同的输出后端。

第四层：格式适配器（Format Adapters）

分别负责不同格式的导入、导出和资源映射。

  • PDF：页面绘制、文件生成、PDF 内容分析和编辑能力。
  • DOCX：OOXML 文档结构的导入与导出。
  • SVG：矢量绘制输出。
  • Raster：测试、预览和图像输出。
  • 其他格式：后续按实际需求扩展。

不同格式之间不要求所有功能一一映射。对于无法无损转换的功能，应明确支持范围和信息损失。

3.2 核心数据流 ​

text
Document Model
      |
      v
Layout Engine
      |
      v
Layout IR
      |
      v
Display List
      |
      +------> PDF Backend
      |
      +------> SVG Backend
      |
      +------> Raster Backend

DOCX 采用独立的数据流：

text
DOCX / OOXML
      |
      v
DOCX Importer
      |
      v
Document Model
      |
      v
DOCX Exporter
      |
      v
DOCX / OOXML

DOCX 导出器可以复用文档模型、样式、字体和资源管理能力，但不应强制消费已经分页并转换为 PDF 式坐标的 Display List。

4. 技术选型 ​

4.1 核心技术栈 ​

项目初步选型说明
实现语言Java作为第一版核心实现语言
构建系统Gradle采用多模块构建
Java 版本Java 21 LTS初步基线，最终以依赖兼容性验证为准
目标许可证Apache-2.0自研代码统一采用
PDF 基础设施Apache PDFBox初期 PDF 输出及 PDF 处理
DOCX 基础设施JDK ZIP／安全 XML受支持 OOXML 语义子集的导入与导出
字体处理独立接口 + 兼容依赖评估字体解析、字形塑形与字体嵌入能力
测试体系JUnit + 结构验证 + 视觉回归检查正确性与兼容性
发布方式Maven Central 等待公共 API 稳定后实施

上述依赖属于候选方案，正式采用前必须验证具体版本、传递依赖许可证、Java 兼容性和目标功能覆盖情况。

4.2 依赖使用原则 ​

  1. 优先通过 Maven 或 Gradle 引入成熟开源库。
  2. 不以 Fork 现有项目作为核心开发路线。
  3. 不直接复制其他项目的实现代码、注释或测试代码。
  4. 将第三方依赖封装在内部模块之后，避免公共 API 泄漏具体实现类型。
  5. 核心模型与布局算法应由项目自主设计和实现。
  6. 只有在性能、兼容性或产品需求明确时，才考虑替换现有底层组件。
  7. 对直接依赖、传递依赖、字体、图像和测试资源持续进行许可证审计。

4.3 许可证策略 ​

项目整体采用 Apache-2.0 作为默认发布许可证。

第三方依赖应逐项审查其许可证、传递依赖条件、NOTICE 要求、专利条款及商业分发限制。

对于字体、图片和其他非代码资源，应独立记录其版权及使用条件。

MIT、BSD 等其他宽松许可证的依赖，可以在审查通过后使用，但不能仅凭许可证名称就认定所有使用场景均符合要求。

5. 模块规划 ​

建议采用以下多模块结构：

text
export4j/
├── export4j-api/                 # 公共 API
├── export4j-model/               # 文档语义模型
├── export4j-graphics-api/        # 精确绘制接口
├── export4j-graphics-core/       # 图形原语与 Display List
├── export4j-text-core/           # 文本测量与塑形接口
├── export4j-font-core/           # 字体抽象与资源管理
├── export4j-layout-model/        # 布局结果模型
├── export4j-layout-core/         # 布局与分页算法
├── export4j-components/          # 段落、表格、页眉、页脚
├── export4j-backend-pdf/         # PDF 输出后端
├── export4j-backend-svg/         # SVG 输出后端
├── export4j-backend-raster/      # 测试与预览后端
├── export4j-adapter-docx/        # DOCX 导入与导出
├── export4j-adapter-pdf/         # PDF 导入与编辑扩展
├── export4j-testing/             # 通用测试工具
├── export4j-conformance-tests/   # 格式及行为一致性测试
├── export4j-bom/                 # 依赖版本管理
└── examples/                    # 使用示例

模块拆分应遵循实际依赖关系逐步实施，不要求第一版一次性建立所有模块。

6. 核心 API 设计原则 ​

6.1 精确绘制接口 ​

统一封装绘制操作，例如：

  • 文档和页面生命周期。
  • 绘制路径、文字、字形和图片。
  • 图形状态、变换和裁剪。
  • 字体及图片资源注册。
  • 输出、刷新和资源释放。

业务代码和布局引擎不应直接操作 PDFBox 的具体类。

6.2 文档模型接口 ​

文档模型以语义结构为主，支持构建、修改、遍历和验证。

模型应明确区分文档级属性、段落级属性、字符级属性及资源引用，避免将所有样式都转换成绘制参数。

6.3 布局接口 ​

布局过程应分离测量与渲染：

  1. 测量可用空间与内容尺寸。
  2. 确定换行、组件尺寸和分页。
  3. 生成布局结果。
  4. 将布局结果转换为绘制指令。
  5. 由后端输出目标格式。

布局引擎应具备明确的约束模型、错误报告和可追踪的布局诊断信息。

6.4 格式适配器接口 ​

格式适配器应区分导入与导出，并声明格式支持范围。

对于不支持或无法无损转换的结构，应通过明确的诊断信息处理，而不是静默丢弃。

7. 研发路线 ​

阶段一：项目基础与 PDF 最小闭环 ​

目标：验证整体架构。

  • 建立 Gradle 多模块项目。
  • 定义 Document Model 和 Graphics API。
  • 实现基础绘制指令及 Display List。
  • 封装 PDFBox，输出包含文字、图形和图片的 PDF。
  • 建立文件结构验证和基础回归测试。

交付物：可运行的核心库、基础 API、示例程序和架构文档。

阶段二：字体与文本排版 ​

目标：实现可靠的文本布局。

  • 建立字体资源及字体度量接口。
  • 实现字体加载、字形映射和文字测量。
  • 实现普通文本换行、对齐、缩进和行距。
  • 支持中文与中英文混排。
  • 验证字体嵌入、Unicode 映射和字体回退。

交付物：可独立使用的文本排版模块和对应测试集。

阶段三：自动布局与分页 ​

目标：从精确绘制库升级为文档排版引擎。

  • 实现约束布局和组件尺寸测量。
  • 实现段落流式布局与自动分页。
  • 实现表格列宽计算、行高计算和跨页处理。
  • 支持页眉页脚、页码和重复表头。
  • 建立布局诊断和视觉回归机制。

交付物：可生成多页复杂报告的排版引擎。

阶段四：多格式支持 ​

目标：建立格式适配体系。

  • 实现 DOCX 导入和导出基础能力。
  • 实现 SVG 输出。
  • 增加 PDF 导入、内容分析或编辑扩展。
  • 明确不同格式之间的功能映射和损失规则。
  • 建立格式兼容性测试集。

交付物：可扩展的多格式文档处理框架。

阶段五：性能、稳定性与正式发布 ​

目标：形成可长期维护的开源项目。

  • 建立性能基准测试。
  • 优化大文档内存占用和资源缓存。
  • 验证并发使用与资源隔离。
  • 完善许可证清单、SBOM 和发布流程。
  • 稳定公共 API，发布正式版本。

交付物：正式版本、用户文档、开发文档及发布规范。

8. 测试与质量要求 ​

测试体系至少覆盖以下方面：

8.1 功能测试 ​

  • 页面尺寸、坐标和变换正确。
  • 文本测量与实际绘制结果一致。
  • 图片、路径和字体资源正确输出。
  • 自动分页与跨页表格符合预期。
  • 不支持的格式特性能够产生明确诊断。

8.2 格式测试 ​

  • PDF 文件能够被独立工具解析和渲染。
  • 字体嵌入、Unicode 文本提取和图片显示符合预期。
  • DOCX 导入导出能够验证支持范围内的结构。
  • 格式转换不会静默丢弃已声明支持的关键属性。

8.3 性能测试 ​

  • 单文档生成耗时。
  • 批量任务吞吐量。
  • 大文档峰值内存。
  • 字体与图片缓存效果。
  • 并发执行时的资源隔离。
  • 异常文档、超大图片和资源不足场景下的行为。

性能目标应在基准文档、硬件环境和并发规模确定后制定，不预设未经测量的性能指标。

9. 项目风险 ​

风险应对策略
排版引擎范围过大分阶段实现，优先普通文本、表格与分页
PDF 和 DOCX 语义差异使用不同后端与适配器，明确功能映射
字体与复杂文字处理困难复用成熟组件，先定义统一接口
第三方许可证不符合要求建立依赖清单与自动化许可证检查
底层依赖限制后续扩展将外部 API 封装在内部模块之后
不同阅读器渲染差异使用独立渲染器与视觉回归测试
公共 API 过早固化在核心模型稳定前采用明确的版本管理策略

10. 项目验收标准 ​

第一阶段至少应满足：

  1. 项目可以通过 Gradle 构建。
  2. 核心 API 不直接暴露 PDFBox 类型。
  3. 可以通过 Document Model 或 Graphics API 生成有效 PDF。
  4. 支持文字、图片、图形和基本页面设置。
  5. 基础输出能够通过独立 PDF 工具验证。
  6. 自研代码具备 Apache-2.0 许可证声明。
  7. 所有直接依赖和传递依赖均有许可证审查记录。
  8. 提供可执行示例和基础自动化测试。

后续阶段应分别增加文本排版、自动分页、复杂表格及多格式适配的验收标准。

11. 开源项目治理 ​

正式公开前，应建立以下项目规范：

  • LICENSE、README、CONTRIBUTING 和 CODE_OF_CONDUCT。
  • 第三方依赖许可证清单。
  • 发布版本与兼容性策略。
  • 公共 API 变更规则。
  • 自动化构建、测试和发布流程。
  • 安全漏洞反馈和依赖升级流程。
  • 设计决策记录（ADR），记录关键架构取舍。

12. 预期成果 ​

项目最终形成一套独立的文档生产基础设施，具备：

  • 自主可控的文档模型和布局引擎。
  • 可替换的精确绘制后端。
  • 可扩展的多格式导入与导出体系。
  • 基于宽松开源许可证的依赖策略。
  • 可复现的测试体系和持续演进的公共 API。

项目的核心竞争力不在于重复实现 PDF 文件格式，而在于建立统一的文档模型、可靠的排版算法、清晰的后端抽象和可长期扩展的多格式架构。