YAML 入門指南：Java 開發者的配置文件新選擇，超越 XML 與 JSON

為什麼選 YAML？

XML 過於冗長，JSON 缺乏註解且巢狀大括號難以維護。YAML (YAML Ain't Markup Language) 以縮進表達層級、支援註解、且是JSON 超集，完美平衡了可讀性與表達力，成為 Spring Boot、Kubernetes、CI/CD 流程的標準配置格式。

核心語法速覽

1. 縮進與映射

# 映射: key: value (冒號後必須有空格)
server:
  port: 8080
  address: 0.0.0.0
  servlet:
    context-path: /api

2. 列表

# 短橫線開頭
spring:
  profiles:
    active:
      - dev
      - mysql
      - redis

# JSON 風格 (行內)
spring.profiles.active: [dev, mysql, redis]

3. 多行文字

# | 保留換行
description: |
  第一行
  第二行
  第三行

# > 折疊為單行 (換行變空格)
summary: >
  這是一段很長的說明文字，
  會被折疊成單行輸出。

4. 錨點與別名 (複用)

defaults: &defaults
  timeout: 3000
  retries: 3

serviceA:
  <<: *defaults  # 合併錨點內容
  name: OrderService

serviceB:
  <<: *defaults
  name: PaymentService
  timeout: 5000  # 覆蓋特定值

Java 整合：SnakeYAML 實戰

Spring Boot 內建 `snakeyaml`，直接 `@ConfigurationProperties` 綁定：

@ConfigurationProperties(prefix = "app")
@Data
public class AppConfig {
    private String name;
    private List<String> tags;
    private Map<String, Object> metadata;
    private NestedConfig nested;
}

// application.yml
app:
  name: MyApp
  tags: [core, backend]
  metadata:
    version: 1.0
    author: team
  nested:
    enabled: true
    threshold: 100

手動解析 (無 Spring 環境)

Yaml yaml = new Yaml();
// 讀成 Map
Map<String, Object> data = yaml.load(new FileInputStream("config.yml"));
// 讀成 POJO
AppConfig config = yaml.loadAs(new FileInputStream("config.yml"), AppConfig.class);

// 寫入
String output = yaml.dump(config);
Files.writeString(Paths.get("out.yml"), output);

YAML vs XML vs JSON 三方對決

常見坑點與最佳實踐

1. 禁用 Tab 鍵：只能用空格縮進 (建議 2 空格)，IDE 請設定「Convert tabs to spaces」。
2. 布林值陷阱：`yes/no`, `on/off`, `true/false` 皆解析為布林，字串請加引號：`"yes"`。
3. 數字格式：`0755` 會被視為八進位，端口號請寫 `"8080"` 或 `8080` (無前導零)。
4. 特殊鍵值需引號：包含 `:, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, ` ` 的字串請加引號。
5. 安全性：SnakeYAML 預設允許反序列化任意類別 (`!!javax.script.ScriptEngineManager` 等)，生產環境請設定 `allowDuplicateKeys: false` 並使用 `SafeConstructor` 或限制標籤。

結語

YAML 以人類友善的設計，成為現代雲原生時代的配置通用語。掌握其核心語法、錨點複用、多行文字與 Java 綁定技巧，能讓你的配置管理更優雅、更安全。