Как создать штрих‑кодовую подпись Java для PDF‑документов

Введение

В этом руководстве вы узнаете, как создать штрих‑кодовую подпись Java для PDF‑файлов с помощью GroupDocs.Signature. Независимо от того, нужно ли вам внедрить коды продуктов, идентификаторы аудита или любые структурированные данные в контракт, штрих‑кодовая подпись позволяет добавить машинно‑читаемую информацию, которую можно мгновенно отсканировать, при этом документ остаётся криптографически защищённым. Мы пройдём через настройку, код, кастомизацию и рекомендации по лучшим практикам, чтобы вы могли начать добавлять штрих‑кодовую подпись в свои PDF‑файлы за считанные минуты.

Быстрые ответы

  • Какая библиотека добавляет штрих‑кодовую подпись в Java? GroupDocs.Signature for Java.
  • Какой тип штрих‑кода лучше всего подходит для розничной торговли? GS1CompositeBar (отраслевой стандарт для отслеживания продуктов).
  • Нужна ли лицензия для продакшн? Да — требуется приобретённая лицензия GroupDocs.
  • Могу ли я добавить одновременно цифровую и штрих‑кодовую подписи? Абсолютно; комбинируйте их для безопасности и сканируемости.
  • Совместим ли код с Java 11 и новее? Да, API работает с JDK 8+.

Что такое create barcode signature java?

create barcode signature java относится к процессу программного внедрения штрих‑кода в PDF с помощью кода на Java. GroupDocs.Signature предоставляет простой API, который генерирует изображение штрих‑кода, размещает его на странице и сохраняет подписанный документ в одной бесшовной операции.

Почему использовать штрих‑кодовую подпись?

Штрих‑кодовая подпись предоставляет машинно‑читаемые метаданные внутри юридически подписанного PDF. Она обеспечивает мгновенную визуальную проверку, упрощает сканирование в цепочке поставок и позволяет downstream‑системам извлекать структурированные данные без открытия файла. Поддерживается более 60 форматов штрих‑кодов, а GS1CompositeBar может кодировать идентификаторы продуктов, серийные номера и коды партии в одном компактном символе — идеально для розничной торговли, здравоохранения и финансов.

Предварительные требования

  • Java Development Kit: JDK 8 или новее (Java 11, 17, 21 все работают).
  • Инструмент сборки: Maven или Gradle — выбирайте тот, который вам удобнее.
  • IDE: IntelliJ IDEA, Eclipse или VS Code.
  • Библиотека GroupDocs.Signature: Добавьте зависимость, как показано ниже.
  • Лицензия: Бесплатная пробная версия для разработки; приобретённая лицензия для продакшн.

Добавление GroupDocs.Signature в ваш проект

For Maven users, add this to your pom.xml:

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-signature</artifactId>
    <version>23.12</version>
</dependency>

For Gradle users, add this to your build.gradle:

implementation 'com.groupdocs:groupdocs-signature:23.12'

About licensing: GroupDocs offers a free trial that’s perfect for testing and development. You can download it from their releases page. When you’re ready for production, you’ll need to purchase a license or request a temporary one from the GroupDocs website. For detailed API usage see the API Reference, consult the Developer Guide for step‑by‑step instructions, and ask questions on the GroupDocs Forum. The same purchase link is also listed as the purchase page.

Как настроить GroupDocs.Signature в Java?

Класс Signature представляет документ и предоставляет методы для применения подписей, поиска контента и управления ресурсами. Создайте экземпляр Signature, чтобы открыть ваш PDF и подготовить его к подписанию. Класс Signature — это ядро GroupDocs.Signature, которое управляет загрузкой документа, обработкой ресурсов и процессом подписи, гарантируя безопасное и эффективное выполнение всех операций.

import com.groupdocs.signature.Signature;

// Point to your PDF file
Signature signature = new Signature("path/to/your/document.pdf");

Important: Always dispose of the Signature object after use—this releases file handles and frees memory.

Как настроить параметры штрих‑кодовй подписи?

Класс BarcodeSignOptions определяет каждый аспект штрих‑кода, который вы собираетесь внедрить, от полезной нагрузки данных до визуального стиля. Он служит контейнером для всех настроек, связанных со штрих‑кодом, таких как тип, размер, цвета и размещение. Ниже представлена минимальная конфигурация, создающая штрих‑код GS1CompositeBar, содержащий GTIN и серийный номер, а также демонстрирующая, как задать отступы и фон для оптимальной читаемости.

