如何使用條碼和 QR 代碼簽署 Java 檔案

介紹

有沒有想過如何使用 如何簽署 Java 技術來證明檔案未被竄改?或是需要一種以程式方式驗證文件而不需複雜加密設定的方法?傳統的數位簽章在某些情境下可能過於繁重。有時只需要一種輕量、可掃描的方式來驗證檔案完整性——尤其在處理壓縮檔、備份或自動化工作流程時。條碼與 QR 代碼簽章正是為此而生。

在本教學中,你將學習如何使用 GroupDocs.Signature 來實作 如何簽署 Java。我們將重點放在簽署 TAR 壓縮檔(非常適合備份系統與軟體發佈),但這些技術同樣適用於各種文件格式。無論你是構建文件管理系統,或只是想為檔案增添額外的安全層,這裡都是正確的起點。

你將學到的內容:

  • 在 Java 中可運作的條碼與 QR 代碼簽章實作
  • 了解何時使用各種簽章類型(以及其重要性)
  • 常見簽署挑戰的實用解決方案
  • 可立即使用的實務整合模式
  • 生產系統的效能最佳化技巧

讓我們開始吧——不需要密碼學學位。

快速回答

  • 什麼程式庫處理 Java 中的條碼簽章? GroupDocs.Signature for Java.
  • 哪種簽章類型能儲存更多資料? QR 代碼(最多 4,296 個字母數字字元)。
  • 我可以簽署大於 100 MB 的 TAR 檔案嗎? 可以——使用背景執行緒並增加 JVM 記憶體上限。
  • 需要網路連線嗎? 不需要,程式庫可完全離線運作。
  • 生產環境需要授權嗎? 需要,有效的 GroupDocs.Signature 授權是必須的。

什麼是 Java 數位簽章?

Java 數位簽章是將可驗證的視覺標記(例如條碼或 QR 代碼)直接嵌入由 Java 產生的檔案中,以證明其真偽與完整性,提供快速且人類可讀的證明,表明檔案自簽署以來未被修改,同時仍可透過 GroupDocs.Signature API 以程式方式驗證。

為什麼使用條碼或 QR 代碼簽章?

GroupDocs.Signature 支援 超過 50 種輸入與輸出格式(包括 PDF、DOCX、XLSX、HTML、PNG 與 TAR),且能在不將整個檔案載入記憶體的情況下處理數百頁的文件。條碼與 QR 代碼提供可掃描、獨立的真偽證明,省去許多內部工作流程中對外部憑證機構的需求。

因素條碼 (Code128)QR 代碼
資料容量~80 個字元最多 4,296 個字母數字字元
可讀性需要條碼掃描器可使用智慧手機相機
空間效率水平上更緊凑需要方形区域
適用情境簡單 ID、時間戳記、短碼URL、JSON 資料、詳細中繼資料
錯誤更正最小內建(可從損壞中恢復)

經驗法則:

  • 使用 條碼 以快速、可掃描的 ID 或時間戳記。
  • 在需要嵌入更豐富資料或希望支援智慧手機時,使用 QR 代碼。
  • 同時結合兩者以獲得最高的冗餘與稽核能力。

前置條件

  • GroupDocs.Signature for Java Library – 版本 23.12 或更新
  • Java Development Kit (JDK) – 版本 8 或以上
  • IDE – IntelliJ IDEA、Eclipse 或任何相容 Java 的編輯器
  • 基本的 Java 知識 – 你應該熟悉類別與匯入

環境設定

將 GroupDocs.Signature 加入專案相當簡單。選擇你的建置工具:

Maven(將以下內容加入 pom.xml):

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

Gradle(將以下內容加入 build.gradle):

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

手動下載:不使用 Maven 或 Gradle?直接從 GroupDocs.Signature releases 取得 JAR,並加入至 classpath。

授權取得

