Java Preferences API 實現用戶偏好持久化存儲

什麼是 Preferences API？

java.util.prefs.Preferences 是 JDK 1.4 引入的跨平台持久化配置存儲機制，專為「用戶偏好設置」設計（如窗口位置、最近打開文件、主題選擇）。它不是通用配置文件替代品，而是針對用戶級/系統級簡鍵值存儲的標準化方案。

核心特性

基本用法

1. 獲取節點

// 用戶級節點 (推薦，無需權限)
Preferences userPrefs = Preferences.userNodeForPackage(MyClass.class);
// 或指定路徑
Preferences userPrefs = Preferences.userRoot().node("/com/myapp/settings");

// 系統級節點 (需管理員權限，慎用)
Preferences sysPrefs = Preferences.systemNodeForPackage(MyClass.class);

2. 讀寫操作

// 寫入
prefs.put("window.title", "My App");
prefs.putInt("window.width", 800);
prefs.putInt("window.height", 600);
prefs.putBoolean("auto.save", true);
prefs.putDouble("zoom.level", 1.5);
prefs.putByteArray("icon.data", iconBytes);

// 讀取 (帶默認值，鍵不存在不拋異常)
String title = prefs.get("window.title", "Default Title");
int width = prefs.getInt("window.width", 1024);
boolean autoSave = prefs.getBoolean("auto.save", false);

// 檢查鍵是否存在
if (prefs.keys().hasMoreElements()) { ... } // 遍歷所有鍵

3. 節點操作

// 刪除鍵
prefs.remove("obsolete.key");

// 刪除整個節點及子節點 (謹慎)
prefs.removeNode();

// 獲取子節點
Preferences child = prefs.node("subcategory");

// 導出 XML (備份/遷移)
try (OutputStream os = new FileOutputStream("prefs-backup.xml")) {
    prefs.exportSubtree(os);
}

// 導入 XML
try (InputStream is = new FileInputStream("prefs-backup.xml")) {
    Preferences.importPreferences(is);
}

實戰封裝：類型安全的配置管理器

public final class AppPreferences {
    private static final Preferences PREFS = Preferences.userNodeForPackage(AppPreferences.class);

    // 鍵常量定義
    private static final String KEY_WINDOW_X = "window.x";
    private static final String KEY_WINDOW_Y = "window.y";
    private static final String KEY_WINDOW_WIDTH = "window.width";
    private static final String KEY_WINDOW_HEIGHT = "window.height";
    private static final String KEY_THEME = "theme";
    private static final String KEY_RECENT_FILES = "recent.files";

    // 默認值
    private static final int DEFAULT_WIDTH = 800;
    private static final int DEFAULT_HEIGHT = 600;

    private AppPreferences() {}

    // === 窗口幾何 ===
    public static void saveWindowBounds(int x, int y, int width, int height) {
        PREFS.putInt(KEY_WINDOW_X, x);
        PREFS.putInt(KEY_WINDOW_Y, y);
        PREFS.putInt(KEY_WINDOW_WIDTH, width);
        PREFS.putInt(KEY_WINDOW_HEIGHT, height);
    }

    public static Rectangle getWindowBounds() {
        return new Rectangle(
            PREFS.getInt(KEY_WINDOW_X, 100),
            PREFS.getInt(KEY_WINDOW_Y, 100),
            PREFS.getInt(KEY_WINDOW_WIDTH, DEFAULT_WIDTH),
            PREFS.getInt(KEY_WINDOW_HEIGHT, DEFAULT_HEIGHT)
        );
    }

    // === 主題 ===
    public static void setTheme(String themeName) {
        PREFS.put(KEY_THEME, themeName);
    }

    public static String getTheme() {
        return PREFS.get(KEY_THEME, "light");
    }

    // === 最近文件 (最多 10 個) ===
    public static void addRecentFile(String filePath) {
        String[] recent = getRecentFiles();
        List<String> list = new ArrayList<>(Arrays.asList(recent));
        list.remove(filePath); // 去重
        list.add(0, filePath); // 置頂
        if (list.size() > 10) list = list.subList(0, 10);
        PREFS.put(KEY_RECENT_FILES, String.join("|", list));
    }

    public static String[] getRecentFiles() {
        String data = PREFS.get(KEY_RECENT_FILES, "");
        return data.isEmpty() ? new String[0] : data.split("\\|");
    }

    // === 強制刷新 (關鍵操作後調用) ===
    public static void flush() {
        try { PREFS.flush(); } catch (BackingStoreException e) { log.error("刷新失敗", e); }
    }
}

Swing 整合示例：記住窗口位置大小

public class MainFrame extends JFrame {
    public MainFrame() {
        // 恢復窗口狀態
        Rectangle bounds = AppPreferences.getWindowBounds();
        setBounds(bounds);
        setTheme(AppPreferences.getTheme());

        // 關閉時保存
        addWindowListener(new WindowAdapter() {
            @Override
            public void windowClosing(WindowEvent e) {
                AppPreferences.saveWindowBounds(getX(), getY(), getWidth(), getHeight());
                AppPreferences.flush();
            }
        });
    }
}

適用場景與不適用場景

遷移建議

服務端/雲原生環境建議遷移至：

• 配置中心：Apollo、Nacos、Consul、Spring Cloud Config
• 分布式緩存：Redis (用戶會話級偏好)
• 數據庫：用戶設置表
• 對象存儲：S3 存儲用戶配置 JSON

常見問題

1. Windows 註冊表路徑：HKEY_CURRENT_USER\Software\JavaSoft\Prefs\com\myapp
2. Linux 文件位置：~/.java/.userPrefs/com/myapp/prefs.xml
3. 導出 XML 編碼：默認 UTF-8，可直接編輯
4. 權限報錯：系統節點需管理員，普通應用嚴禁使用
5. 大數據性能：不適合存儲大對象，byte[] 限制較小 (平台相關)