如何使用條碼和 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. 驗證授權狀態
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、批次處理與事件驅動系統的實務整合模式
- 處理任意大小檔案的效能最佳化技巧
後續步驟:
- 使用
search()方法探索簽章驗證。 - 嘗試其他文件格式——GroupDocs.Signature 支援 PDF、DOCX、XLSX、PNG 等。
- 自訂簽章外觀(顏色、尺寸、邊框)。
- 建置驗證 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