import com.groupdocs.signature.options.sign.BarcodeSignOptions;
import com.groupdocs.signature.domain.barcodes.BarcodeTypes;

// Create barcode with GS1 format data
BarcodeSignOptions options = new BarcodeSignOptions("(01)03212345678906/(21)A1B2C3D4E5F6G7H8");
options.setEncodeType(BarcodeTypes.GS1CompositeBar);

Строка "(01)03212345678906/(21)A1B2C3D4E5F6G7H8" следует стандарту GS1:

  • (01) = GTIN (глобальный идентификатор продукта)
  • 03212345678906 = фактический код продукта
  • (21) = идентификатор серийного номера
  • A1B2C3D4E5F6G7H8 = уникальный серийный номер

Вы можете заменить её любым текстом для QR‑кодов, Code128, DataMatrix и т.д. Поддерживается более 60 типов штрих‑кодов — см. документацию GroupDocs для полного списка.

Как позиционировать и настраивать штрих‑код?

Размещение и стилизация контролируются тем же объектом BarcodeSignOptions. Используйте setTop, setLeft, setWidth и setHeight для задания точных координат и размеров. Установка setAllPages(true) автоматически добавит штрих‑код на каждую страницу, а setPageNumber(1) — на конкретную страницу. Вы также можете вращать штрих‑код, добавить фон или отрегулировать отступы, чтобы он не перекрывал существующее содержимое.

// Set position and apply to all pages
options.setTop(200); // Set vertical position
options.setAllPages(true);

Для более точного расположения вы также можете привязать штрих‑код к определённой странице, повернуть его или добавить фон:

options.setLeft(100);        // 100 pixels from left edge
options.setTop(200);         // 200 pixels from top
options.setWidth(300);       // Barcode width in pixels
options.setHeight(100);      // Barcode height in pixels
options.setPageNumber(1);    // Only sign page 1 (removes setAllPages)

Визуальная кастомизация (цвета переднего/фонового плана, отступы, подписи) доступна через дополнительные свойства:

options.setMargin(new Padding(10));           // Add padding around barcode
options.setBackground(new Background());       // Set background color
options.setForeColor(Color.BLACK);            // Barcode color
options.setBackgroundColor(Color.WHITE);      // Background color

Как подписать документ штрих‑кодом?

Метод sign у экземпляра Signature применяет сконфигурированные параметры и записывает подписанный документ на диск. Он возвращает объект SignResult, который сообщает, сколько подписей было применено и возникли ли предупреждения. Этот метод обрабатывает всю низкоуровневую работу с PDF, поэтому вам не нужно напрямую использовать библиотеки PDF.

try {
    SignResult signResult = signature.sign(outputPath, options);
    System.out.println("Document signed successfully!");
    System.out.println("Signed document saved to: " + outputPath);
} finally {
    if (signature != null) {
        signature.dispose();
    }
}

Блок try‑finally гарантирует, что объект Signature будет освобождён даже при возникновении исключения, предотвращая утечки дескрипторов файлов.

if (signResult.getSucceeded().size() > 0) {
    System.out.println("Successfully added " + signResult.getSucceeded().size() + " signature(s)");
}

Полный рабочий пример

Объединив всё вместе, получаем метод, который загружает PDF, добавляет штрих‑код GS1CompositeBar и сохраняет подписанный файл:

import com.groupdocs.signature.Signature;
import com.groupdocs.signature.options.sign.BarcodeSignOptions;
import com.groupdocs.signature.domain.barcodes.BarcodeTypes;

public class BarcodeSigningExample {
    
    public void signPdfWithBarcode(String inputPath, String outputPath) {
        Signature signature = null;
        
        try {
            // Initialize signature
            signature = new Signature(inputPath);
            
            // Configure barcode
            BarcodeSignOptions options = new BarcodeSignOptions(
                "(01)03212345678906/(21)A1B2C3D4E5F6G7H8"
            );
            options.setEncodeType(BarcodeTypes.GS1CompositeBar);
            options.setTop(200);
            options.setAllPages(true);
            
            // Sign and save
            SignResult result = signature.sign(outputPath, options);
            
            System.out.println("Signing completed: " + result.getSucceeded().size() + " signature(s) added");
            
        } catch (Exception e) {
            System.err.println("Error signing document: " + e.getMessage());
            e.printStackTrace();
        } finally {
            if (signature != null) {
                signature.dispose();
            }
        }
    }
}

