Pro 版本

输出管线

概览

Output Pipeline 按依赖顺序运行一份声明式的 PDF 步骤清单，支持逐步重试以及一个出错即停选项。某些步骤类型需要额外的 Enterprise Pack 能力。

可用性与授权

此能力随 NextPDF Pro（nextpdf/pro）一同发行，并通过一份 Pro 级授权信封激活。缺少该权利的部署不会加载此能力的类。对比各版本并获取授权。

管线执行器本身属于 Pro 版本。另有三种步骤类型需要一个命名的 Enterprise Pack 能力：遮蔽步骤需要一个 Privacy Pack 能力，而提取与 OCR 叠加步骤需要 Intelligence Pack 能力。一个未授权的受限步骤会在执行时失败即关闭——它产出一个失败的步骤结果，且其 resolver 从不会被调用——而非中止整次运行。

安装

composer require nextpdf/pro:^3

代码位于 NextPDF\Pro\OutputPipeline 命名空间下。

概念概述

PipelineExecutor 接受一个 PipelineManifest，将各步骤排成拓扑顺序，并把每个步骤分派给一个注册在 StepResolverRegistry 中的 resolver。步骤输出被存储在一个 PipelineContext 中，供下游步骤使用。执行器强制一个全局超时、支持逐步重试，并可从一个命名步骤恢复。它被设计为在一个异步作业 worker 内运行，而非直接从请求处理器运行。

内置步骤类型包括 generate、merge、split、inspect、compress、sign 与 convert。遮蔽、提取与 OCR 叠加步骤类型是受能力授权的，并映射到 Enterprise Pack 能力。

为何如此设计

执行器仅负责编排。它对各步骤排序、强制执行授权门槛，并把每个步骤分派给一个已注册的 resolver，但本身不做任何 PDF 工作。这种拆分让同一份清单既可以走这条顺序的 PHP 路径，也可以走一个带外 worker——由后者并行分派各步骤——而调用代码无需改动。该设计瞄准的是一个异步作业 worker，而非请求处理器，因为一条多步骤管线常常会超出一次请求的预算，而一个队列通过增加 worker 来扩展吞吐量。全局超时在各步骤之间检查也是出于同一原因：一整个步骤是交给一个 resolver 的工作单元，而编排者不介入该 resolver 的运行。失败以逐步的 StepResult 值浮现，而非抛出异常，因此单个失败步骤绝不会拖垮 worker 汇报的聚合 PipelineResult。

设计背景：高吞吐量文档生成。

行为契约

execute($manifest, $variables) 返回一个带总体状态、逐步结果、时长，以及已完成与失败步骤计数的结果。
步骤按拓扑顺序运行；某个步骤类型缺失 resolver 会产出一个带有清晰消息的失败步骤。
PipelineOptions::$stopOnError 在首次失败时停止执行；否则执行继续，最终状态会反映任何失败。
全局超时（若已设置）会在下一个步骤开始前，若被超过则使管线失败。
逐步重试受所配置的最大值限制；只有非终止性失败才会被重试。
resume-from-step 会跳过更早的步骤，直到到达命名步骤。
受能力限制的步骤类型在缺少所需 Pack 能力时会以一个授权错误码在执行时失败即关闭；resolver 从不会被调用。

代码示例 —— 快速上手

以下反映已记录的公共 API。该仓库未为本模块发行可运行示例。

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$result = (new PipelineExecutor($stepResolverRegistry))->execute($manifest);

代码示例 —— 生产环境

use NextPDF\Pro\OutputPipeline\PipelineExecutor;

$executor = new PipelineExecutor($stepResolverRegistry);

// Invoke from an async job worker, not a request handler.
$result = $executor->execute($manifest, ['customerName' => 'Acme']);

if ($result->status !== \NextPDF\Pro\OutputPipeline\PipelineStatus::Completed) {
    foreach ($result->stepResults as $stepResult) {
        // Inspect per-step error detail.
    }
}

边界情况与注意事项

管线意在通过一个作业系统异步运行。内联运行它会在整条管线持续期间阻塞调用方。
一个没有已注册 resolver 的步骤类型会使该步骤失败，而不会中止整条管线（除非设置了出错即停）。
全局超时是在各步骤之间检查的，而非步骤中途；一个长时间运行的步骤可能在检查触发之前就超出预算。

性能

总时长是各步骤时长之和加上重试开销。全局超时限定最坏情况的墙钟时间。没有公布吞吐量数字；管线成本主要由你纳入的步骤决定。请用有代表性的清单来度量。

安全说明

执行器将输入文档与变量传递给步骤 resolver；请将它们视为不可信，并在每个 resolver 内校验。受能力限制的步骤在未授权时失败即关闭。执行器不记录任何文档内容。

一致性

执行器本身不执行任何格式一致性工作；一致性取决于各个步骤 resolver（generate、merge、split、sign、convert）。撰写时 RAG 语料库不可用，因此本页面不断言任何外部条款标识符。

Enterprise 边界说明

Enterprise 在行为层面增加了解锁受限步骤类型（遮蔽、提取、OCR 叠加）的 Pack 能力。没有那些 Pack，管线仍会运行每一个非受限步骤。Pack 内部细节不在此处范围内。

Core 回退/替代方案

没有 Pro 时，请用 NextPDF Core 的 API 命令式地编排 PDF 操作；声明式清单、依赖排序与重试是 Pro 新增能力。

发布边界

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