Hướng dẫn cho nhà phát triển Gotenberg

Tổng quan nhanh

Gói Gotenberg chuyển tác vụ chuyển đổi sang Portable Document Format (PDF) cho một dịch vụ bên ngoài. Trong mã ứng dụng, hãy giữ ranh giới dịch vụ đó thật rõ ràng: xác thực đầu vào, dựng payload, gửi yêu cầu, phân tích kết quả và xử lý lỗi dịch vụ.

Hãy dùng hướng dẫn này khi xây dựng quy trình chuyển đổi office sang PDF, endpoint tải lên, kiểm tra tình trạng dịch vụ hoặc chính sách truyền tải xoay quanh nextpdf/gotenberg.

Ranh giới kiến trúc

Lớp	Thuộc về	Trách nhiệm	Đừng đặt ở đây
Nguồn tải lên hoặc tài liệu	Ứng dụng	Cấp quyền cho bên gọi, xác thực nguồn và chọn chính sách chuyển đổi.	Quyết định về endpoint dịch vụ hoặc pinning truyền tải.
Phát hiện định dạng	`nextpdf/gotenberg`	Ánh xạ các phần mở rộng an toàn sang `OfficeFormat`.	Tin vào media type đã khai báo mà không xác thực ở phía ứng dụng.
Bridge	`nextpdf/gotenberg`	Dựng yêu cầu multipart, gọi Gotenberg và phân tích phản hồi PDF.	Truy vấn miền hoặc chính sách lưu trữ.
Dịch vụ Gotenberg	Triển khai	Chuyển đổi tài liệu office sang PDF.	Cấp quyền trong ứng dụng Hypertext Preprocessor (PHP).
Engine lõi	`nextpdf/nextpdf`	Nhập hoặc gộp dữ liệu PDF đã chuyển đổi khi cần.	Chuyển đổi office.

Vòng đời thời gian chạy

Giai đoạn	Hành vi	Hành động của nhà phát triển
Tạo cấu hình	Endpoint application programming interface (API), thời gian chờ, kích thước tối đa, API key và các pin được nạp từ cấu hình.	Hãy để endpoint dịch vụ và token ở ngoài mã nguồn.
Xác thực đầu vào	Đường dẫn tệp, kích thước tệp, tên tệp, phần mở rộng và độ an toàn của Uniform Resource Locator (URL) đều được kiểm tra.	Hãy từ chối đầu vào không được hỗ trợ trước khi gửi đi.
Dựng payload	`GotenbergConvertPayload` dựng dữ liệu form multipart.	Chỉ giữ lại tên tệp gốc khi nó an toàn.
Yêu cầu dịch vụ	Bridge gửi yêu cầu đến `/forms/libreoffice/convert`.	Cấu hình thời gian chờ và chính sách truyền tải.
Phân tích kết quả	`GotenbergResponseParser::parse()` trả về các byte PDF và metadata.	Hãy xem các phản hồi không phải PDF và các phản hồi lỗi là lỗi chuyển đổi.

Cấu trúc ứng dụng được khuyến nghị

Đường dẫn	Mục đích
`app/Pdf/Conversion/*`	Lớp bao bọc ở phía ứng dụng quanh `GotenbergBridge`.
`app/Pdf/Uploads/*`	Xác thực tải lên, lưu trữ và chính sách tên tệp.
`app/Pdf/ConversionPolicy/*`	Chính sách về kích thước, định dạng và lựa chọn dịch vụ.
`tests/Pdf/Conversion/*`	Các bài kiểm thử về định dạng, tệp, dịch vụ và truyền tải.

Hãy tách xác thực tệp khỏi chuyển đổi. Dịch vụ chuyển đổi của bạn nên nhận đầu vào đã được cấp quyền, đồng thời vẫn dựa vào phần xác thực của gói như một lớp phòng thủ chiều sâu.

<?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;
    }
}

Các mẫu chuyển đổi

Mẫu	API	Dùng khi	Ràng buộc
Chuyển đổi từ đường dẫn tệp	`GotenbergBridge::convertFile()`	Tài liệu đã được lưu sẵn trên đĩa.	Đường dẫn phải đọc được và đã được chính sách phê duyệt.
Chuyển đổi từ byte trong bộ nhớ	`GotenbergBridge::convertString()`	Ứng dụng của bạn đã có sẵn byte từ một lượt tải lên hoặc kho lưu trữ đối tượng.	Tên tệp vẫn quyết định việc phát hiện định dạng.
Dựng payload trực tiếp	`GotenbergConvertPayload`	Bạn cần các byte multipart cho bài kiểm thử hoặc mã truyền tải tùy chỉnh.	Hãy giữ việc tạo boundary ở ngoài đầu vào của người dùng.
Phân tích phản hồi trực tiếp	`GotenbergResponseParser::parse()`	Các lệnh gọi Hypertext Transfer Protocol (HTTP) tùy chỉnh vẫn cần phần phân tích của gói.	Bạn phải truyền vào `OfficeFormat` dự kiến.

Tình trạng và mức độ sẵn sàng

GotenbergBridge::isAvailable() là tín hiệu về mức độ sẵn sàng, không phải lớp bảo vệ thời gian chạy duy nhất của bạn. Một dịch vụ có thể vượt qua kiểm tra sẵn sàng nhưng vẫn thất bại ở lượt chuyển đổi tiếp theo.

