Java Properties 屬性檔案讀寫完整指南與最佳實務

java.util.Properties 繼承自 Hashtable，專為「鍵值對」設定檔設計，支援從輸入流載入、輸出流儲存，並內建處理編碼、轉義、註解等細節，是 Java 應用程式外部化配置的經典選擇。

核心 API 快速查閱

完整範例：讀取、修改、新增、儲存

import java.io.*;
import java.util.Properties;

public class PropertiesDemo {
    private static final String FILE = "config.properties";

    public static void main(String[] args) throws IOException {
        Properties props = new Properties();

        // 1. 讀取 (建議使用 Reader 指定 UTF-8)
        try (Reader reader = new InputStreamReader(new FileInputStream(FILE), StandardCharsets.UTF_8)) {
            props.load(reader);
        } catch (FileNotFoundException e) {
            System.out.println("配置檔不存在，將建立新檔");
        }

        // 2. 取值 (含預設值)
        String siteName = props.getProperty("sitename", "DefaultSite");
        String siteUrl  = props.getProperty("siteurl", "https://localhost");
        System.out.println("sitename = " + siteName);
        System.out.println("siteurl  = " + siteUrl);

        // 3. 修改與新增 (僅接受 String)
        props.setProperty("sitename", "Boxcode");
        props.setProperty("studio", "Boxcode Studio");

        // 4. 儲存 (使用 Writer 指定 UTF-8，避免中文亂碼)
        try (Writer writer = new OutputStreamWriter(new FileOutputStream(FILE), StandardCharsets.UTF_8)) {
            props.store(writer, "Copyright (c) Boxcode Studio - Updated: " + new Date());
        }

        // 5. 列出所有鍵值
        props.stringPropertyNames().forEach(k -> 
            System.out.println(k + " = " + props.getProperty(k))
        );
    }
}

配置檔範例 (config.properties)

# 這是註解行
! 也是註解
sitename=Boxcode
siteurl=https://boxcode.example.com
studio=Boxcode Studio
# 布林值慣用 true/false
debug=true
# 數值需自行轉型
max.connections=100

常見坑與最佳實務

• 編碼陷阱：load(InputStream) 固定用 ISO-8859-1，中文會變亂碼。必須改用 load(Reader) + InputStreamReader(..., StandardCharsets.UTF_8)。
• 不要用 put/putAll：繼承自 Hashtable 的方法允許非 String 鍵值，導致 store() 拋出 ClassCastException。永遠使用 setProperty。
• 多層配置合併：Properties defaults = new Properties(); props = new Properties(defaults); 可實現預設值回退機制。
• 執行緒安全：Properties 同步方法較慢，高併發讀取建議改用 ConcurrentHashMap 或讀取後快取不可變快照。
• 敏感資料：密碼、金鑰勿明文存放，應加密或使用 Vault / 環境變數注入。

現代替代方案

• YAML (SnakeYAML)：結構化、支援清單/巢狀、可讀性高，Spring Boot 預設採用。
• HOCON (Typesafe Config)：支援合併、引用、環境變數替換，Akka/Play 框架常用。
• Spring @ConfigurationProperties：型別安全綁定、驗證、熱重載。