Output Pipeline — 深度参考

速览

本页是 NextPDF\Pro\OutputPipeline 公开接口的深度参考。内容涵盖清单构建与验证、拓扑执行顺序、重试与超时语义、恢复行为，以及 fail-closed 的 Pack 能力门控。它为每个公开符号说明参数、默认值与失败模式。先阅读 Output Pipeline 能力页面 以获取工作流指引。

可用性与授权

该能力随 NextPDF Pro（nextpdf/pro）提供，并通过 Pro 级授权信封激活。缺少该权益的部署不会加载此能力的类。比较版本并获取授权。

执行器与十种步骤类型中的七种不带任何按功能标志。另有三种步骤类型需要一项 Pack 能力：

步骤类型	清单值	所需能力	Pack
Redact	redact	pack.privacy.redact	Privacy Pack
Extract	extract	pack.intelligence.extract	Intelligence Pack
OCR overlay	ocr_overlay	pack.intelligence.searchable_pdf	Intelligence Pack

门控在执行时强制生效，采用 fail-closed，在步骤到达其解析器之前进行。未获授权的受门控步骤会产出一个 Failed 步骤结果，携带 SPEC-LIC-001 代码与所需能力；解析器绝不会被调用。未注入能力解析器的管线会拒绝每一个受门控步骤。

公开 API 范围

composer require nextpdf/pro:^3

nextpdf/premium 元包会安装 nextpdf/pro 代码；本模块位于 NextPDF\Pro\OutputPipeline 命名空间下。

符号	参数	默认行为	返回	抛出或失败于	备注
PipelineExecutor::__construct	StepResolverRegistry $registry, ?CapabilityResolverInterface $capabilityResolver = null	绑定内置的解析器注册表与可选的权益来源	PipelineExecutor	未声明	null 能力解析器会拒绝每个受 Pack 门控的步骤
PipelineExecutor::execute	PipelineManifest $manifest, array $variables = []	按拓扑顺序运行各步骤并聚合结果	PipelineResult	未声明；解析器失败会被捕获为 Failed 步骤结果	设计用于在异步作业 worker 内运行
PipelineManifest::__construct	string $id, array $steps, PipelineOptions $options = new PipelineOptions(), ?string $resumeFromStepId = null	在构造时验证步骤图	PipelineManifest	当步骤列表为空、步骤 ID 重复、依赖未知、存在环、输出类型不匹配或恢复步骤缺失时抛出 InvalidArgumentException；步骤超过 10 000 时抛出 OverflowException	所有验证在任何执行之前完成
PipelineManifest::topologicalOrder	无	将依赖排在被依赖者之前	list<PipelineStep>	未声明	对给定清单具有确定性
PipelineManifest::getStep	string $stepId	按步骤 ID 线性查找	?PipelineStep	未声明	未知 ID 返回 null
PipelineManifest::rootSteps	无	返回没有依赖的步骤	list<PipelineStep>	未声明	根步骤最先运行
PipelineManifestBuilder::create	string $manifestId	开始一个新的构建器	self	未声明	构造函数为私有；这是唯一入口
PipelineManifestBuilder::addStep	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], ?StepOutputType $outputType = null	追加一个步骤；null 输出类型会依据步骤类型推断	self	未声明	验证延迟到 build()
PipelineManifestBuilder::stopOnError	bool $stop = true	设置首次失败即停止	self	未声明	默认为 true
PipelineManifestBuilder::maxRetries	int $retries	设置每步的重试上限	self	未声明	默认为 0（不重试）
PipelineManifestBuilder::timeout	int $timeoutMs	设置全局管线超时	self	未声明	0 会禁用超时
PipelineManifestBuilder::resumeFrom	string $stepId	设置恢复点	self	未声明	该步骤必须在 build() 时存在
PipelineManifestBuilder::build	无	构造已验证的清单	PipelineManifest	同 PipelineManifest::__construct	—
PipelineOptions::__construct	bool $stopOnError = true, int $maxRetries = 0, int $timeoutMs = 0	不可变的执行选项	PipelineOptions	未声明	只读值对象
PipelineStep::__construct	string $id, PipelineStepType $type, array $parameters = [], array $dependsOn = [], StepOutputType $outputType = StepOutputType::Pdf	不可变的步骤定义	PipelineStep	未声明	直接构造会将所有类型的输出类型默认为 PDF
PipelineStep::isRoot	无	当步骤没有依赖时为 true	bool	未声明	—
PipelineStepType (enum)	—	十个字符串支撑的 case：generate、merge、split、inspect、compress、sign、convert，外加受门控的 redact、extract、ocr_overlay	—	—	每个内置操作对应一个 case
PipelineStepType::requiresPack	无	对 Redact、Extract 与 OcrOverlay 为 true	bool	未声明	所有其他 case 返回 false
PipelineStepType::requiredCapability	无	将受门控的 case 映射到其能力代码	?string	未声明	非门控 case 返回 null
PipelineStatus (enum)	—	五个 case：pending、running、completed、failed、cancelled	—	—	由管线结果与步骤结果共享
PipelineStatus::isTerminal	无	对 Completed、Failed 与 Cancelled 为 true	bool	未声明	Pending 与 Running 为非终止
StepOutputType (enum)	—	三个 case：pdf、json、metadata	—	—	驱动构建时的边验证
StepOutputType::forStepType	PipelineStepType $stepType	某步骤类型的默认输出类型	self	未声明	Inspect 与 Extract 映射为 JSON；所有其他类型映射为 PDF
StepOutputType::isCompatibleWith	self $expectedInput	同类型匹配或 PDF 输出时为 true	bool	未声明	辅助方法；PDF 是通用输入
PipelineContext::__construct	string $manifestId, array $variables = [], ?string $resumeFromStepId = null	每次运行的内存内上下文	PipelineContext	未声明	无 TTL、过期、持久化或后端存储
PipelineContext::setStepResult / ::getStepResult	string $stepId（set 时另加 StepResult）	记录或读取一个步骤结果	void / ?StepResult	未声明	尚未执行的步骤返回 null
PipelineContext::setStepOutput / ::getStepOutput	string $stepId（set 时另加 mixed）	存储或读取一个中间输出	void / mixed	未声明	缺失的输出返回 null
PipelineContext::hasStepResult	string $stepId	某步骤是否已执行	bool	未声明	支持恢复检查
PipelineContext::allStepResults	无	迄今记录的所有结果	array<string, StepResult>	未声明	以步骤 ID 为键
PipelineContext::isResume	无	该运行是否从某步骤恢复	bool	未声明	—
PipelineResult::isSuccess	无	仅当总体状态为 Completed 时为 true	bool	未声明	结果由执行器产出
PipelineResult::getStepResult	string $stepId	按 ID 查找一个步骤结果	?StepResult	未声明	被跳过或未知的步骤返回 null
PipelineResult::failedSteps	无	筛选出失败的步骤结果	list<StepResult>	未声明	全部成功时为空列表
StepResult::isSuccess	无	仅当步骤状态为 Completed 时为 true	bool	未声明	携带 stepId、type、status、durationMs、error、output
CapabilityResolverInterface::hasCapability	string $capability	对某一能力代码进行肯定式权益测试	bool	不得抛出	缺省即拒绝：未知、已过期或未映射的代码返回 false