GroupDocs 提供彈性授權方案:

  • 免費試用:適合測試——不需信用卡。立即開始
  • 臨時授權:需要更多評估時間?申請臨時授權 以在開發期間取得完整功能。
  • 正式授權:當你準備部署時,根據需求購買授權。

其他有用連結

小技巧:先使用免費試用來原型化你的解決方案,若需要更多時間再決定,則取得臨時授權。

設定 GroupDocs.Signature for Java

Signature 類別是 GroupDocs.Signature 所有簽署操作的入口點。它代表載入記憶體的單一檔案,並提供新增、搜尋或刪除視覺簽章的方法。

建立指向 TAR 檔案的 Signature 實例。這會將檔案載入記憶體以供處理:

import com.groupdocs.signature.Signature;

public class InitializeSignature {
    public static void main(String[] args) {
        Signature signature = new Signature("your-document-path");
        // Additional setup and usage here...
    }
}

重要:完成後務必關閉 Signature 物件(或使用 try‑with‑resources),以避免大型檔案產生記憶體洩漏。

在條碼與 QR 代碼簽章之間的選擇

不確定要使用哪種簽章類型?以下是一個快速決策指南:

因素條碼 (Code128)QR 代碼
資料容量~80 個字元最多 4,296 個字母數字字元
可讀性需要條碼掃描器可使用智慧手機相機
空間效率水平上更緊凑需要方形区域
適用情境簡單 ID、時間戳記、短碼URL、JSON 資料、詳細中繼資料
錯誤更正最小內建(可從損壞中恢復)

經驗法則:

  • 使用 條碼 以快速、可掃描的 ID 或時間戳記。
  • 在需要嵌入更豐富資料或希望支援智慧手機時,使用 QR 代碼。
  • 同時結合兩者以獲得最高的冗餘與稽核能力。

實作指南

使用條碼簽署 TAR 壓縮檔

為什麼使用條碼簽署?

條碼非常適合 TAR 壓縮檔,因為它們緊湊且可掃描。你可以嵌入時間戳記、版本號、使用者 ID 或檢查碼,以快速驗證。

步驟

1. 初始化簽章
首先,為 TAR 檔案建立 Signature 實例:

import com.groupdocs.signature.Signature;

final Signature signature = new Signature("path/to/your/archive.tar");

小技巧:對於大於 100 MB 的 TAR 檔案,請在背景執行緒中執行簽署操作,以保持 UI 響應。

2. 設定條碼選項
BarcodeSignature 類別定義條碼內容、類型與放置位置。BarcodeOptions 物件保存這些設定:

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

BarcodeSignOptions bcOptions = new BarcodeSignOptions("12345678", BarcodeTypes.Code128);
bcOptions.setLeft(100);  // X position in pixels
bcOptions.setTop(100);   // Y position in pixels

BarcodeOptions 讓你指定條碼的視覺外觀與位置。
BarcodeTypes 是列出支援的條碼符號(如 Code128、Code39 等)的列舉。

這裡發生了什麼?

  • "12345678" 為條碼編碼的資料——請替換為實際的 ID、時間戳記或驗證碼。
  • BarcodeTypes.Code128 在資料容量與掃描可靠性之間取得平衡。
  • 位置值 (100, 100) 將條碼放置於左上角 100 像素處。

你可能想要的自訂選項:

bcOptions.setWidth(200);        // Barcode width in pixels
bcOptions.setHeight(50);        // Barcode height in pixels
bcOptions.setForeColor(Color.BLACK);  // Barcode color
bcOptions.setBackgroundColor(Color.WHITE);  // Background color

3. 簽署並儲存文件
執行簽署操作並儲存已簽署的壓縮檔:

import com.groupdocs.signature.domain.SignResult;

String outputFilePath = "output/path/SignWithBarcode/archive_signed.tar";
SignResult signResult = signature.sign(outputFilePath, bcOptions);

回傳的 SignResult 物件會告訴你操作是否成功以及簽章放置的位置。
常見問題:在呼叫 sign() 前確保輸出目錄已存在。程式庫不會自動建立上層目錄。

