Gotenberg 開發者指南

概覽

Gotenberg 套件會將轉換工作委派給外部服務。應用程式碼應清楚劃定服務邊界：驗證輸入、組出 payload、送出請求、解析（resolve）結果，並處理服務失敗。

當你要建置 office 轉 PDF 的轉換流程、上傳 endpoint、服務健康檢查，或設計圍繞 nextpdf/gotenberg 的傳輸政策時，請參閱本指南。

架構邊界

層級	由誰擁有	職責	不應放在此處
上傳或文件來源	應用程式	授權呼叫端、驗證來源、選擇轉換政策。	服務 URL 或傳輸 pinning 決策。
格式偵測	`nextpdf/gotenberg`	將安全的副檔名對映到 `OfficeFormat`。	未經應用程式驗證就信任 MIME。
橋接層	`nextpdf/gotenberg`	組裝 multipart 請求、呼叫 Gotenberg、解析 PDF 回應。	領域查詢或儲存政策。
Gotenberg 服務	部署	把 office 文件轉換成 PDF。	PHP 應用程式的授權。
核心引擎	`nextpdf/nextpdf`	視需要匯入或合併已轉換的 PDF 資料。	Office 轉換。

執行期生命週期

階段	行為	開發者該做的事
建立組態	載入 API URL、timeout、最大大小、API key 與 pins。	不要把服務 URL 與 token 寫進原始碼。
輸入驗證	檢查檔案路徑、檔案大小、檔名、副檔名與 URL 安全性。	在派送前先拒絕不支援的輸入。
組出 payload	`GotenbergConvertPayload` 會組成 multipart 表單資料。	只有在安全時才保留原始檔名。
服務請求	橋接層會將請求送往 `/forms/libreoffice/convert`。	設定 timeout 與傳輸政策。
解析結果	`GotenbergResponseParser::parse()` 會回傳 PDF 位元組與中繼資料。	將非 PDF 或錯誤回應一律視為轉換失敗。

建議的應用程式結構

路徑	用途
`app/Pdf/Conversion/*`	封裝 `GotenbergBridge` 的應用程式包裝層。
`app/Pdf/Uploads/*`	上傳驗證、儲存與檔名政策。
`app/Pdf/ConversionPolicy/*`	大小、格式與服務選擇政策。
`tests/Pdf/Conversion/*`	格式、檔案、服務與傳輸測試。

將檔案驗證與轉換分開。轉換服務應接收已授權的輸入，同時仍以套件驗證作為縱深防禦。

<?php

use NextPDF\Gotenberg\GotenbergBridge;

final readonly class OfficeConversionService
{
    public function __construct(
        private GotenbergBridge $bridge,
    ) {}

    public function convertUploadedFile(string $safePath): string
    {
        $result = $this->bridge->convertFile($safePath);

        if (!$result->isValid()) {
            throw new RuntimeException('The conversion service did not return a valid PDF.');
        }

        return $result->pdfData;
    }
}

轉換模式

模式	API	使用時機	限制
轉換檔案路徑	`GotenbergBridge::convertFile()`	文件已存放在磁碟上。	路徑必須可讀取且通過政策核可。
轉換記憶體中的位元組	`GotenbergBridge::convertString()`	應用程式已從上傳或物件儲存取得位元組。	格式偵測仍由檔名主導。
直接組出 payload	`GotenbergConvertPayload`	測試或自訂傳輸程式碼需要 multipart 位元組。	讓 boundary 產生過程不受使用者輸入影響。
直接解析回應	`GotenbergResponseParser::parse()`	自訂 HTTP 呼叫仍需要沿用套件解析邏輯。	必須傳入預期的 `OfficeFormat`。

健康與就緒狀態

GotenbergBridge::isAvailable() 是就緒訊號。它不應是唯一的執行期防護。服務可能在就緒檢查時可用，下一次轉換卻仍然失敗。

檢查項目	用途	維運備註
組態有效性	偵測缺漏的 API URL。	在應用程式啟動或部署檢查時執行。
`/health` 可用性	偵測服務是否可連線。	用於就緒狀態儀表板。
小型 fixture 轉換	偵測 LibreOffice 故障或服務退化。	在排程的 smoke 測試中執行，不要每次請求都跑。
timeout 監控	偵測服務回應變慢的情況。	依格式與檔案大小追蹤。

擴充點

擴充點	用於	限制
PSR-18 `ClientInterface`	自訂 HTTP 用戶端行為。	必須遵循 PSR-18 的 response/exception 語意。
PSR-17 工廠	建立請求與串流。	建構橋接層時必需。
`HtmlSecurityPolicyInterface`	針對 HTML 輸入的解析層政策。	與 Gotenberg 安全政策互補。
`ResponseFactoryInterface`	以 pinned cURL 傳輸建構回應。	只有在使用套件的傳輸路徑時才需要。
`GotenbergSecurityPolicy`	驗證 URL、檔案大小、檔名與 pin。	將應用程式授權留在這一層之外。

開發工作流程

測試時先用 convertString()，讓 fixture 清楚可見。
只有在檔案系統路徑受控之後才加入 convertFile()。
將最大檔案大小設定在服務與基礎設施限制之下。
把 isAvailable() 當作就緒訊號，而非錯誤處理的替代品。
記錄檔名、格式、大小、狀態與耗時。不要記錄文件的位元組內容。
開放上傳 endpoint 前，先加入 timeout 與失敗模式的測試。

失敗處理

失敗	應在哪裡處理	建議的回應方式
不支援的副檔名	格式偵測。	在派送至服務前先拒絕。
不安全的檔名	安全政策。	拒絕，並依上傳命名政策進行正規化。
超大檔案	上傳政策與套件驗證。	在讀取或送出大型 payload 之前先拒絕。
Gotenberg 無法使用	橋接邊界。	視情況回傳可重試的應用程式錯誤。
非 PDF 回應	回應解析器。	視為轉換失敗，並記錄服務狀態。
pin 或 URL 驗證失敗	傳輸政策。	安全地關閉，並通知維運人員。

安全預設值

關注項目	預設值	何時應覆寫
逾時（timeout）	`30` 秒。	只有在量測過實際服務延遲後才調高。
最大檔案大小	`52,428,800` 位元組。	在公開或多租戶 endpoint 上應調低。
API 金鑰	空白。	為私有 Gotenberg 部署設定。
支援的格式	`docx`、`xlsx`、`pptx`、`odt`、`ods`、`odp`。	只有在 `OfficeFormat` 與解析器都支援時才新增格式。
pin 組	空白。	新增 pin 時，請一併加入備援 pin 與輪替程序。

測試檢查清單

格式測試需涵蓋支援與不支援的副檔名。
檔案測試需涵蓋缺漏、無法讀取、超大與不安全的檔名。
服務測試需涵蓋非 2xx 回應、無效的回應主體與傳輸例外。
安全測試需涵蓋政策禁止的私有服務 URL 或無效服務 URL。
timeout 測試需斷言已設定的 timeout 會傳入傳輸層。
fixture 測試應讓範例文件保持小型，且不含敏感資料。