入口点签名

final class PipelineExecutor
{
    public function __construct(
        private readonly StepResolverRegistry $registry,
        private readonly ?CapabilityResolverInterface $capabilityResolver = null,
    )

    public function execute(PipelineManifest $manifest, array $variables = []): PipelineResult
}

final class PipelineManifestBuilder
{
    public static function create(string $manifestId): self

    public function addStep(
        string $id,
        PipelineStepType $type,
        array $parameters = [],
        array $dependsOn = [],
        ?StepOutputType $outputType = null,
    ): self

    public function stopOnError(bool $stop = true): self

    public function maxRetries(int $retries): self

    public function timeout(int $timeoutMs): self

    public function resumeFrom(string $stepId): self

    public function build(): PipelineManifest
}

interface CapabilityResolverInterface
{
    public function hasCapability(string $capability): bool;
}

行为契约

清单验证

验证在 PipelineManifest 构造函数中运行，先于任何执行。依次为：步骤列表必须非空；步骤数量上限为 10 000，将对抗性的深层依赖链转化为可捕获的 OverflowException，而非原生栈耗尽；步骤 ID 必须唯一；每个 dependsOn 引用都必须能够解析；依赖图必须无环；输出类型必须兼容；已声明的恢复步骤必须存在。每一项违规都会以具体消息抛出 InvalidArgumentException。

输出类型检查适用于类型映射为 PDF 输出的步骤：此类步骤的每个依赖本身都必须产出 PDF 输出。指向产出 JSON 的步骤类型（inspect、extract）的依赖边在本版本中不做类型检查。

执行顺序、恢复与超时

execute($manifest, $variables) 会构建一个全新的 PipelineContext，计算拓扑顺序，并按该顺序顺序运行各步骤。设置了恢复点后，先前的步骤会被跳过，直到到达指定步骤。被跳过的前驱不会被重新执行，其输出也不会被恢复：上下文是每次运行且在内存中的，因此一个恢复的步骤在读取被跳过前驱的输出时会得到 null。