使用 QR 代碼簽署 TAR 壓縮檔

何時使用 QR 代碼

當需要儲存結構化資料(JSON、XML)、嵌入驗證 URL,或支援智慧手機掃描時,QR 代碼表現優異。

步驟

1. 初始化簽章
同前——建立 Signature 實例:

final Signature signature = new Signature("path/to/your/archive.tar");

2. 設定 QR 代碼選項
設定要嵌入的資料以建立 QR 代碼:

import com.groupdocs.signature.options.sign.QrCodeSignOptions;
import com.groupdocs.signature.domain.qrcodes.QrCodeTypes;

QrCodeSignOptions qrOptions = new QrCodeSignOptions("12345678", QrCodeTypes.QR);
qrOptions.setLeft(400);  // X position
qrOptions.setTop(400);   // Y position

QrCodeTypes 是指定要產生的 QR 代碼類型(標準 QR、DataMatrix、Aztec 等)的列舉。

實務範例 – 嵌入含驗證資料的 JSON 負載:

String verificationData = "{\"version\":\"1.0\",\"timestamp\":\"2025-01-02T10:30:00Z\",\"user\":\"john.doe\"}";
QrCodeSignOptions qrOptions = new QrCodeSignOptions(verificationData, QrCodeTypes.QR);

QR 代碼類型選項:

  • QrCodeTypes.QR – 標準 QR 代碼(最常見)
  • QrCodeTypes.DataMatrix – 針對小資料更緊湊
  • QrCodeTypes.Aztec – 適合曲面使用

3. 簽署並儲存文件
完成簽署流程,與條碼相同:

String outputFilePath = "output/path/SignWithQRCode/archive_signed.tar";
SignResult signResult = signature.sign(outputFilePath, qrOptions);

效能說明:由於錯誤更正計算,QR 代碼產生比條碼稍慢,但對大多數使用情境而言差異可忽略不計(通常僅幾毫秒)。

使用多重簽章簽署 TAR 壓縮檔

為什麼使用多重簽章?

  • 冗餘 – 若其中一個簽章受損,另一個仍可驗證。
  • 不同受眾 – 條碼供掃描器使用,QR 代碼供智慧手機使用。
  • 分層資料 – 條碼提供快速 ID,QR 代碼提供詳細中繼資料。
  • 合規 – 某些法規要求多種驗證方式。

步驟

1. 初始化簽章
同前的初始化方式:

final Signature signature = new Signature("path/to/your/archive.tar");

2. 設定多重選項
建立兩種簽章類型並將它們合併於清單中:

import java.util.ArrayList;
import java.util.List;

// Set up barcode (reusing from earlier example)
BarcodeSignOptions bcOptions = new BarcodeSignOptions("12345678", BarcodeTypes.Code128);
bcOptions.setLeft(100);
bcOptions.setTop(100);

// Set up QR code (different position to avoid overlap)
QrCodeSignOptions qrOptions = new QrCodeSignOptions("12345678", QrCodeTypes.QR);
qrOptions.setLeft(400);
qrOptions.setTop(400);

// Combine them
List<com.groupdocs.signature.options.sign.SignOptions> listOptions = new ArrayList<>();
listOptions.add(bcOptions);
listOptions.add(qrOptions);

小技巧:策略性地放置簽章——角落或不干擾的區域最適合用於 TAR 壓縮檔。

3. 簽署並儲存文件
將選項清單傳遞給 sign() 方法:

String outputFilePath = "output/path/SignWithMultipleSignatures/archive_signed.tar";
SignResult signResult = signature.sign(outputFilePath, listOptions);

GroupDocs 會依序處理每個簽章,將它們嵌入文件的中繼資料中。清單中的順序不會影響驗證。

真實案例

1. 軟體發佈流水線

情境:以 TAR 壓縮檔分發軟體套件,並證明未被修改。
解決方案:使用包含 JSON 負載的 QR 代碼簽署每個發佈版本:

String releaseData = String.format(
    "{\"version\":\"%s\",\"buildDate\":\"%s\",\"sha256\":\"%s\"}",
    version, buildDate, checksum
);

為何可行:使用者可在安裝前掃描 QR 代碼以驗證套件完整性——無需管理 GPG 金鑰。

2. 自動化備份系統

情境:每日備份的 TAR 壓縮檔需要稽核追蹤。
解決方案:加入包含備份時間戳記與伺服器 ID 的條碼:

String backupId = String.format("SRV01-%s", LocalDateTime.now().format(formatter));
BarcodeSignOptions bcOptions = new BarcodeSignOptions(backupId, BarcodeTypes.Code128);

為何可行:不開啟壓縮檔即可快速視覺驗證備份的真偽。

3. 文件管理系統

情境:以壓縮檔儲存的法律文件需要防篡改驗證。
解決方案:在同一壓縮檔上同時使用條碼(快速掃描)與 QR 代碼(詳細中繼資料)。

4. 供應鏈追蹤

情境:在多個組織間追蹤檔案包裹。
解決方案:嵌入帶有追蹤 URL 的 QR 代碼,該 URL 連結至驗證 API:

String trackingUrl = "https://verify.yourcompany.com/track/" + uniqueId;
QrCodeSignOptions qrOptions = new QrCodeSignOptions(trackingUrl, QrCodeTypes.QR);

常見問題與解決方案

問題 1:「簽章未找到」於簽署後

症狀:sign() 成功,但簽章未顯示。
原因:放置位置錯誤、覆寫原始檔案、TAR 檢視器限制。
解決方案:

// Always verify the signing succeeded
SignResult result = signature.sign(outputFilePath, bcOptions);
if (result.getSucceeded().size() > 0) {
    System.out.println("Signature added successfully at: " + outputFilePath);
} else {
    System.err.println("Signing failed: " + result.getFailed());
}

// Use absolute paths to avoid confusion
String absolutePath = new File(outputFilePath).getAbsolutePath();

問題 2:大型 TAR 檔案導致 OutOfMemoryError

症狀:對於大於 500 MB 的壓縮檔,JVM 會當機。
解決方案:增加記憶體上限 (-Xmx) 並及時釋放 Signature 物件:

java -Xmx2G -jar your-application.jar

或實作分塊處理:

// For very large files, consider signing metadata separately
// rather than embedding in the TAR itself

問題 3:簽章資料被截斷

症狀:長字串被截斷。
原因:超出 Code128 的容量(≈ 80 個字元)。
解決方案:改用 QR 代碼以容納較長的負載:

// Bad: Too much data for Code128
BarcodeSignOptions bcOptions = new BarcodeSignOptions(veryLongString, BarcodeTypes.Code128);

// Good: Use QR code instead
QrCodeSignOptions qrOptions = new QrCodeSignOptions(veryLongString, QrCodeTypes.QR);

問題 4:授權驗證錯誤

症狀:在生產環境中出現 LicenseException 或「Trial version」警告。
解決方案:在建立任何 Signature 實例之前先載入授權:

import com.groupdocs.signature.License;

License license = new License();
license.setLicense("path/to/GroupDocs.Signature.lic");

// Now create signatures
Signature signature = new Signature("document.tar");

小技巧:在應用程式啟動時載入一次授權,而非每次簽署前都載入。

問題 5:位置值未如預期運作

症狀:簽章出現在意外的位置。
原因:像素與點的混淆。
解決方案:GroupDocs 預設使用像素。若需精確放置:

bcOptions.setLeft(100);  // 100 pixels from left edge
bcOptions.setTop(100);   // 100 pixels from top edge

// If you need percentage-based positioning:
bcOptions.setHorizontalAlignment(HorizontalAlignment.Center);
bcOptions.setVerticalAlignment(VerticalAlignment.Center);

整合模式

模式 1:REST API 服務

將簽署功能以微服務方式公開:

@RestController
@RequestMapping("/api/signature")
public class SignatureController {
    
    @PostMapping("/sign")
    public ResponseEntity<SignatureResponse> signFile(
            @RequestParam("file") MultipartFile file,
            @RequestParam("signatureType") String type) {
        
        try {
            // Save uploaded file temporarily
            File tempFile = File.createTempFile("upload-", ".tar");
            file.transferTo(tempFile);
            
            // Sign based on type
            Signature signature = new Signature(tempFile.getAbsolutePath());
            
            SignOptions options = type.equals("barcode") 
                ? createBarcodeOptions() 
                : createQROptions();
            
            String outputPath = generateOutputPath();
            SignResult result = signature.sign(outputPath, options);
            
            // Return signed file
            return ResponseEntity.ok(new SignatureResponse(outputPath, result));
            
        } catch (Exception e) {
            return ResponseEntity.status(500).body(null);
        }
    }
}

模式 2:批次處理管線

在管線中簽署多個壓縮檔:

public class BatchSigner {
    
    public void signArchiveBatch(List<File> archives) {
        ExecutorService executor = Executors.newFixedThreadPool(4);
        
        archives.forEach(archive -> {
            executor.submit(() -> {
                try {
                    signSingleArchive(archive);
                } catch (Exception e) {
                    logger.error("Failed to sign: " + archive.getName(), e);
                }
            });
        });
        
        executor.shutdown();
        executor.awaitTermination(1, TimeUnit.HOURS);
    }
    
    private void signSingleArchive(File archive) throws Exception {
        Signature signature = new Signature(archive.getAbsolutePath());
        // ... signing logic
    }
}

模式 3:事件驅動架構

在壓縮檔建立時觸發簽署:

@Component
public class ArchiveCreatedListener {
    
    @EventListener
    public void onArchiveCreated(ArchiveCreatedEvent event) {
        CompletableFuture.runAsync(() -> {
            signArchive(event.getFilePath());
        });
    }
    
    private void signArchive(String filePath) {
        // ... signing logic
    }
}

效能考量

記憶體管理

問題:每個 Signature 實例會將整個檔案載入記憶體。
最佳實踐:

// Bad: Creating multiple instances for same file
Signature sig1 = new Signature("file.tar");
Signature sig2 = new Signature("file.tar");  // Loads again!

// Good: Reuse the instance
try (Signature signature = new Signature("file.tar")) {
    signature.sign(output1, options1);
    signature.sign(output2, options2);  // Same instance, different outputs
}

檔案大小最佳化

  • 小檔案 (< 10 MB) – 同步簽署。
  • 中等檔案 (10‑100 MB) – 使用背景執行緒。
  • 大型檔案 (> 100 MB) – 考慮分別簽署中繼資料或使用串流 API。

簽章複雜度(標準伺服器的近似時間)

簽章類型每份文件所需時間
單一條碼50‑100 ms
單一 QR 代碼100‑200 ms
多重簽章150‑300 ms

最佳化提示:處理數千個檔案時,將它們批次化並使用執行緒池(請參考上方的批次處理模式)。

程式庫更新

GroupDocs 定期釋出效能改進。重大部署前請務必檢查 變更紀錄。

更新策略:

  1. 在預備環境測試新版本。
  2. 檢視破壞性變更。
  3. 使用真實檔案進行效能基準測試。
  4. 逐步推出。

生產環境最佳實踐

1. 驗證授權狀態

License license = new License();
if (!license.isLicensed()) {
    logger.warn("Running in trial mode - features may be limited");
}

2. 實作穩健的錯誤處理

try {
    signature.sign(outputPath, options);
} catch (Exception e) {
    logger.error("Signature failed", e);
    // Don't just swallow exceptions - log or re-throw
    throw new SignatureException("Failed to sign document", e);
}

3. 使用具描述性的簽章資料

// Bad: Meaningless ID
new BarcodeSignOptions("12345678", BarcodeTypes.Code128);