Этот метод готов к продакшн: он проверяет входные данные, управляет ресурсами и сообщает о результате.

Как добавить одновременно цифровую и штрих‑кодовую подписи?

Для максимальной безопасности сначала добавьте криптографическую цифровую подпись, а затем наложите штрих‑код. Цифровая подпись гарантирует целостность документа, а штрих‑код обеспечивает быструю визуальную проверку и машинно‑читаемые данные. Используйте класс DigitalSignOptions для первого шага, а затем примените BarcodeSignOptions, как показано выше.

// First, add digital signature
DigitalSignOptions digitalOptions = new DigitalSignOptions("certificate.pfx");
digitalOptions.setPassword("cert_password");
signature.sign(outputPath, digitalOptions);

// Then, add barcode on top
BarcodeSignOptions barcodeOptions = new BarcodeSignOptions("DATA");
barcodeOptions.setEncodeType(BarcodeTypes.QR);
signature.sign(outputPath, barcodeOptions);

Полученный PDF будет одновременно юридически обязательным (цифровая подпись) и мгновенно читаемым любым сканером штрих‑кодов.

Работа с различными типами штрих‑кодов

Переключение форматов штрих‑кодов так же просто, как изменение одного значения enum. Ниже пример, заменяющий GS1CompositeBar на QR‑код:

// Define barcode sign options with sample text
BarcodeSignOptions options = new BarcodeSignOptions("Sample Text");

// Assign specific barcode type
options.setEncodeType(BarcodeTypes.GS1CompositeBar);

А вот тот же переход для линейного штрих‑кода Code128:

options.setEncodeType(BarcodeTypes.QR);           // QR code
options.setEncodeType(BarcodeTypes.Code128);      // Code 128
options.setEncodeType(BarcodeTypes.DataMatrix);   // Data Matrix

Помните, каждый тип штрих‑кода имеет свои ограничения по объёму данных — QR‑коды могут хранить тысячи символов, тогда как Code39 ограничен только буквенно‑цифровыми символами.

Примеры из реального мира

Управление цепочкой поставок

Внедрение GS1CompositeBar в транспортные накладные позволяет сотрудникам склада сканировать номера заказов, пункты назначения и коды партии без открытия PDF.

BarcodeSignOptions options = new BarcodeSignOptions(
    "(01)" + gtin + "/(21)" + serialNumber + "/(10)" + batchNumber
);
options.setEncodeType(BarcodeTypes.GS1CompositeBar);

Документация в здравоохранении

QR‑коды на формах согласия можно сканировать для автоматической привязки документа к правильной карте пациента.

String patientData = "PATIENT_ID:" + patientId + "|DOC_TYPE:CONSENT|DATE:" + dateString;
BarcodeSignOptions options = new BarcodeSignOptions(patientData);
options.setEncodeType(BarcodeTypes.QR);

Финансовые услуги

Идентификаторы транзакций, закодированные в штрих‑коде, позволяют аудиторам проверять соответствие простым сканированием.

String complianceData = "TXN:" + transactionId + "|AGENT:" + agentId + "|BRANCH:" + branchCode;
BarcodeSignOptions options = new BarcodeSignOptions(complianceData);
options.setEncodeType(BarcodeTypes.PDF417);

Контроль качества в производстве

Отчёты инспекций, подписанные штрих‑кодами, содержащими номера партии и идентификаторы инспекторов, делают анализ причин мгновенным.

String qcData = "BATCH:" + batchNumber + "|INSPECTOR:" + inspectorId + "|RESULT:" + passFailStatus;
BarcodeSignOptions options = new BarcodeSignOptions(qcData);
options.setEncodeType(BarcodeTypes.DataMatrix);

Распространённые проблемы реализации

Проблема 1: Исключение «File is already in use»

Answer: The file remains locked if a previous Signature instance wasn’t disposed. Always wrap signing code in a try‑finally block and call signature.dispose().