全局超时为正值时，会在步骤之间、每个步骤启动前被求值。到期时管线状态变为 Failed，其余步骤不再启动。已在运行中的步骤绝不会在执行途中被中断，因此单个长步骤可能超出预算。

重试与失败捕获

每个步骤最多获得 maxRetries + 1 次尝试。成功的尝试会立即返回。任何失败的尝试——来自解析器的 Failed 结果，或抛出的 Throwable——只要还有尝试次数就会被重试；返回最后一次尝试的结果。解析器内部抛出的 Throwable 会被降级为一个 Failed 步骤结果，携带异常消息，或在消息为空时携带 Unknown error。因此 execute() 始终返回一个 PipelineResult；它绝不会向上传播解析器失败。

未注册解析器的步骤类型会产出一个带有明确消息的 Failed 步骤结果；运行不会被中止。当 stopOnError 为 true（默认）时，执行会在首个失败步骤处停止，且管线状态为 Failed。当其为 false 时，执行会继续，若有任一步骤失败则最终状态为 Failed，否则为 Completed。

Pack 能力门控

在任何解析器分发之前，每个受 Pack 门控的步骤（Redact、Extract、OcrOverlay）都会针对注入的 CapabilityResolverInterface 进行检查。门控采用 fail-closed：解析器缺失、false 回答或未映射的能力代码都会拒绝该步骤。拒绝会产出一个 Failed 步骤结果，其 error 携带 SPEC-LIC-001 代码、步骤类型与所需能力。受门控的拒绝不消耗任何重试次数，并报告 0.0 的耗时。解析器的实现必须仅在权益被肯定持有时返回 true，且不得抛出。

结果聚合

PipelineResult 报告清单 ID、总体状态、按执行顺序的各步骤结果、以毫秒计的总耗时，以及总数、完成数与失败数。stepsTotal 统计清单中的每一个步骤，包括被恢复跳过的或停止后未到达的步骤；stepsCompleted 与 stepsFailed 仅统计已执行的步骤。

边界情况与失败模式

• 执行器设计用于在作业 worker 内异步执行。内联使用会令调用方在整个管线运行期间被阻塞。
• 全局超时是一项步骤之间的检查。单个长步骤可能超出预算；没有步骤会在执行途中被中断。
• 恢复仅在同一次执行内跳过步骤。它不会从任何存储恢复输出；带缓存输出的跨运行恢复未实现。
• 直接构造 PipelineStep 会将每种步骤类型的输出类型默认为 PDF。请使用构建器，或显式传入输出类型，以便 inspect 与 extract 步骤声明 JSON 输出，使边验证保持有意义。
• 消息为空的解析器异常会在步骤结果中被规范化为 Unknown error。
• 由门控或缺失解析器产出的 Failed 步骤结果报告 0.0 的耗时。
• PipelineResult::getStepResult() 对未知 ID 以及被恢复或停止跳过的步骤都返回 null；可通过 stepsTotal 与结果列表长度的对比来区分。
• 本模块不执行任何密码学操作，也不定义任何 FIPS 特定行为。sign 步骤的 FIPS 态势由签名模块管控，而非由管线管控。

一致性

管线自身不做任何格式一致性工作。每个产出物的一致性由执行该步骤背后的模块——签名、优化、转换等——负责，并记录在这些模块的参考页面上。本页不主张任何外部条款标识；每一条陈述都以产品源码为依据。NextPDF 不作任何认证主张。

开发说明

• 模块源码标注 @since 2.2.0；本参考记录的是 nextpdf/pro 3.1.0 所发布的接口。
• 所有类均为 final；清单、选项、步骤与结果类型都是只读值对象。请构造新实例而非修改。
• StepResolverInterface 与 StepResolverRegistry 为 @internal。步骤解析器仅为内置；本版本不支持用户自定义的步骤处理器。
• CapabilityResolverInterface 是公开的权益接缝。实现必须缺省即拒绝，且不得默认放行。
• 这个 PHP 执行器是清单验证与顺序执行路径；生产部署可通过 sidecar 进行并行编排的分发。无论哪种方式，PHP 路径上的能力门控都是独立 fail-closed 的。
• 内部机制细节保留在源码仓库的内部文档中，不在本手册范围内。

发布边界

本页仅记录外部可观察的行为与受支持的公开 API 范围。内部命名空间路径、辅助类、机制表、runbook 文件名与工单前缀均不在范围内。

另请参阅

• Output Pipeline — 提供工作流指引的能力页面。
• Output Pipeline — NextPDF Enterprise 深度参考 — 跨清单的批量编排。
• Document — 深度参考
• Accelerator — 深度参考