// Good: Self-documenting data
String signatureData = String.format("DOC-%s-%s", 
    docType, 
    LocalDateTime.now().format(DateTimeFormatter.ISO_DATE_TIME)
);
new BarcodeSignOptions(signatureData, BarcodeTypes.Code128);

4. 為簽章格式加上版本號 在嵌入的 JSON 中加入版本號,以未來驗證邏輯保持相容性:

String qrData = String.format(
    "{\"v\":\"1.0\",\"type\":\"archive\",\"timestamp\":\"%s\"}", 
    timestamp
);

5. 使用真實檔案測試 – 始終以生產規模的壓縮檔驗證,以提前發現記憶體與效能問題。

結論

現在你已具備使用條碼與 QR 代碼實作 如何簽署 Java 的堅實基礎。以下是你所學到的內容:

  • 如何使用條碼與 QR 代碼簽署 TAR 壓縮檔(以及其他文件)
  • 根據特定需求選擇簽章類型的時機
  • 在投入生產前如何排除常見問題
  • REST API、批次處理與事件驅動系統的實務整合模式
  • 處理任意大小檔案的效能最佳化技巧

後續步驟:

  1. 使用 search() 方法探索簽章驗證。
  2. 嘗試其他文件格式——GroupDocs.Signature 支援 PDF、DOCX、XLSX、PNG 等。
  3. 自訂簽章外觀(顏色、尺寸、邊框)。
  4. 建置驗證 API,以程式方式驗證簽章。

GroupDocs.Signature 的功能遠超本指南。請參閱 GroupDocs.Signature for Java 文件說明,了解文字簽章、影像簽章與中繼資料擷取等進階功能。

有任何問題或想分享你的實作嗎?加入 GroupDocs 社群論壇,向其他開發者尋求協助。

常見問答

Q: 我可以簽署除 TAR 壓縮檔以外的文件嗎?
A: 當然可以!GroupDocs.Signature 支援超過 50 種檔案格式,包括 PDF、DOCX、XLSX、PNG 等。只需在 Signature 建構子中更改檔案副檔名,即可使用任何支援的類型。

Q: 簽署後如何驗證簽章?
A: 使用 search() 方法來定位並驗證簽章:

Signature signature = new Signature("signed-document.tar");
BarcodeSearchOptions searchOptions = new BarcodeSearchOptions();
List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, searchOptions);

Q: 這些簽章能防止篡改嗎?
A: 條碼與 QR 代碼簽章提供視覺驗證,但不像數位憑證那樣具備密碼學強度。若需最高安全性,請將它們與傳統 PKI 結合,或將簽章雜湊值儲存在外部資料庫中。

Q: 簽章能儲存的最大資料量是多少?

  • Code128 條碼:≈80 個字母數字字元
  • QR 代碼(Version 40):最多 4,296 個字母數字字元或 7,089 個數字字元

Q: 我可以自訂簽章外觀嗎?
A: 可以!可控制顏色、尺寸、邊框等:

bcOptions.setForeColor(Color.BLUE);
bcOptions.setBackgroundColor(Color.YELLOW);
bcOptions.setBorder(new Border());
bcOptions.getBorder().setColor(Color.RED);
bcOptions.getBorder().setWeight(2);

Q: 若對同一檔案簽署兩次會發生什麼?
A: 每次呼叫 sign() 都會新增一個簽章。若要取代現有簽章,請先使用 delete() 方法將其刪除。

Q: 如何處理大型檔案而不致記憶體不足?
A: 增加 JVM 記憶體上限 (-Xmx)、及時釋放 Signature 物件,並考慮對多 GB 壓縮檔的中繼資料分別簽署。

Q: 簽署文件是否需要網路連線?
A: 不需要。安裝程式庫後,GroupDocs.Signature 完全可離線運作。


最後更新: 2026-10-06
測試環境: GroupDocs.Signature 23.12 for Java
作者: GroupDocs

相關教學