單元 8 · 實作與最佳實踐

8.1 完整範例 · Docker Compose

綜合運用單元 2–7：縮排、序列、環境變數、錨點合併與多行字串。以下是一次完整的實作，右欄逐段拆解：

x-app: &app
  restart: unless-stopped
  networks: [appnet]

services:
  api:
    <<: *app
    build: .
    ports:
      - "8080:8080"
    environment:
      DB_URL: "postgres://db:5432/app"
      LOG_LEVEL: info
  db:
    <<: *app
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 10s

volumes:
  db-data:

networks:
  appnet:

8.2 常見錯誤 · Common Mistakes

8.3 安全性 · Security

讀 YAML 時，不要用「不安全」的 load。這非常重要：

# ❌ 危險：可執行任意程式碼（object constructor）
yaml.load(data)

# ✅ 安全：只載入純資料
yaml.safe_load(data)

# 其他語言的對應作法：
# Go    → gopkg.in/yaml.v3 預設就安全
# Ruby  → YAML.safe_load
# Node  → js-yaml safeLoad / 新版的 load

8.4 工具鏈 · Tooling

8.5 風格指南 · Style Guide

• 一律兩個空格縮排，不用 Tab。
• 布林寫 true / false；要字串就加引號「字串化」yes/no。
• 設定檔加註解，說明「為什麼這樣設」。
• 避免重複鍵——同鍵出現兩次，最後一個贏，容易藏 bug。
• 錨點適度使用，團隊懂再大量用。
• 用 yamllint 接進 CI，讓壞格式進不了 main。
• 敏感值走環境變數，不要寫死在 YAML。
• 檔名用 .yaml 或 .yml 皆可，但同一個專案請統一。

8.6 Worked Example：交付前檢查清單

- [ ] 縮排全部用空格（兩個空格）
- [ ] 所有冒號後都有空格
- [ ] 布林寫 true / false
- [ ] 電話/代碼等已加引號
- [ ] 「序列裡的對映」有對齊
- [ ] 多行區塊縮排正確
- [ ] 沒有重複鍵
- [ ] 跑過 yamllint 無 error
- [ ] 用解析器讀回並印出驗證

延伸閱讀

• 上一篇：單元 7 · YAML 生態系。
• 術語表：複習全站。

進階真實情境 Worked Example：完整的 Production Docker Compose

以下是一份整合了單元 1–8 所有概念的生產級 compose.yaml，包含錨點、多行字串、型別安全、flow/block 混用與安全性考量：

# Production Compose — 綜合運用
x-logging: &log
  logging:
    driver: json-file
    options:
      max-size: "10m"
      max-file: "3"

x-healthcheck: &hc
  healthcheck:
    interval: "30s
      |
      timeout: 5s
      |
      retries: 3

services:
  api:
    <<: *log
    build: .
    ports: ["8080:8080"]
    environment:
      NODE_ENV: production
      DB_HOST: "db"
    depends_on:
      db: {condition: service_healthy}

  db:
    <<: *log
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: "${DB_PASS}"  # 從 .env 讀入

volumes:
  pgdata:

關鍵設計決策：敏感值 DB_PASS 不寫死在 YAML 中，而是從 .env 檔注入（"${DB_PASS}"），這符合安全性最佳實踐。ports 加引號是因為 "8080:8080" 內含冒號，不加引號會被 YAML 誤判。

深入原理擴充

Production YAML 的隱性成本

大型 YAML 設定檔（如 Helm chart values.yaml、K8s operator CRD）的隱性成本包括：

• 版本控制衝突：YAML 的空白敏感特性導致 Git merge 衝突比 JSON 頻繁得多
• 型別安全缺失：沒有 schema 的 YAML 檔，錯誤只在執行期才暴露
• 錨點可追溯性差：<<:*base 的值從哪來？IDE 通常無法追蹤
• 工具碎片化：yamllint、prettier、editorconfig 三方對「合法 YAML」的定義不完全一致

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

診斷式疑難排解表

進階挑戰題

