NextPDF Gotenberg 的启动与发现

速览

该桥接器本身没有任何自动发现机制。它是一个普通服务，需要你通过显式的构造函数注入来构造：一个配置值对象，外加若干 PSR HTTP 协作者。本包不附带任何服务提供者、任何 bundle，也没有任何容器扩展；它本身也不会读取任何环境变量。在这里，「发现」指的是宿主框架如何提供这些协作者，这是框架的职责，并非本包的职责。

桥接器是如何被发现的

它不会被自动发现，需要由你来构造。GotenbergBridge 需要四个参数，并接受三个可选参数：

必填：一个 GotenbergConfig、一个 PSR-18 客户端、一个 PSR-17 请求工厂、一个 PSR-17 流工厂。
可选：一个 PSR-3 日志记录器、一个 HTML 安全策略（默认为 NextPDF 核心的默认策略），以及一个 PSR-17 响应工厂。

响应工厂是 cURL 锁定传输的启用开关。提供它后，只要存在可锁定对象（已解析的地址或已配置的 SPKI 锁定项），桥接器就会使用锁定传输。省略它时，则始终使用注入的 PSR-18 客户端。完整的参数契约见 /integrations/gotenberg/configuration/.

启动序列

没有注册步骤。其生命周期如下：

宿主解析出一个 PSR-18 客户端和若干 PSR-17 工厂。该步骤由宿主容器完成；本包不做这件事。
应用程序从自己的配置源构建一个 GotenbergConfig。GotenbergConfig::fromArray() 接受一个 snake_case 数组，并会用默认值替换格式错误的值，从而容忍这类输入。请在你的启动路径中校验该配置源，这样缺失的 URL 会在启动时失败，而不是在每次转换时失败。
应用程序用配置和协作者构造 GotenbergBridge。
首次转换调用会执行 URL 校验、SSRF 与文件名筛查，并发起请求本身。构造时不会执行任何工作；在你调用它之前，桥接器始终保持惰性。

容器绑定

本包不附带任何容器绑定。若要让该桥接器可被注入，请按如下方式将其注册到你的宿主应用程序容器中：

从你的配置源绑定 GotenbergConfig。
将 PSR-18 客户端和 PSR-17 工厂绑定到你所选的实现。
将 GotenbergBridge 绑定为一个接收上述各项的服务。

框架原生的自动接线、配置发布，以及服务提供者或 bundle 注册，都由专门的框架集成包提供，不在这里。本包有意保持与框架无关。它仅依赖 PSR 接口，因此可在任何容器下工作。

配置解析顺序

本包本身不读取任何配置。解析顺序就是你的应用程序在调用 GotenbergConfig::fromArray() 或构造函数之前所实现的那一套顺序。一种常见顺序是：环境变量，然后是已发布的配置文件，最后是代码中的默认值。那套顺序是你的应用程序契约，并非本包契约。本包真正定义的是：当传给 fromArray() 的数组省略某个字段时，该字段的 默认值：空的 API URL、30 秒超时、50 MiB 大小上限、空的 API 密钥、空的锁定项列表。

诊断

有两个内置信号可用于确认接线情况：

isAvailable() 会先在不产生任何网络流量的情况下校验 URL，然后向 <apiUrl>/health 发送一个 HEAD 请求，并在状态码低于 500 时报告为可用。发生任何失败时，它都会返回 false，而不是抛出异常。请在就绪检查中调用它。
用一个已知良好的小文档执行一次冒烟转换，可以端到端地确认整条路径。这包括向 <apiUrl>/forms/libreoffice/convert 发起的 multipart 请求，以及响应校验。

另请参阅

/integrations/gotenberg/integration/ — 通过该服务驱动 NextPDF 流水线。
/integrations/gotenberg/install/ — 包与服务的安装。
/integrations/gotenberg/configuration/ — 完整的构造函数与配置契约。
/integrations/gotenberg/overview/ — 转换流程与依赖模型。