Web 專案中使用 JNI 的類加載陷阱與解決方案

問題背景

在 Web 專案中調用 JNI（Java Native Interface）時，常遇到一個經典問題：當應用容器（如 Tomcat）因類文件變更而熱重載 Context 時，JNI 類會嘗試再次加載同一個動態庫，導致 UnsatisfiedLinkError，使該功能完全不可用。

典型 JNI 類結構

public class SystemInfo {
    static {
        System.loadLibrary("SystemInfo"); // 載入本地庫
    }
    public static native long getPhysicalMemory();
}

問題根因

• JNI 規定：同一個 JVM 進程中，同名動態庫只能被載入一次。
• Web 容器熱重載會卸載舊的 ClassLoader 並創建新的，但已載入的本地庫不會自動卸載（且無法通過程式碼主動卸載）。
• 新 ClassLoader 載入 JNI 類時，再次執行 static 區塊中的 System.loadLibrary，JVM 檢測到庫已存在，拋出異常。

解決方案：將 JNI 類移出 Web 應用 ClassLoader

核心思路：讓 JNI 類由容器的共享 ClassLoader 載入，而非 Web 應用專屬的 ClassLoader。這樣 Context 重載時，共享 ClassLoader 不會被銷毀，JNI 類也不會重複初始化。

Tomcat 具體配置步驟

1. 將 JNI 相關類（如 SystemInfo.class）單獨打包成 JAR（例如 jni-common.jar）。
2. 將該 JAR 放置在 Tomcat 的共享庫目錄：{tomcat_home}/lib/（Tomcat 7+）或 {tomcat_home}/common/lib/（舊版本）。
3. 從 Web 專案的 WEB-INF/classes 或 WEB-INF/lib 中移除該 JNI 類/JAR。
4. 重啟 Tomcat。

原理說明

Tomcat 的類加載層級（由父到子）：

Bootstrap ClassLoader (JRE 核心庫)
    ↓
System ClassLoader (Tomcat 啟動類路徑)
    ↓
Common ClassLoader ({tomcat}/lib/*.jar)  ←←← 放這裡！
    ↓
Webapp ClassLoader (WEB-INF/classes, WEB-INF/lib/*.jar)  ←←← 不要放這裡

Common ClassLoader 生命週期隨容器啟動/關閉，不受 Web 應用重載影響。

注意事項

• JNI 類若依賴專案中的其他類，會因可見性問題無法編譯/運行。JNI 類必須獨立，不依賴業務代碼。
• 若有多個 Web 應用共用同一 JNI 庫，此方案天然支持。
• 其他容器（Jetty, JBoss, WebLogic 等）同理，只需找到對應的「共享/公共庫目錄」即可。

總結

JNI 庫無法重複載入是 Java 原生限制。通過調整類加載層級，將 JNI 類提升到容器共享 ClassLoader，即可徹底解決熱重載導致的庫加載衝突。這是部署 JNI Web 應用的標準最佳實踐。