Interop

Tổng quan nhanh

NextPDF Pro cung cấp một tập có phiên bản các đối tượng truyền dữ liệu kết quả (DTO) để tuần tự hóa đầu ra phân tích PDF — thông tin tài liệu, các trang, các khối văn bản, phân đoạn và dữ liệu biểu mẫu — sang một hình dạng JSON ổn định, khóa-schema, để được tiêu thụ bởi các hệ thống và công cụ bên ngoài.

Tính khả dụng & cấp phép

Năng lực này đi kèm trong NextPDF Pro (nextpdf/pro) và kích hoạt cùng một phong bì giấy phép bậc Pro. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. Interop là một phần của phiên bản Pro; không có cờ giấy phép riêng theo từng tính năng. So sánh các phiên bản và nhận giấy phép.

Cài đặt

composer require nextpdf/pro:^3

Tổng quan khái niệm

Khi đầu ra xử lý PDF đi qua một ranh giới tiến trình hoặc dịch vụ, bên nhận cần một hợp đồng ổn định. Bề mặt Interop V1 cung cấp điều đó:

• InteropResultInterface — mọi DTO kết quả đều triển khai nó. Mỗi DTO tuần tự hóa thành một mảng an-toàn-JSON luôn mang một khóa schema_version, và thành một chuỗi JSON.
• Các DTO kết quả — DocumentInfo, PageInfo, BoundingBox, ExtractedText / ExtractedPage / TextBlock, DocumentSegmentation / Segment, và FormData / FormField. Mỗi DTO là một góc nhìn bất biến của một kết quả phân tích.
• SchemaLock — một bảo vệ CI. Nó giữ giá trị SHA-256 của schema đã đóng băng và làm hỏng bản dựng nếu tệp schema thay đổi mà không có một bước nâng phiên bản tương ứng, để hợp đồng truyền tải không thể trôi dạt một cách âm thầm.

Bề mặt Interop được đặt phiên bản một cách tường minh (SCHEMA_VERSION). Hãy xem nó như một hợp đồng API công khai: các thay đổi mang tính bổ sung sẽ nâng schema; các thay đổi phá vỡ yêu cầu một phiên bản lớn mới.

Vì sao nó hoạt động theo cách này

Hình dạng tuần tự hóa được xem như một hợp đồng API công khai, không phải một chi tiết triển khai. Mọi DTO đều mang một khóa schema_version, để bên tiêu thụ rẽ nhánh theo hình dạng mà họ nhận được thay vì đoán. SchemaLock ghim giá trị SHA-256 của schema đã đóng băng trong CI, để định dạng không thể trôi dạt mà không có một bước nâng phiên bản. Đó là điều cho phép các hệ thống bên ngoài xây dựng dựa trên JSON một cách an toàn: hợp đồng chỉ dịch chuyển khi phiên bản dịch chuyển. Đầu ra vẫn khả chuyển — dữ liệu có tài liệu, có phiên bản mà bạn sở hữu, không phải một hình dạng thay đổi bên dưới bạn.

Nền tảng thiết kế: Open core, không khóa nhà cung cấp.

Bề mặt API

Lớp	Trách nhiệm
InteropResultInterface	Hợp đồng tuần tự hóa chung.
DocumentInfo, PageInfo, BoundingBox	Các DTO tài liệu/trang chung.
ExtractedText, ExtractedPage, TextBlock	Các DTO trích xuất văn bản.
DocumentSegmentation, Segment	Các DTO phân đoạn tài liệu.
FormData, FormField	Các DTO dữ liệu biểu mẫu.
SchemaLock	Bảo vệ CI chống trôi dạt schema.

Mẫu mã — Khởi đầu nhanh

$json = $result->toJson(JSON_PRETTY_PRINT);
$array = $result->toArray(); // includes 'schema_version'

Mẫu mã — Production

use NextPDF\Pro\Interop\V1\SchemaLock;

if (! SchemaLock::verify()) {
    throw new RuntimeException('Interop schema drift detected — version bump required.');
}
$payload = $result->toArray();
$httpClient->postJson($endpoint, $payload);

Trường hợp biên & lưu ý

• toArray() luôn bao gồm schema_version; các bên tiêu thụ hạ nguồn nên rẽ nhánh theo nó.
• SchemaLock::verify() trả về false nếu tệp schema bị thiếu hoặc bị sửa đổi.
• Các DTO là các góc nhìn chỉ-đọc; chúng không chạy lại phân tích.

Hiệu năng

Việc tuần tự hóa là tuyến tính theo kích thước của đồ thị kết quả.

Ghi chú về bảo mật

Các DTO chỉ mang đầu ra phân tích mà bạn điền vào. Không có I/O hệ thống tệp hay mạng nào xảy ra trong khi tuần tự hóa.

Sự phù hợp tiêu chuẩn

Interop định nghĩa một schema có phiên bản thuộc sở hữu NextPDF; nó không triển khai một tiêu chuẩn bên ngoài.

Hợp đồng hành vi

• Mọi DTO kết quả đều triển khai InteropResultInterface và tuần tự hóa thành một mảng an-toàn-JSON luôn mang một khóa schema_version, và thành một chuỗi JSON.
• Các DTO kết quả (DocumentInfo, PageInfo, BoundingBox, ExtractedText/ExtractedPage/TextBlock, DocumentSegmentation/Segment, FormData/FormField) là các góc nhìn chỉ-đọc bất biến; chúng không chạy lại phân tích.
• SchemaLock::verify() giữ giá trị SHA-256 của schema đã đóng băng và trả về false nếu tệp schema bị thiếu hoặc bị sửa đổi, để hợp đồng truyền tải không thể trôi dạt một cách âm thầm.
• Bề mặt được đặt phiên bản một cách tường minh (SCHEMA_VERSION): các thay đổi mang tính bổ sung sẽ nâng schema; các thay đổi phá vỡ yêu cầu một phiên bản lớn mới.
• Không có I/O hệ thống tệp hay mạng nào xảy ra trong khi tuần tự hóa.

Ghi chú ranh giới Enterprise

Enterprise không thay đổi hành vi của Interop. Enterprise bổ sung các tính năng bậc cao hơn được ghi tài liệu riêng; chúng không bắt buộc để sử dụng các DTO kết quả có phiên bản.

Phương án dự phòng / thay thế trong Core

Không có tương đương trong Core cho các DTO kết quả có phiên bản, khóa-schema. Đây là một bổ sung của Pro.

Ranh giới công bố

Trang này chỉ ghi tài liệu về hành vi có thể quan sát từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn không gian tên nội bộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook và tiền tố phiếu (ticket) đều nằm ngoài phạm vi.

Xem thêm

• Extraction — tạo ra các kết quả văn bản và phân đoạn.
• Form — tạo ra các kết quả dữ liệu biểu mẫu.
• Interop — Tham chiếu sâu — tham chiếu đầy đủ các trường DTO.