互操作

速览

NextPDF Pro 提供一套带版本的结果数据传输对象（DTO），它们将 PDF 分析输出 —— 文档信息、页面、文本块、分段和表单数据 —— 序列化为一种稳定、模式锁定的 JSON 形态，供外部系统和工具消费。

可用性与授权

此能力随 NextPDF Pro（nextpdf/pro）一同发布，并通过 Pro 层级的授权信封激活。缺少该授权的部署不会加载此能力的类。Interop 是 Pro 版本的一部分；不存在单独的按功能授权标志。比较各版本并获取授权。

安装

composer require nextpdf/pro:^3

概念概述

当 PDF 处理输出跨越进程或服务边界时，接收方需要一份稳定的契约。Interop V1 接口提供了这一点：

• InteropResultInterface —— 每个结果 DTO 都实现它。每个 DTO 都序列化为一个始终携带 schema_version 键的 JSON 安全数组，以及一个 JSON 字符串。
• 结果 DTO —— DocumentInfo、PageInfo、BoundingBox、ExtractedText / ExtractedPage / TextBlock、DocumentSegmentation / Segment，以及 FormData / FormField。每一个都是某一分析结果的不可变视图。
• SchemaLock —— 一个 CI 守卫。它持有被冻结模式的 SHA-256，并在模式文件发生改变而没有相应的版本号提升时使构建失败，从而使线缆契约（wire contract）无法静默漂移。

Interop 接口是显式带版本的（SCHEMA_VERSION）。请将其视为一份公共 API 契约：增量式变更提升模式版本；破坏性变更需要一个新的主版本。

为何如此设计

序列化形态被当作一份公共 API 契约，而非实现细节。每个 DTO 都携带一个 schema_version 键，因此消费方根据其收到的形态进行分支，而不是猜测。SchemaLock 在 CI 中钉住被冻结模式的 SHA-256，因此该格式在没有版本号提升的情况下无法漂移。正是这一点让外部系统能够安全地基于该 JSON 进行构建：契约仅随版本一同变动。输出保持可移植 —— 有文档、带版本、由你拥有的数据，而不是在你脚下变形的形态。

设计背景：开放内核，无锁定。

API 接口

类	职责
InteropResultInterface	通用序列化契约。
DocumentInfo、PageInfo、BoundingBox	通用的文档/页面 DTO。
ExtractedText、ExtractedPage、TextBlock	文本提取 DTO。
DocumentSegmentation、Segment	文档分段 DTO。
FormData、FormField	表单数据 DTO。
SchemaLock	CI 模式漂移守卫。

代码示例 —— 快速上手

$json = $result->toJson(JSON_PRETTY_PRINT);
$array = $result->toArray(); // includes 'schema_version'

代码示例 —— 生产环境

use NextPDF\Pro\Interop\V1\SchemaLock;

if (! SchemaLock::verify()) {
    throw new RuntimeException('Interop schema drift detected — version bump required.');
}
$payload = $result->toArray();
$httpClient->postJson($endpoint, $payload);

边界情况与注意事项

• toArray() 始终包含 schema_version；下游消费方应基于它进行分支。
• 如果模式文件缺失或被修改，SchemaLock::verify() 返回 false。
• 这些 DTO 是只读视图；它们不会重新运行分析。

性能

序列化随结果图（result graph）的大小呈线性。

安全说明

DTO 只携带你所填充的分析输出。序列化期间不发生任何文件系统或网络 I/O。

一致性

Interop 定义了一个 NextPDF 自有的带版本模式；它不实现任何外部标准。

行为契约

• 每个结果 DTO 都实现 InteropResultInterface，并序列化为一个始终携带 schema_version 键的 JSON 安全数组，以及一个 JSON 字符串。
• 结果 DTO（DocumentInfo、PageInfo、BoundingBox、ExtractedText/ExtractedPage/TextBlock、DocumentSegmentation/Segment、FormData/FormField）是不可变的只读视图；它们不会重新运行分析。
• SchemaLock::verify() 持有被冻结模式的 SHA-256，并在模式文件缺失或被修改时返回 false，从而使线缆契约无法静默漂移。
• 该接口是显式带版本的（SCHEMA_VERSION）：增量式变更提升模式版本；破坏性变更需要一个新的主版本。
• 序列化期间不发生任何文件系统或网络 I/O。

Enterprise 边界说明

Enterprise 不改变 Interop 的行为。Enterprise 增加了更高层级的功能，单独编写文档；它们对于使用这些带版本的结果 DTO 并非必需。

Core 回退/替代方案

模式锁定、带版本的结果 DTO 没有 Core 等价物。这是一项 Pro 新增内容。

发布边界

本页仅描述外部可观察的行为以及受支持的公共 API 接口。内部命名空间路径、辅助类、机制表、运行手册文件名和工单前缀不在范围之内。

另请参阅

• Extraction —— 产出文本和分段结果。
• Form —— 产出表单数据结果。
• Interop —— 深度参考 —— 完整的 DTO 字段参考。