單元 1 · YAML 是什麼

1.1 定義：YAML 是什麼

YAML（YAML Ain't Markup Language）是一門資料序列化格式（data serialization format）：用縮排與少量符號描述資料結構，程式再用解析器把它讀成 dict / object / hash。全名是反覆式縮寫（recursive acronym）——「YAML 不是標記語言」，它刻意強調自己不描述版面，只描述資料的形狀。

1.2 YAML 與 JSON 的關係

YAML 與 JSON 描述的是同一種資料模型：對映（mapping）、序列（sequence）、純量（scalar）。兩者可以互相轉換——任何 JSON 都是一份合法的 YAML（JSON 是 YAML 1.2 的子集），反之絕大多數 YAML 也能轉成等價 JSON。

server:
  host: localhost
  port: 8080
debug: true

{"server": {"host": "localhost",
           "port": 8080},
 "debug": true}

1.3 YAML vs JSON vs TOML

1.4 被誰使用：生態地圖

1.5 設計哲學：為什麼 YAML 會贏

1. 人好讀：縮排即結構，視覺上直接對應巢狀層級，比括號直覺。
2. 原生註解：設定檔需要「為什麼這樣設」，JSON 辦不到。
3. 低學習成本：核心概念只有 mapping 與 sequence 兩種容器。
4. 多行字串：CI 步驟、指令碼可以直接嵌進設定，不需要跳脫地獄。
5. 隨處可用：任何語言的解析器都有一堆，YAML 是生態事實標準。

1.6 Worked Example：第一份設定檔

app:
  name: 我的服務
  env: production
features:
  - login
  - billing
debug: false

動手：開一個 test.yml，貼上左邊內容，用 Python / Node / 線上工具解析看看，再改成你自己的服務設定。

延伸閱讀

• 下一篇：單元 2 · 基本語法。
• 術語表：複習全站。

進階真實情境 Worked Example：Helm values 設定檔

在 Kubernetes 生態中，Helm chart 的 values.yaml 是最常見的 YAML 設定檔。以下是一份具備多層巢狀、flow/block 混用與註解的真實場景：

# Helm chart values
replicaCount: 2
image:
  repository: nginx
  tag: "1.27"            # 字串，避免浮點
  pullPolicy: IfNotPresent
service:
  type: LoadBalancer
  port: 80
resources:
  limits: {cpu: "500m", memory: "128Mi"}
  requests: {cpu: "250m", memory: "64Mi"}

replicaCount: 2
image: {repository: "nginx",
        tag: "1.27",
        pullPolicy: "IfNotPresent"}
service: {type: "LoadBalancer",
          port: 80}
resources:
  limits: {cpu: "500m", memory: "128Mi"}
  requests: {cpu: "250m", memory: "64Mi"}

為什麼這樣設計而非替代方案：tag 加引號是為了避免 1.27 被推斷為浮點數；resources 用 flow style 是因為它是簡短的 key-value 對，一行看完比四行更清晰；pullPolicy 不加引號是 plain string 的最佳實踐——值不含特殊字元，多一對引號只會增加噪音。

深入原理擴充

Block Context vs Flow Context

YAML 有兩種呈現上下文（presentation context）：block context（以縮排定義結構）與 flow context（以 { } / [ ] 定義結構）。關鍵規則：flow context 中的冒號後不一定要有空格（當值是明確的標量時），但在 block context 中一定要有空格。這就是為什麼 {cpu:"500m"} 在 flow 對映中合法，但 cpu:"500m" 在 block context 中會出錯。

大家以為是這樣但其實不是……

診斷式疑難排解表

進階挑戰題

1. 跨單元挑戰：寫一份 YAML，要求包含：(a) 一個 flow 對映裡嵌套 block 序列、(b) 一個值同時使用 !!str 標籤與雙引號、(c) 一行包含 # 但不是註解。用 yaml.safe_load 印出型別驗證。
2. 設計思維：你在設計一份 CI/CD 設定檔格式——哪些值應該是字串、哪些應該是數字？列舉 5 個例子並說明你的判斷依據（型別安全 vs 可讀性）。
3. 比較分析：找一份真實的 GitHub Actions workflow，試著把它改寫成等價的 JSON，然後說明改寫過程中遇到哪些「YAML 有但 JSON 沒有」的特性（註解、多行字串、flow/block 混用）。

① 專案級端到端 Worked Example：設定檔驅動的微服務專案

把前 1–7 單元的概念放進一個完整專案：一個小型電商 API，所有設定都用 YAML 描述——應用設定、容器編排、CI pipeline 三層貫通。這就是 YAML 在真實世界的角色：整個專案的「膠水」。

產出檔案樹

config-first-app/
├── app/
│   ├── config.yml          # 應用設定（本單元核心）
│   └── main.py             # 讀取 config.yml 的服務入口
├── deploy/
│   └── compose.yml         # Docker Compose 編排
└── .github/
    └── workflows/
        └── ci.yml          # GitHub Actions CI

關鍵檔案內容

app:
  name: order-api
  env: ${APP_ENV:-dev}   # 環境變數注入，預設 dev
  port: 8080
features:
  - auth
  - cart
  - checkout
rate_limit:
  window: 60
  max_requests: 100

services:
  api:
    build: ../app
    ports: ["8080:8080"]
    environment:
      APP_ENV: production
  redis:
    image: redis:7-alpine

name: CI
on: [push]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install pyyaml
      - run: python -c "import yaml;c=yaml.safe_load(open('app/config.yml'));assert c['app']['port']==8080"

$ python3 -c "import yaml;c=yaml.safe_load(open('app/config.yml'));print(c['app']['port'], c['features'])"
8080 ['auth', 'cart', 'checkout']

$ docker compose -f deploy/compose.yml config --quiet && echo "compose OK"
compose OK

$ actionlint .github/workflows/ci.yml && echo "workflow OK"
workflow OK

端到端流程：開發改 app/config.yml → push 觸發 CI → CI 先解析驗證 YAML 再跑測試 → 綠燈後用 compose 起整疊服務。任何一步的 YAML 壞掉，都會在 CI 階段被攔下，而不是等到上線才爆。

② 效能/品質/安全深度

效能：YAML 的大型檔案代價

YAML 是直譯器友善、解析器昂貴的格式。對比：

實務結論：熱路徑（每次請求都讀）用 JSON；冷路徑（開機/部署時讀一次）用 YAML。大型 values.yaml 可拆成多檔或開啟快取，減少單次解析量。

品質：只有語法檢查不夠

YAML 的「寬鬆」讓品質問題藏在語法正確的檔案裡：型別誤判、缺少必填欄位、拼錯鍵名。解法是三層防線：yamllint（風格）→ JSON Schema（結構）→ 解析器 + assert（行為）。

安全：不可信 YAML 的處理原則

③ 站際比較對照表

④ 互動式檢核清單

• 能說出 YAML 與 JSON/TOML 的定位差異，並在「需要註解的設定檔」與「需要高效傳輸」之間做出正確選擇。
• 能畫出一份專案的完整 YAML 檔案樹（設定檔 / 編排檔 / CI 檔）並解釋每一層的用途。
• 能為自己的專案建立「YAML → 解析 → 驗證」的最小 CI 門檻（至少一行 safe_load 檢查）。
• 能說出大型設定檔改用 JSON 的至少三個理由（解析速度、記憶體、語法風險）。
• 能說明「語法正確」與「品質合格」之間的差距，並列舉至少兩種檢查工具。
• 遇到不可信 YAML 時，能說出處理鐵律（safe_load + 大小 / 深度限制）。