Signature signature = null;
try {
    signature = new Signature(filePath);
    // ... your code ...
} finally {
    if (signature != null) {
        signature.dispose();
    }
}

Проблема 2: Штрих‑код не отображается в PDF

Answer: Verify that setTop/setLeft values are within page bounds, increase the barcode’s width/height, and ensure foreground/background colors contrast with the page background.

// Make sure dimensions are reasonable
options.setTop(100);      // Not 10000
options.setLeft(100);
options.setWidth(300);    // At least 200 pixels for readability
options.setHeight(100);

// Ensure contrast
options.setForeColor(Color.BLACK);
options.setBackgroundColor(Color.WHITE);

Проблема 3: Исключение «Invalid Barcode Data»

Answer: GS1 barcodes require strict parentheses notation. Use the correct Application Identifiers (e.g., (01), (21)) and avoid unsupported characters.

// Correct:
"(01)03212345678906/(21)ABC123"

// Incorrect:
"03212345678906ABC123"

Проблема 4: OutOfMemoryError при работе с большими PDF

Answer: Increase the JVM heap (-Xmx4G) and consider signing pages individually instead of using setAllPages(true) for very large documents.

java -Xmx2G -jar your-application.jar

Проблема 5: Сканирование штрих‑кода не удаётся

Answer: Ensure the barcode is at least 200 × 100 px, uses high contrast colors, and isn’t distorted by PDF compression.

// Increase size
options.setWidth(400);
options.setHeight(150);

// Maximize contrast
options.setForeColor(Color.BLACK);
options.setBackgroundColor(Color.WHITE);

// Add quiet zone (blank space around barcode)
options.setMargin(new Padding(10));

Безопасность и проверка

Являются ли штрих‑кодовые подписи безопасными?

A barcode alone isn’t cryptographically protected, so anyone could generate a new one. Pair it with a digital signature to guarantee both authenticity and scanability. The dual‑signature pattern (digital first, barcode second) gives you legal enforceability plus operational convenience.

Проверка данных штрих‑кода

After scanning, verify that the document’s digital signature is still valid and that the barcode payload matches expected patterns. Use GroupDocs’ search() API with BarcodeSearchOptions to extract and validate barcode content automatically.

public boolean validateScannedBarcode(String scannedData, String documentPath) {
    // Verify digital signature first
    if (!verifyDigitalSignature(documentPath)) {
        return false;
    }
    
    // Validate barcode format
    if (!scannedData.matches("(01)\\d{14}/(21)[A-Z0-9]+")) {
        return false;
    }
    
    // Check against database
    String productId = extractProductId(scannedData);
    return database.productExists(productId);
}

Соображения по производительности

Управление ресурсами

Always dispose of Signature objects after each operation to avoid memory leaks:

signature.dispose();

When processing many files, create and dispose a new Signature per document:

for (String filePath : documentPaths) {
    Signature signature = null;
    try {
        signature = new Signature(filePath);
        // ... signing logic ...
    } finally {
        if (signature != null) {
            signature.dispose();
        }
    }
}

Пакетная обработка

For small batches (< 100 files), sequential processing is simple:

for (String path : paths) {
    signDocument(path);
}

For larger workloads, parallel processing can speed things up—but monitor I/O pressure and limit threads to 4‑8:

paths.parallelStream().forEach(path -> signDocument(path));

Оптимизация памяти для больших PDF

Increase heap size, process pages individually, and clear references after each step. This prevents OutOfMemoryError on documents larger than 50 MB.

Кеширование параметров штрих‑кода

If you reuse the same barcode configuration across many files, cache the BarcodeSignOptions instance:

// Create once, reuse many times
private static BarcodeSignOptions createStandardBarcodeOptions(String data) {
    BarcodeSignOptions options = new BarcodeSignOptions(data);
    options.setEncodeType(BarcodeTypes.GS1CompositeBar);
    options.setTop(200);
    options.setAllPages(true);
    return options;
}

Расширенные возможности

Несколько подписей в одном документе

Add several barcodes (or mix with digital signatures) by calling sign multiple times with different option objects:

// Add QR code in top-left
BarcodeSignOptions qrOptions = new BarcodeSignOptions("https://example.com");
qrOptions.setEncodeType(BarcodeTypes.QR);
qrOptions.setTop(50);
qrOptions.setLeft(50);
signature.sign(outputPath, qrOptions);