Kiểm tra	Mục đích	Lưu ý vận hành
Tính hợp lệ của cấu hình	Phát hiện endpoint API bị thiếu.	Hãy chạy kiểm tra này khi khởi động ứng dụng hoặc trong các bước kiểm tra triển khai.
`/health` sẵn sàng	Phát hiện xem dịch vụ có truy cập được hay không.	Hãy dùng kiểm tra này cho các bảng theo dõi mức độ sẵn sàng.
Chuyển đổi fixture nhỏ	Phát hiện hành vi LibreOffice bị hỏng hoặc dịch vụ bị thoái lui.	Hãy chạy kiểm tra này trong các bài kiểm thử smoke theo lịch, không phải trên mỗi yêu cầu.
Giám sát thời gian chờ	Phát hiện hành vi dịch vụ chậm.	Hãy theo dõi theo định dạng và kích thước tệp.

Các điểm mở rộng

Điểm mở rộng	Dùng cho	Ràng buộc
PHP Standard Recommendation (PSR)-18 `ClientInterface`	Hành vi HTTP client tùy chỉnh.	Phải tuân thủ ngữ nghĩa phản hồi và ngoại lệ của PSR-18.
PSR-17 factories	Tạo request và stream.	Bắt buộc để dựng bridge.
`HtmlSecurityPolicyInterface`	Chính sách ở lớp phân tích cho các đầu vào Hypertext Markup Language (HTML).	Bổ trợ cho chính sách bảo mật của Gotenberg.
`ResponseFactoryInterface`	Dựng phản hồi cho truyền tải cURL có pinning.	Chỉ bắt buộc khi bạn dùng đường truyền tải của gói.
`GotenbergSecurityPolicy`	Xác thực URL, kích thước tệp, tên tệp và pin.	Hãy giữ phần cấp quyền ứng dụng ở ngoài lớp này.

Quy trình phát triển

Hãy bắt đầu với convertString() trong các bài kiểm thử để fixture luôn rõ ràng.
Chỉ thêm convertFile() sau khi các đường dẫn hệ thống tệp đã được kiểm soát.
Hãy giữ kích thước tệp tối đa thấp hơn giới hạn của dịch vụ và hạ tầng.
Hãy dùng isAvailable() cho các tín hiệu về mức độ sẵn sàng, chứ không thay thế cho việc xử lý lỗi.
Hãy ghi log tên tệp, định dạng, kích thước, trạng thái và thời lượng. Đừng ghi log các byte của tài liệu.
Hãy thêm các bài kiểm thử về thời gian chờ và chế độ lỗi trước khi bạn mở các endpoint tải lên.

Xử lý lỗi

Lỗi	Nơi nên được xử lý	Phản hồi được khuyến nghị
Phần mở rộng không được hỗ trợ	Phát hiện định dạng.	Hãy từ chối trước khi bạn gửi đến dịch vụ.
Tên tệp không an toàn	Chính sách bảo mật.	Hãy từ chối tệp đó và chuẩn hóa chính sách đặt tên khi tải lên.
Tệp quá kích thước	Chính sách tải lên và phần xác thực của gói.	Hãy từ chối trước khi đọc hoặc gửi payload lớn.
Gotenberg không khả dụng	Ranh giới bridge.	Trả về một lỗi ứng dụng có thể thử lại khi phù hợp.
Phản hồi không phải PDF	Bộ phân tích phản hồi.	Hãy xem đó là lỗi chuyển đổi và ghi lại trạng thái của dịch vụ.
Lỗi xác thực pin hoặc URL	Chính sách truyền tải.	Hãy fail closed và cảnh báo cho người vận hành.

Các giá trị mặc định an toàn

Vấn đề	Mặc định	Khi nào nên ghi đè
Thời gian chờ	`30` giây.	Chỉ tăng lên sau khi bạn đo được độ trễ thực tế của dịch vụ.
Kích thước tệp tối đa	`52,428,800` byte.	Hãy hạ thấp cho các endpoint công khai hoặc đa người thuê.
API key	Trống.	Thiết lập cho các bản triển khai Gotenberg riêng tư.
Các định dạng được hỗ trợ	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`.	Chỉ thêm các định dạng khi `OfficeFormat` và bộ phân tích hỗ trợ chúng.
Tập pin	Trống.	Hãy thêm pin kèm pin dự phòng và một quy trình luân chuyển.

Danh sách kiểm tra kiểm thử

Các bài kiểm thử về định dạng bao quát cả phần mở rộng được hỗ trợ và không được hỗ trợ.
Các bài kiểm thử về tệp bao quát các tệp bị thiếu, tệp không đọc được, tệp quá kích thước và tên tệp không an toàn.
Các bài kiểm thử về dịch vụ bao quát các phản hồi không phải 2xx, phần thân phản hồi không hợp lệ và các ngoại lệ truyền tải.
Các bài kiểm thử về bảo mật bao quát các URL dịch vụ riêng tư hoặc không hợp lệ khi chính sách cấm chúng.
Các bài kiểm thử về thời gian chờ khẳng định rằng thời gian chờ đã cấu hình được truyền tới lớp truyền tải.
Các bài kiểm thử về fixture giữ cho các tài liệu mẫu nhỏ gọn và không nhạy cảm.