單元 5 · 資料型別

5.1 原理：自動推斷型別

YAML 解析器會依字面自動推斷型別：看到像數字的當數字，像布林的當布林，像日期的當日期物件。這很方便，也是陷阱的來源——因為你以為是字串的值，可能被轉成別的型別。

5.2 常用型別一覽

integer:  42
float:    3.14
exp:      6.02e23
hex:      0x1F
octal:    0o17
bool:     true
none:     null
date:     2026-08-15
datetime: 2026-08-15T10:30:00Z

註：hex / octal 在各解析器的支援程度不同，別依賴它——要當字串就加引號。

5.3 布林陷阱：yes / on / off / 1

這是 YAML 最著名的坑。在 YAML 1.1（很多工具仍用），yes、no、on、off 都會被當成布林。YAML 1.2 只認 true / false。於是同一份檔案在不同解析器下結果可能不同。

on: 開        # 鍵 on → true！
value: yes     # → true（1.1）

{true: "開",     # 鍵被轉成布林
 "value": true}

5.4 數字陷阱：前導零與指數

v1: 010          # 舊規格視為八進位 8；新規格已禁止
v2: "010"        # 加引號 → 字串 "010"，最安全
v3: 1e3          # → 1000.0（浮點）
v4: "1e3"        # 加引號 → 字串

電話號碼、郵遞區號、產品代碼這類「看起來像數字但其實是識別碼」的值，一律加引號，否則前導零會被吃掉或型別錯誤。

5.5 時間戳 · Timestamps

ISO 8601 格式會被推斷成日期/時間物件；加引號則維持字串。

created: 2026-08-15          # 日期物件
started: 2026-08-15T10:30:00Z  # 帶時區
as_str: "2026-08-15"           # 字串

實務注意：10:00（時分）在 YAML 1.1 會被當 sexagesimal（六十進位）數字！想當字串就加引號。

5.6 強制字串與型別標籤

!! 可顯式指定型別，稱型別標籤（type tag）。最常用的是 !!str；!!binary 表示 base64。

icon: !!binary U29tZQ==       # base64
count: !!str 42            # 強制字串 "42"

5.7 Worked Example：一份帶型別陷阱的設定

version: "1.0"            # 字串，不是 1.0
replicas: 3
enabled: true
phone: "0912-345-678"   # 保留前導零
mode: "yes"             # 字串 "yes"，不是布林
start: 2026-08-15

練習：寫 10 個值——5 個故意踩陷阱（yes、010、on、1e3、10:00），5 個用安全寫法修正，然後用 yaml.safe_load 印出每個值的 type() 檢查。

延伸閱讀

• 上一篇：單元 4 · 序列與巢狀。
• 下一篇：單元 6 · 錨點與別名。
• 術語表：複習全站。

進階真實情境 Worked Example：CI/CD 中的型別陷阱連環爆

以下是一份看似無害但包含多個型別陷阱的 GitHub Actions 設定：

env:
  APP_VERSION: "1.0"           # ✅ 字串
  APP_VERSION_BAD: 1.0         # ❌ 變成浮點 1.0
  PORT: "08080"               # ✅ 保留前導零
  PORT_BAD: 08080              # ❌ 1.1 變八進位，1.2 報錯
  DEBUG: "off"                 # ✅ 字串
  DEBUG_BAD: off               # ❌ 1.1 變 false

APP_VERSION:     "1.0" → "1.0"  (字串)
APP_VERSION_BAD: 1.0   → 1.0    (浮點，丟了精確度)
PORT:            "08080" → "08080" (字串)
PORT_BAD:        08080  → 4160 (1.1 八進位) / ERROR (1.2)
DEBUG:           "off"  → "off" (字串)
DEBUG_BAD:       off    → false (1.1 布林)

為什麼這樣設計而非替代方案：APP_VERSION 加引號不只是「保險」——在 CI/CD 中，version 常被 shell 的 echo 直接輸出，浮點 1.0 與字串 "1.0" 在 shell 行為相同，但在程式比較（if [ "$v" == "1.0" ]）或 JSON 注入時行為不同。加引號是唯一的「型別鎖」。

