API 回傳一坨垃圾？資深工程師教你用 JSON Schema 打造 WordPress 滴水不漏的數據防火牆

嗨，我是浪花科技的 Eric。身為一個有點龜毛的資深工程師，我看過太多因為「資料格式」問題而引發的災難。前端送來的資料缺東缺西、後端 API 回傳的格式變來變去，這種「溝通全靠心電感應」的開發模式，簡直是專案管理的惡夢，更別提後續維護要花多少時間去 debug 了。

「Garbage in, garbage out.」（垃圾進，垃圾出）這句古老的程式諺語，在 API 串接的世界裡尤其真實。如果你的 WordPress 網站需要跟外部服務、手機 App 或前端框架（像是 React / Vue）溝通，那麼你一定對處理各種奇形怪狀的 JSON 資料感到頭痛。今天，我就要來跟你分享一個能從根本解決這個問題的神兵利器：JSON Schema 設計與驗證。

什麼是 JSON Schema？為什麼你的 WordPress 專案需要它？

在我們深入探討之前，先來個快速複習。JSON (JavaScript Object Notation) 是一種輕量級的資料交換格式，因為易於閱讀和撰寫，已經成為現代 API 的標準格式。但 JSON 本身只定義了資料的「長相」，卻沒有定義「規則」。

這就像是你拿到一張履歷表，你知道上面有姓名、電話、Email，但你無法保證：

• Email 欄位是不是真的是一個有效的 Email 格式？
• 年齡欄位會不會被填入「祕密」這兩個字？
• 必填的電話號碼是不是被漏掉了？

JSON Schema 就是為了解決這個問題而生的。它本身也是一個 JSON 檔案，但它的用途是去「描述」另一個 JSON 檔案的結構和規則。你可以把它想像成是：

• JSON 資料的「藍圖」或「說明書」：它清楚定義了每個欄位的名稱、資料型別（字串、數字、布林值…）、是否為必填，以及更複雜的驗證規則。
• 一份開發團隊之間的「合約」：前端工程師和後端工程師不用再猜來猜去，只要看著這份 Schema，就知道資料該長什麼樣子。
• 一個自動化的「數據守門員」：在資料進入你的 WordPress 資料庫之前，先用 Schema 這道防火牆過濾掉所有不符合規範的「垃圾資料」。

對 WordPress 開發者來說，導入 JSON Schema 設計與驗證 帶來的好處是顯而易見的：

1. 提升 REST API 的穩健性：確保所有寫入你自訂端點 (Custom Endpoint) 的資料都是乾淨、有效、且符合預期的，大幅減少因為髒資料造成的 bug。
2. 增強網站安全性：防止惡意使用者透過 API 傳送非預期的資料結構或型別，這也是一種基礎的安全性防護，避免潛在的注入攻擊。
3. 加速開發與協作：Schema 本身就是最好的 API 文件。前端不用再苦苦等待後端完成 API 才能開始開發，他們可以根據 Schema 產生的假資料 (mock data) 先行作業。
4. 簡化 Debug 過程：當資料驗證失敗時，你可以立刻回傳一個明確的錯誤訊息，告訴呼叫方「哪個欄位錯了」、「為什麼錯」，而不是讓程式在後續流程中因為一個 `null` 或非預期的資料型別而莫名其妙地崩潰。

JSON Schema 核心概念：打造你的第一份數據藍圖

講了這麼多好處，我們來實際看看 JSON Schema 長什麼樣子。假設我們要為一個產品評論的 API 設計一個 Schema，我們期望收到的 JSON 資料如下：

{
  "product_id": 123,
  "rating": 5,
  "comment": "這真是太棒了！",
  "reviewer_name": "Eric",
  "reviewer_email": "eric@roamer-tech.com"
}

對應的 JSON Schema 可能會這樣設計：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Product Review",
  "description": "Schema for a product review submission",
  "type": "object",
  "properties": {
    "product_id": {
      "description": "The unique identifier for the product",
      "type": "integer",
      "minimum": 1
    },
    "rating": {
      "description": "The rating given by the reviewer, from 1 to 5",
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "comment": {
      "description": "The review text",
      "type": "string",
      "maxLength": 500
    },
    "reviewer_name": {
      "description": "Name of the reviewer",
      "type": "string",
      "minLength": 2
    },
    "reviewer_email": {
      "description": "Email address of the reviewer",
      "type": "string",
      "format": "email"
    }
  },
  "required": ["product_id", "rating", "comment", "reviewer_name", "reviewer_email"]
}

重點關鍵字解析：

