在前 14 天，我們談過環境、依賴、測試、日誌、例外處理。專案已經能「穩定跑、能被監控、遇到錯誤還能撐下去」。但還有一個日常一定會碰到的基礎能力還沒說清楚：資料序列化與設定格式。

不管是 API 傳遞資料、快取結果、還是讀取設定檔，你一定會遇到這個問題：到底該用 JSON、YAML 還是 TOML？今天我們就來做一個清楚的定位，並且放到工程化專案的實務情境中。

1. JSON 與 orjson：效能與相容性

JSON 是資料交換的世界語言。Python 標準庫有內建 json 模組，但它效能普通，也缺乏一些進階支援。這時候可以換成 orjson：一個基於 Rust 的超快 JSON 庫。

import orjson
from datetime import datetime

data = {"id": 1, "ts": datetime.now()}

# 序列化成 bytes
serialized = orjson.dumps(data)
print(serialized)

# 反序列化
parsed = orjson.loads(serialized)
print(parsed)

特點：

• 快很多：比標準 json 快數倍，適合高流量 API。
• 安全：強制 UTF-8，不會出現莫名其妙的亂碼。
• 支援 datetime / numpy：不用自己轉字串。

👉 工程實務：

• API Response → orjson 幾乎是必備。
• 快取層（Redis、檔案） → 用 orjson.dumps / loads。
• 若專案只依賴標準庫 → 退而求其次用 json，但效能差距顯著。

2. YAML：設定檔的好朋友（但要小心）

YAML 因為可讀性高，被廣泛用在 Kubernetes、CI/CD workflow。它很適合人類維護的設定檔。

app:
  name: demo
  debug: true
  database:
    url: postgresql://user:pass@localhost/db
    pool_size: 10

Python 讀取：

import yaml

with open("config.yaml") as f:
    config = yaml.safe_load(f)

print(config["app"]["database"]["url"])

優點：

• 可讀性高，能支援巢狀結構、註解。
• 生態成熟，各語言幾乎都有 parser。

缺點：

• 語法太寬鬆，縮排錯誤很常見。
• 曾經有過安全漏洞（千萬別用 yaml.load，要用 safe_load）。

👉 工程實務：

• 適合 CI/CD、部署、Infra 設定。
• 團隊共同維護的設定檔 → YAML + Schema 驗證（搭配 Pydantic）。
• 避免把敏感資訊直接寫進 YAML，建議搭配 Day 12 的秘密管理策略。

3. TOML：現代 Python 專案的設定標準

TOML 出現的目的很明確：簡單、結構化、不踩坑。Python 生態已經正式採用它，PEP 518/621 規定 pyproject.toml 就是 TOML 格式。

[app]
name = "demo"
debug = true

[database]
url = "postgresql://user:pass@localhost/db"
pool_size = 10

Python 讀取（Python 3.11 內建）：

import tomllib

with open("config.toml", "rb") as f:
    config = tomllib.load(f)

print(config["database"]["url"])

特點：

• 單純明確：比 YAML 更直觀，幾乎沒有隱式陷阱。
• 標準化：PEP 官方背書，Python 3.11 內建。
• 最適合專案設定：版本、依賴、環境 → 全部都靠它。

👉 工程實務：

• 專案設定 → TOML（pyproject.toml 已成共識）。
• 使用者需要大量編輯 → YAML 會更親和。
• 資料交換或快取 → JSON / orjson 才是對的選擇。

4. 三者的角色分工

這三種格式不是互相取代，而是各自有最適合的場景：

對應到專案目錄結構（Day 4 的延伸）：

my_project/
├─ pyproject.toml        # 專案設定（TOML）
├─ config.yaml           # 部署/Infra 設定（YAML）
├─ cache/                # 儲存 JSON 序列化結果
│   └─ response.json
└─ src/my_project/
   ├─ settings.py        # 載入並驗證設定（pydantic-settings）
   └─ serializers.py     # 集中處理 orjson dumps/loads

這樣一來，專案就能把「設定、資料、程式」清楚分工。

結語

從 JSON → YAML → TOML，這三種格式並不是競爭，而是分工：

• JSON/orjson：效率與通用性，最適合資料交換。
• YAML：人類友善，適合維護大量設定。
• TOML：專案設定的官方標準。

工程化的核心在於 格式與責任的分離。當設定與程式分離、資料與格式分離，每個檔案才能在正確的位置發揮價值。

明天 Day 16，我們將進一步探討 非同步基礎：asyncio / anyio 的落地心法，把專案帶向高併發的世界 🚀。