深入原理擴充

YAML 1.1 vs 1.2 的型別差異完整對照

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

診斷式疑難排解表

進階挑戰題

1. 1.1 vs 1.2 比對實驗：用 Python 的 yaml（1.1）和 ruamel.yaml（可選 1.2）分別解析 {yes: on, no: off, 010: 1e3}，印出結果比對差異。
2. 型別安全清單：列出 10 個你日常會放在 YAML 裡的值（版本號、port、ID、日期、金額、布林開關等），逐一判斷哪些需要加引號、哪些可以 plain，並說明理由。
3. 真實 bug 排查：一份設定檔中有 timeout: 10:30，在 YAML 1.1 中被解析為什麼？怎麼修正？如果改成 timeout: "10:30"，下游程式拿到的是字串，需要轉成秒數，怎麼做？

① 專案級端到端 Worked Example：型別安全設定檔治理專案

單靠「記得加引號」無法規模化——真實專案用 JSON Schema 把型別契約寫死，讓機器強制所有 YAML 檔案遵守型別規則：

產出檔案樹

typed-config/
├── config/
│   ├── app.yaml            # 實際設定（含型別陷阱風險）
│   └── schema.json         # JSON Schema——YAML 的型別契約
├── scripts/
│   └── validate.py         # 驗證器（schema + 型別斷言）
└── .github/workflows/
    └── validate.yml        # CI 強制：任何 PR 都要通過型別驗證

關鍵檔案內容

app:
  name: order-api
  version: "1.0"        # 型別陷阱：不加引號會變浮點
  port: 8080
  enabled: true
  features:
    - auth
    - cart
db:
  timeout: "30"         # 故意當字串，schema 會拒絕
  pool: 5

{
  "type": "object",
  "required": ["app", "db"],
  "properties": {
    "app": {"type": "object",
      "properties": {
        "version": {"type": "string"},
        "port": {"type": "integer"},
        "enabled": {"type": "boolean"},
        "features": {"type": "array",
          "items": {"type": "string"}}
      }
    },
    "db": {"type": "object",
      "properties": {
        "timeout": {"type": "integer"},  # 期望整數
        "pool": {"type": "integer"}
      }
    }
  }
}

$ check-jsonschema --schemafile config/schema.json config/app.yaml
== Validation errors ==
config/app.yaml$: 'db.timeout' is not of type 'integer'
  ('string' was expected)

$ python3 scripts/validate.py
app.version type= <class 'str'>  OK
db.timeout type= <class 'str'>   FAIL  (expected int)

關鍵洞察：型別安全不能只靠作者自律——用 JSON Schema 把「每個欄位該是什麼型別」變成機器可執行契約，這才是大型團隊的標準做法。

② 效能/品質/安全深度

品質：型別誤判的三種真實後果

• 靜默壞值：yes 變 true、010 變 8——程式不報錯，但行為錯。
• 精確度損失：version: 1.0 在浮點比對或字串輸出時丟失語意。
• 下游爆炸：型別錯誤常在上游「看不出問題」，直到 DB 寫入或 API 回傳才爆。

安全：型別可被用來攻擊

效能：型別檢查的成本

JSON Schema 驗證對大型檔案有 O(n) 到 O(n·k) 的成本（k = schema 複雜度）。實務上把驗證放 CI / pre-commit（慢但全面），執行期只做最小檢查（isinstance / 型別斷言），兼顧正確性與延遲。

③ 站際比較對照表

④ 互動式檢核清單

• 能列出 10 個日常 YAML 值，逐一判斷該加引號還是 plain，並用 type() 驗證。
• 能重現 yes/on/010/1e3/10:00 的型別陷阱，並用引號修正。
• 能寫一份 JSON Schema 描述自己專案的設定檔型別，並用 check-jsonschema 驗證。
• 能把 schema 驗證接進 CI，讓型別錯誤擋在 PR 階段。
• 能說明 safe_load 為何是安全底線，並舉例標籤注入攻擊。
• 能在執行期與 CI 之間分配型別檢查，兼顧正確性與效能。