• $schema: 指定你使用的 Schema 版本，通常照抄即可。
• title / description: 不影響驗證，但對文件化非常有幫助。
• type: 定義資料的型別，最外層通常是 object 或 array。
• properties: 這是 object 型別的核心，用來定義物件內每個屬性（key）的規則。
• required: 一個陣列，列出所有必填的屬性名稱。如果請求中缺少了 `required` 裡的任何一個欄位，驗證就會失敗。
• 驗證關鍵字：像是 minimum, maximum, minLength, maxLength, format (例如 email, date-time) 等，這些都是用來加上更細緻的規則，確保資料不只「存在」，更是「正確」。

實戰！在 WordPress REST API 中導入 JSON Schema 驗證

理論講完了，我們工程師還是得看 code 才踏實。WordPress 核心本身沒有內建 JSON Schema 驗證器，但我們可以很輕易地透過 Composer 整合第三方 PHP 套件來完成這項工作。我個人推薦 justinrainbow/json-schema 這個老牌又穩定的函式庫。

身為一個現代化的 WordPress 開發者，你應該要在你的外掛或主題專案中使用 Composer。如果你還在手動 `require` 檔案，那真的該花點時間看看 如何打造現代化的開發環境了，這會讓你的專案管理提升好幾個檔次。

步驟一：使用 Composer 安裝驗證函式庫

在你的外掛或主題根目錄下，打開終端機，執行：

composer require justinrainbow/json-schema

步驟二：建立自訂 REST API 端點

我們在 `functions.php` 或是一個自訂外掛中，註冊一個新的 API 路由來接收產品評論。

<?php
add_action('rest_api_init', function () {
    register_rest_route('my-awesome-plugin/v1', '/reviews', [
        'methods' => 'POST',
        'callback' => 'handle_submit_review',
        // 我們等等會在這裡加上權限檢查
        'permission_callback' => '__return_true', 
    ]);
});

步驟三：撰寫驗證與處理邏輯

現在，最關鍵的部分來了。我們要在 `handle_submit_review` 這個 callback function 裡，用剛剛安裝的函式庫來驗證傳入的請求 body。

<?php
use JsonSchema\Validator;

function handle_submit_review(WP_REST_Request $request) {
    // 1. 取得請求的 JSON body
    $data = $request->get_json_params();

    // 2. 定義我們的 JSON Schema (實務上建議存在一個 .json 檔裡)
    $schema = json_decode(file_get_contents(__DIR__ . '/schemas/review.json'));

    // 3. 建立驗證器
    $validator = new Validator();
    $validator->validate($data, $schema);

    // 4. 檢查驗證結果
    if (!$validator->isValid()) {
        // 驗證失敗，回傳一個帶有詳細錯誤資訊的 WP_Error 物件
        $errors = [];
        foreach ($validator->getErrors() as $error) {
            $errors[] = sprintf('[%s] %s', $error['property'], $error['message']);
        }

        return new WP_Error(
            'rest_invalid_payload',
            'The submitted data is invalid.',
            ['status' => 400, 'errors' => $errors]
        );
    }

    // 5. 驗證通過！可以安心地處理資料了
    // 例如：將評論寫入資料庫
    $product_id = sanitize_text_field($data['product_id']);
    $rating = intval($data['rating']);
    // ... 其他處理邏輯 ...

    // 回傳成功的響應
    return new WP_REST_Response(['message' => 'Review submitted successfully!'], 201);
}

看到了嗎？在我們真正開始處理資料（步驟 5）之前，我們用 Schema 建立了一道堅固的防線。任何不符合 `review.json` 裡面規則的請求，都會在步驟 4 被擋下來，並且回傳一個 400 Bad Request 的 HTTP 狀態碼，以及清楚的錯誤訊息。這就是專業級 API 該有的樣子！

結論：不只是驗證，更是專業開發的基石

導入 JSON Schema 設計與驗證，初期看起來可能會增加一點點工作量，需要你額外定義 Schema 檔案。但相信我，這是一項非常值得的投資。它能為你的 WordPress 專案帶來更強的健壯性、更高的安全性，並大幅改善團隊協作的效率。

別再讓你的 API 像個沒有警衛的大門，任由各種來路不明的資料闖入。從今天起，為你的資料建立一份清晰的藍圖，用 JSON Schema 打造一個讓自己和同事都能安心的開發流程吧！

延伸閱讀

• API 亂糟糟，專案火葬場？資深工程師的 WordPress REST API 設計聖經 (REST + JSON)
• 你的 WordPress 正在大開後門嗎？資深工程師的 Webhook 設計與安全驗證終極指南
• WordPress 只能寫文章？錯！資深工程師手把手教你用 REST API 自訂端點，打造無頭應用超能力！

如果你對於如何在現有專案中導入 JSON Schema，或是對於 WordPress API 開發、自動化串接有任何疑問，浪花科技的團隊擁有豐富的實戰經驗。我們不只會寫 code，更專注於打造穩健、可擴展的系統架構。

歡迎點擊這裡，填寫表單與我們的專家聊聊，讓我們幫助你打造更專業、更可靠的 WordPress 應用！