// Add GS1 barcode in bottom-right
BarcodeSignOptions gs1Options = new BarcodeSignOptions("(01)03212345678906");
gs1Options.setEncodeType(BarcodeTypes.GS1CompositeBar);
gs1Options.setTop(700);
gs1Options.setLeft(400);
signature.sign(outputPath, gs1Options);

Динамическое содержимое штрих‑кода

Generate barcode data from document metadata, timestamps, or database lookups:

// Extract data from PDF or database
String orderId = extractOrderIdFromPdf(filePath);
String timestamp = LocalDateTime.now().format(DateTimeFormatter.ISO_DATE_TIME);
String barcodeData = String.format("ORDER:%s|TIME:%s", orderId, timestamp);

BarcodeSignOptions options = new BarcodeSignOptions(barcodeData);

Интеграция со Spring Boot

Expose a REST endpoint that receives a PDF, adds a barcode, and returns the signed file:

@Service
public class DocumentSigningService {
    public void signWithBarcode(MultipartFile file, String barcodeData) {
        // ... implementation ...
    }
}

Пример REST API

A minimal controller that delegates to the signing service:

@PostMapping("/sign-document")
public ResponseEntity<byte[]> signDocument(
    @RequestParam("file") MultipartFile file,
    @RequestParam("barcode") String barcodeData
) {
    // Sign document and return as byte array
}

Часто задаваемые вопросы

Q: Что такое штрих‑код GS1CompositeBar?
A: GS1CompositeBar combines linear and 2D components to store product IDs, serial numbers, and other data in a single scannable symbol, widely used in retail and logistics.

Q: Могу ли я использовать другие типы штрих‑кодов, кроме GS1CompositeBar?
A: Yes—GroupDocs.Signature supports over 60 types, including QR, Code128, DataMatrix, PDF417, and Aztec. Switch the setEncodeType() value to change the format.

Q: Нужна ли лицензия для продакшн‑использования?
A: A valid GroupDocs license is required for production deployments. A free trial is available for development and testing.

Q: Будут ли сканеры штрих‑кодов считывать коды из подписанных PDF?
A: Absolutely, provided the barcode is at least 200 × 100 px and has sufficient contrast. Smartphone scanning apps work on‑screen; hardware scanners work on printed copies.

Q: Как обрабатывать ошибки во время подписи?
A: Wrap your code in try‑catch blocks, log full stack traces, and always call signature.dispose() in a finally block to release resources.

Q: Могу ли я подписывать другие форматы документов?
A: Yes—GroupDocs.Signature also supports DOCX, XLSX, PPTX, images, and many more. Just change the input file extension; the API remains the same.

Q: Есть ли ограничения по размеру файла?
A: No hard limit, but documents over 50 MB may require a larger JVM heap and page‑by‑page processing to stay memory‑efficient.

Q: Как подписывать PDF, хранящиеся в облачном хранилище?
A: Download the file to a temporary local path, apply the signature, then upload it back to your cloud bucket. Clean up temporary files afterward.

Заключение

Теперь у вас есть полное, готовое к продакшн руководство по созданию штрих‑кодовй подписи Java для PDF‑документов. Комбинируя криптографические цифровые подписи с машинно‑читаемыми штрих‑кодами, вы получаете как юридическую enforceability, так и операционную эффективность в цепочках поставок, здравоохранении, финансах и производстве. Экспериментируйте с различными типами штрих‑кодов, интегрируйте код в существующие сервисы и исследуйте пакетную обработку для масштабных развертываний.

Последнее обновление: 2026-05-21
Тестировано с: GroupDocs.Signature 23.10 for Java
Автор: GroupDocs

String filePath = "YOUR_DOCUMENT_DIRECTORY" + "/sample.pdf";
String fileName = new java.io.File(filePath).getName();
String outputPath = "YOUR_OUTPUT_DIRECTORY" + "/SignedWithBarcodeGS1CompositeBar/" + fileName;

String documentDir = System.getenv("DOCUMENT_DIR");
String outputDir = System.getenv("OUTPUT_DIR");

Signature signature = new Signature(filePath);

Связанные руководства