JNA 實戰指南 (二)：從 DLL 呼叫到遺留代碼保護的完整遷移策略

Java Native Access (JNA) 讓 Java 直接呼叫原生庫 (Windows DLL / Linux .so) 無需編寫 JNI C++ 胶水代碼。本文接續基礎篇，深入實戰：DLL 函數映射、呼叫約定陷阱、錯誤處理、遺留系統整合策略與生產環境治理。

一、核心 API 快速回顧

// 1. 定義介面繼承 Library
public interface MyNativeLib extends Library {
    MyNativeLib INSTANCE = Native.load("mylib", MyNativeLib.class); // Windows 自動加 .dll
    
    // 2. 宣告原生函數簽名 (名稱、參數、返回值需完全對應)
    int helloWorld(int divider);
    void processData(byte[] input, int len, Pointer outputBuffer);
    boolean init(String configPath, IntByReference errorCode);
}

// 3. Java 呼叫如同普通方法
int result = MyNativeLib.INSTANCE.helloWorld(77); // 返回 1 (77/77)

二、呼叫約定陷阱：Dependency Walker 診斷實戰

C/C++ 編譯器依呼叫約定修飾導出符號名稱：

實戰診斷步驟

1. 下載 Dependency Walker (depends.exe) 開啟目標 DLL。
2. 觀察「Export Table」欄位 Function 名稱：

# Cdecl - 正常
helloWorld

# Stdcall - 帶 @ 號
_helloWorld@4

3. 若見 @ 符號，Java 介面必須繼承 StdCallLibrary：

import com.sun.jna.win32.StdCallLibrary;
public interface MyStdLib extends StdCallLibrary {
    MyStdLib INSTANCE = Native.load("mylib", MyStdLib.class);
    int helloWorld(int divider); // JNA 會自動處理 @修飾
}

4. 若載入失敗 UnsatisfiedLinkError: Error looking up function 'helloWorld'，90% 是呼叫約定不匹配。

三、資料類型映射完整對照表

四、錯誤處理與穩健性設計

1. 原生異常不會自動轉 Java Exception

C++ throw、除零、存取違規 (0xC0000005) 會直接炸掉 JVM 進程 (hs_err_pid.log)。

// C 代碼
int divide(int a, int b) { return a / b; } // b=0 觸發 EXCEPTION_INT_DIVIDE_BY_ZERO

// Java 呼叫
try {
    lib.divide(10, 0); // JVM 直接崩潰，catch 不到
} catch (Exception e) { /* 永遠執行不到 */ }

2. 防禦策略

• 輸入驗證：Java 端嚴格檢查參數 (除數非零、指標非空、緩衝區長度足夠)。
• 原生端加護：DLL 內部用 __try/__except (SEH) 或 try/catch 捕獲結構化異常，返回錯誤碼而非拋出。
• 隔離進程：極高風險舊代碼，採用「Java 進程 + 獨立 Native 進程 (IPC/RPC/gRPC)」架構，崩潰不波及主應用。

五、遺留代碼整合遷移路線圖

六、生產環境治理清單

• 依賴管理：jna-platform.jar 包含常用 OS API 映射，優先用它別重複造輪子。
• 原生庫打包：Maven 專案用 maven-nar-plugin 或手動放入 src/main/resources/native/<os>/<arch>/，Native.load 會自動從 classpath 解壓到臨時目錄載入。
• 線程安全：JNA 呼叫預設持有全域鎖 (Native.loadLibrary 同步)，高併發場景評估 Native.setProtected(true) 或改用 Direct Mapping (JNI) 繞過鎖。
• 記憶體洩漏防範：Memory、Pointer 分配的堆外記憶體需手動 free() 或用 try-with-resources (JNA 5.10+ 實現 AutoCloseable)。
• 審計日誌：所有 JNA 呼叫入口統一攔截 (AOP/Filter) 記錄：呼叫者、參數哈希、耗時、結果碼，滿足合規審計。

七、JNA vs JNI vs Panama (未來) 決策矩陣

總結

JNA 是連接 Java 與原生世界的「通用轉接頭」，以極低開發成本解決遺留 DLL/.so 整合難題。但原生邊界是系統脆弱面：呼叫約定不匹配、記憶體模型差異、未檢查異常、線程模型衝突，皆可能導致難以診斷的 JVM 崩潰。採用「Facade 隔離 + 參數護欄 + 進程隔離備案 + 審計日誌」的防禦深度策略，並在技術選型時評估 Panama Foreign Function API 的遷移時機，才能在享受 JNA 便利的同時守住系統穩定性底線。