1. Production 設定檔審計：找一個公開的 GitHub repo（例如 Hashicorp、Prometheus），找到它的 Docker Compose 或 K8s manifest，用本單元的檢查清單逐一審計：縮排、型別安全、錨點使用、敏感值處理。列出至少 3 個你會改的地方。
2. 全棧 YAML 驗證流程設計：設計一套 CI pipeline：(a) yamllint 檢查風格、(b) JSON Schema 檢查語意、(c) kustomize build 驗證 K8s manifest、(d) docker compose config 驗證 Compose 檔。畫出流程圖並說明每一步的目的。
3. Migration 計劃：你手上有 50 個 YAML 設定檔，需要從 YAML 1.1 遷移到 1.2。制定一個安全的遷移計劃：哪些值需要改？怎麼自動化偵測？怎麼驗證遷移後的結果？

① 專案級端到端 Worked Example：Monorepo 設定檔治理專案

最後一單元，把全部工具串成一套設定檔治理系統：一個 monorepo 內的所有 YAML，靠 pre-commit + CI + schema 三層自動把關。這是「最佳實踐」從個人習慣升級為團隊工程的完整示範：

產出檔案樹

platform-config/
├── .pre-commit-config.yaml   # pre-commit 掛鉤（本地門檻）
├── .yamllint                 # yamllint 設定
├── .editorconfig             # 縮排/換行統一
├── configs/
│   ├── app.yaml              # 應用設定
│   ├── compose.yml           # Docker Compose
│   └── k8s/
│       ├── deployment.yaml   # K8s manifest
│       └── service.yaml
├── schemas/
│   └── app.schema.json       # 型別契約
└── Makefile                  # 統一指令入口

關鍵檔案內容

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
  - repo: https://github.com/adrienverge/yamllint.git
    rev: v1.35.1
    hooks:
      - id: yamllint
        args: [--strict]
  - repo: https://github.com/koalaman/shellcheck-precommit
    rev: v0.10.0
    hooks:
      - id: shellcheck

extends: default
rules:
  indentation: {spaces: 2, indent-sequences: true}
  line-length: {max: 100}
  comments: {min-spaces-from-content: 2}
  key-duplicates: enable
  truthy: {allowed-values: [true, false]}

$ pre-commit run --all-files
trailing-whitespace................Passed
end-of-file-fixer...................Passed
yamllint............................Passed
shellcheck..........................Passed

$ make lint
yamllint -c .yamllint .
(無輸出 = 通過)

$ make validate
check-jsonschema --schemafile schemas/app.schema.json configs/app.yaml
PASS: configs/app.yaml

關鍵洞察：最佳實踐的價值在可重現性——本地與 CI 跑同一套檢查、同一版本、同一規則，才能保證「壞 YAML 進不了 main」。這比任何個人記憶可靠。

② 效能/品質/安全深度

品質：三層品質模型的落地

分配原則：越便宜的層級越要頻繁跑（pre-commit 每 commit），越貴的層級放 CI 的關鍵 PR 才跑。

安全：YAML 的機密洩漏面

效能：pre-commit 與 CI 的取捨

pre-commit 有快取（repo 與環境快取），重複執行很快；CI 每次從零建環境。最佳化：① hook 只跑變更檔案（pre-commit 預設）；② CI 用 paths 過濾；③ schema 驗證用 Python 快 (check-jsonschema) 而非起 container；④ 把 lint 放最便宜的 runner。

③ 站際比較對照表

④ 互動式檢核清單

• 能為自己的 repo 建立 .pre-commit-config.yaml，包含 yamllint + whitespace 檢查。
• 能寫出 .yamllint 設定（縮排、行長、key-duplicates、truthy），並用 --strict 跑通。
• 能為至少一份 YAML 寫 JSON Schema 並接進 CI（check-jsonschema）。
• 能整合 Makefile 的 lint/validate 指令，讓本地與 CI 跑同一套。
• 能部署 gitleaks / git-secrets 掃描，確認 repo 無 YAML 內嵌 secret。
• 能把品質模型分層（風格/結構/行為），並說明每層的工具與頻率。