Java Properties 配置檔案完整操作指南：載入、遍歷、XML 儲存與最佳實務

前言

java.util.Properties 繼承自 Hashtable，是處理鍵值對配置檔的標準工具。支援 .properties 文字格式與 .xml 格式雙向轉換。本文涵蓋核心 API、遍歷方式、XML 操作、編碼陷阱與生產環境最佳實務。

核心 API 快速查閱

完整操作範例

1. 載入 .properties (類別路徑資源)

Properties props = new Properties();
try (InputStream is = MyClass.class.getResourceAsStream("/config/app.properties")) {
    if (is == null) throw new IllegalStateException("Config not found");
    props.load(is);  // 注意：預設 ISO-8859-1，中文會變亂碼
} catch (IOException e) {
    throw new RuntimeException("Load config failed", e);
}

2. 載入 .properties (指定 UTF-8，解決中文亂碼)

try (Reader reader = new InputStreamReader(
        MyClass.class.getResourceAsStream("/config/app.properties"), StandardCharsets.UTF_8)) {
    props.load(reader);
}

3. 遍歷所有鍵值對

// 方式一：keySet (舊式，需轉型)
for (Object keyObj : props.keySet()) {
    String key = (String) keyObj;
    String value = props.getProperty(key);
    System.out.println(key + "=" + value);
}

// 方式二：stringPropertyNames (推薦，型別安全)
for (String key : props.stringPropertyNames()) {
    System.out.println(key + "=" + props.getProperty(key));
}

// 方式三：entrySet (需轉型)
for (Entry entry : props.entrySet()) {
    System.out.println(entry.getKey() + "=" + entry.getValue());
}

4. 檢查鍵是否存在

if (props.containsKey("database.url")) { ... }
// 或
String url = props.getProperty("database.url", "jdbc:mysql://localhost:3306/default");

5. 程式化修改並儲存 (UTF-8)

props.setProperty("app.version", "2.1.0");
props.setProperty("feature.new", "enabled");

try (Writer writer = new OutputStreamWriter(
        new FileOutputStream("config/app.properties"), StandardCharsets.UTF_8)) {
    props.store(writer, "Updated by deploy script at " + Instant.now());
}

6. XML 格式儲存與載入

// 存為 XML (自動 UTF-8)
try (OutputStream os = new FileOutputStream("config/app.xml")) {
    props.storeToXML(os, "Application Configuration");
}

// 從 XML 載入
Properties propsXml = new Properties();
try (InputStream is = new FileInputStream("config/app.xml")) {
    propsXml.loadFromXML(is);
}

生產環境最佳實務

常見陷阱總結

• load(InputStream) 固定 ISO-8859-1 → 中文變 ??? 或亂碼。
• store(OutputStream) 會將非 ASCII 字元轉為 Unicode 轉義 \uXXXX，人類難讀。
• Properties 非執行緒安全 (繼承 Hashtable 雖同步但複合操作不原子)。
• 鍵值對中包含空白、冒號、等號需轉義，store/load 自動處理。

現代替代方案：Spring Boot @ConfigurationProperties、Typesafe Config (HOCON)、YAML + SnakeYAML、Apollo/Nacos 配置中心。但 Properties 作為 JDK 零依賴基礎設施，理解其機制仍是必修課。