在發送 API 請求前驗證 JSON

為什麼發送前先驗證

當一個 API 請求失敗時，錯誤訊息可能指向認證、權限、schema 驗證或 JSON 本身的格式問題。先驗證 JSON 主體，就能在請求送到伺服器之前排除一整類失敗。它也讓複製的 cURL 指令、Postman 主體、webhook 範例與整合測試在 review 時更輕鬆。

要做的語法檢查

一次嚴格的 JSON 驗證應該確認主體可以解析為 JSON，並且格式化後的輸出和你想送出去的內容一致。

• 每個字串與物件鍵都用雙引號
• 沒有註解或尾隨逗號
• 布林值是 true 或 false，而不是 True 或 False
• 缺漏值是 null 或直接省略，而不是 undefined
• 頂層值與目標 endpoint 的期望一致

標頭同樣重要

合法的 JSON 主體如果請求宣告的 Content-Type 不對，仍然會失敗。多數 JSON API 都要 Content-Type: application/json。如果 endpoint 也檢查 Accept，加上 Accept: application/json，讓客戶端與伺服器在格式上取得共識。

錯誤的請求主體

{ userId: 42, active: True, tags: ['beta',], }

修正後的請求主體

{ "userId": 42, "active": true, "tags": ["beta"] }

通過語法驗證之後

語法驗證只能證明文件可解析。對於正式環境的請求，還要檢查 schema：必填欄位、未知欄位、值的型別、陣列長度、列舉值、日期字串，以及數字 ID 應該是數字還是字串。

除錯小技巧

如果伺服器仍然拒絕合法的 JSON，把格式化後的請求主體與已知可用的範例做對比。語意化的 JSON diff 能在忽略鍵序的同時找出真正的值差異，對不同工具產生的負載特別有用。

一個小巧的 fetch + Ajv 包裝

在把回應主體交給應用程式碼前，先以已知的 schema 做驗證。模組載入時把 schema 編譯一次，每次呼叫都套上一層保護：const validate = ajv.compile(schema); const res = await fetch(url); const data = await res.json(); if (!validate(data)) throw new Error("Schema mismatch: " + ajv.errorsText(validate.errors)); return data; —— 這樣上游契約破壞會在邊界暴露，而不是埋在五層之下。