單元 8 · 實作與最佳實踐 · JSON 繁中教學站

最後一單元：把語法、型別、延伸格式串成「能上線」的 JSON 應用，並養成安全、可維護的習慣。

完整範例 · 設定檔

綜合運用：六種型別、巢狀、以及（用 JSONC 時）註解。

config.jsonc / FULL EXAMPLE

{
  // 服務設定
  "name": "my-app",
  "port": 8080,
  "debug": false,

  "database": {
    "host": "db.example.com",
    "pool": { "min": 1, "max": 10 }
  },

  "features": ["auth", "search"],
  "admins": [1, 2, 3],
  "limits": { "timeout": 30, "retries": 3 },
  "banner": null
}

解說 · EXPLAINED

name / port / debug：字串、數字、布林。

database：巢狀物件（含 pool）。

features / admins：字串與數字的陣列。

limits：鍵值映射。

banner：null——「沒設定」也要明確表達。

// 註解：只能在 JSONC 環境使用。

撰寫與驗證 · Write & Validate

工具鏈 · TOOLCHAIN

# 驗證格式（Node 一行）
node -e "JSON.parse(require('fs').readFileSync(0,'utf8'))" < config.json

# 或 Python
python3 -c "import json,sys; json.load(sys.stdin)" < config.json

# 美化 / 壓縮
jq . config.json          # 美化
jq -c . config.json       # 壓成一行
cat config.json | jq .    # 管道用法

# 用 Schema 驗證（用 ajv / jsonschema）
npx ajv-cli validate -s schema.json -d data.json

安全性 · Security

讀取 JSON 有兩個經典陷阱：

1. Prototype Pollution

「不安全 merge」把 __proto__ 等特殊鍵寫進物件原型，可能癱瘓或控制應用程式：

危險的鍵 · DANGEROUS KEYS

{ "__proto__": { "isAdmin": true } }
{ "constructor": { "prototype": { } } }

防範：解析時用「純資料」安全函式（如 Node 的 JSON.parse 本身是安全的）；危險的是任意 merge（如 `lodash.merge`、手寫遞迴合併）。合併前先檢查鍵名、或改用 structuredClone / Object.assign 之外的白名單合併。

2. 只信你的解析器，別信手刻 regex

用正規表示式解析 JSON 幾乎必然出錯（字串內有逗號、括號、跳脫…）。永遠用標準解析器。

常見錯誤 · Common Mistakes

錯誤	後果	修正
尾逗號	解析失敗	移除最後一項逗號
單引號 / 無引號鍵	解析失敗	全改雙引號
寫了註解	解析失敗	改用 JSONC 環境或移除
字串內裸換行	解析失敗	用 `\n`
大整數超過 2^53	精度失真	改用字串
把日期當數字/物件	型別不符	用 ISO 字串慣例
多筆資料堆在一起	解析失敗	包成陣列，或改用 JSON Lines

最佳實踐 · Best Practices

2 空格縮排（多數工具慣例）；用 prettier 統一格式。
鍵名用 camelCase（或配合團隊的 snake_case），全站一致。
日期用 ISO 8601 字串，別發明私有格式。
大數 / 金額用字串，避免精度失真。
缺值明確用 null，不要省略欄位造成歧義。
檔案夠大就改 JSON Lines，別硬塞進一個 JSON。
設定檔要註解？選對環境：JSONC / JSON5。
永遠用安全解析，防 prototype pollution。

把整門課串起來

懂：六種型別與兩種容器（單元 2）。
守規矩：語法鐵則、跳脫、數字（單元 3–4）。
讀形狀：巢狀與四種實務模式（單元 5）。
識變體：JSONC / JSON5 / JSON Lines（單元 6）。
用工具：jq、Schema、安全解析（單元 7–8）。

下一步：打開 DevTools 的 Network 標籤，看任一 API 回應；再用 jq 在終端機把它整形、過濾一遍——你會發現 JSON 已經「看懂了」。

看完這頁你應該能說出：

一份完整設定檔的各部分結構與型別。
至少六個常見 JSON 錯誤與修正。
prototype pollution 是什麼、如何防範。
用 jq / Schema 驗證與格式化的方式。
撰寫 JSON 的最佳實踐清單。

延伸閱讀