REST API 連 AI 都看不懂？WordPress JSON 設計原則實戰

有個話題每次碰到都讓我血壓升高：API 設計。接手過幾個被遺棄的專案之後，我發現糟糕的端點命名與混亂的 JSON 結構，不只折磨人類工程師，連 AI 都解析不動。這篇就來談 2026 年 WordPress REST API 該有的設計原則。

現在是 2026 年了，我前幾天接手了一個被遺棄的專案，打開它的 API 文件（如果有那種東西的話），我差點把剛沖好的手沖咖啡噴在螢幕上。為什麼？因為我看到了一個 Endpiont 叫做 /getAllDataAndDoSomething_v2_final，而且不管發生什麼錯誤，它永遠回傳 HTTP 200 OK，然後在 JSON 裡藏一個 "error": "true"。

各位，寫程式是一種藝術，不是在煮大雜燴。特別是在 WordPress 的世界裡，REST API 已經是與外部系統溝通的標準語言。如果你的 API 設計得像義大利麵一樣糾纏不清，不只前端工程師會恨你，現在連負責串接的 AI Agent 都會因為讀不懂你的 Schema 而罷工。

這篇文章不談高深的哲學，我們談實戰。我們要談如何用 WordPress 內建的 register_rest_route 寫出優雅、標準、符合 REST + JSON 原則的 API。這不僅是為了讓程式碼好看，更是為了可維護性與擴展性。

為什麼 2026 年我們還在堅持 REST？

我知道你們想說什麼：「Eric，現在不是都在用 GraphQL 或是 tRPC 了嗎？」

沒錯，那些技術很棒。但在 WordPress 的生態系中，REST API 依然是王者。為什麼？因為它利用了 HTTP 協議本身的特性（如快取、狀態碼），而且對於 Headless 架構來說，REST 的資源導向（Resource-Oriented）概念是最容易被理解與標準化的。

特別是在 2026 年，我們大量的開發工作已經交給 AI 輔助。AI 對於標準化的 REST 結構理解能力極強。一個設計良好的 REST API，配合清晰的 JSON 回傳格式，可以讓 Cursor 或 GitHub Copilot 在幾秒鐘內幫你生成完整的前端串接程式碼。反之，如果你的 API 毫無邏輯，AI 也救不了你。

核心原則一：URI 是名詞，不是動詞

這是我最常看到的錯誤。REST 的核心在於「資源（Resource）」。你的 URL 應該代表「東西」，而不是「動作」。

❌ 錯誤的設計（像在寫 RPC）：

• /wp-json/my-plugin/get-products
• /wp-json/my-plugin/create-new-order
• /wp-json/my-plugin/deleteUser

✅ 正確的設計（RESTful）：

• /wp-json/my-shop/v1/products (取得產品列表)
• /wp-json/my-shop/v1/orders (新增訂單)
• /wp-json/my-shop/v1/users/123 (刪除特定使用者)

看出差別了嗎？URL 保持乾淨，動作交給 HTTP Method 來決定。

核心原則二：善用 HTTP 動詞，別再一招 POST 打天下

很多新手工程師（甚至一些資深的懶惰工程師）喜歡把所有請求都用 POST。他們會說：「啊瀏覽器有時候會快取 GET 請求很麻煩耶。」

聽我一句勸，別這樣做。HTTP 協議設計這些動詞是有意義的，正確使用它們可以讓你的 API 語意清晰，並且讓 CDN 和中間層知道該如何處理快取。

• GET：讀取資源。這是「安全」且「冪等（Idempotent）」的操作，不該改變伺服器狀態。
• POST：建立新資源。通常不具備冪等性。
• PUT：完整更新資源（覆蓋）。
• PATCH：部分更新資源（只改這幾個欄位）。
• DELETE：刪除資源。

在 WordPress 中註冊路由時，請務必指定正確的 methods：

register_rest_route( 'my-shop/v1', '/products/(?P<id>\d+)', array(
    'methods'  => 'PATCH',
    'callback' => 'update_product_price',
    'permission_callback' => function() {
        return current_user_can( 'edit_products' );
    }
));

核心原則三：JSON 回傳格式的「信封模式」與命名慣例

現在來到重點了：JSON。API 的回應不應該只是一坨裸露的數據。你需要一個標準的結構，我們通常稱為「信封（Envelope）」。

1. 統一的命名風格 (Case Convention)

WordPress 核心與資料庫欄位習慣使用 snake_case (如 post_title)，但在 JavaScript 前端世界（React/Vue）習慣使用 camelCase (如 postTitle)。

在 WordPress REST API 開發中，我強烈建議遵循 WordPress 的標準，保持 snake_case。為什麼？因為當你使用 wp_insert_post 或處理資料庫時，你不需要在那邊轉來轉去。如果前端需要 camelCase，讓他們用 Axios 的攔截器去轉換，或者使用像 humps 這樣的庫。後端保持一致性最重要。

2. 結構化的回應

不要直接回傳一個陣列。你的 JSON 應該包含元數據（Metadata），這對於分頁（Pagination）特別重要。

✅ 推薦的 JSON 結構：

{
  "success": true,
  "data": [
    {
      "id": 101,
      "product_name": "藍色馬克杯",
      "price": 350
    }
  ],
  "meta": {
    "total_count": 50,
    "total_pages": 5,
    "current_page": 1
  }
}

核心原則四：HTTP 狀態碼不是裝飾品

這是我最不能忍受的地雷。請不要在發生錯誤時回傳 HTTP 200，然後在 JSON 裡寫 "status": "error"。

HTTP 狀態碼是全球通用的語言：

• 200 OK：成功。
• 201 Created：成功建立資源（POST 回應）。
• 400 Bad Request：客戶端送來的資料格式不對（例如 JSON 缺欄位）。
• 401 Unauthorized：你沒登入，我不認識你。
• 403 Forbidden：我認識你，但你權限不足（例如訂閱者想刪文章）。
• 404 Not Found：找不到資源。
• 429 Too Many Requests：你太急了，被 Rate Limit 擋下來了。
• 500 Internal Server Error：程式碼炸了，這是我的錯。

在 WordPress 中，你可以透過 WP_Error 來回傳正確的狀態碼：

if ( empty( $request['price'] ) ) {
    return new WP_Error( 
        'missing_price', 
        '價格欄位是必填的', 
        array( 'status' => 400 ) 
    );
}

這樣前端接到 400，就會進入 catch 區塊，邏輯清晰又乾淨。

2026 年的進階思維：為 AI 準備的 Context 與 Schema

在 2026 年，很多時候呼叫你 API 的不是人類寫的程式，而是 AI Agent。為了讓 AI 能更有效率地理解你的 API，有兩點非常重要：

1. Schema 定義：在 register_rest_route 中，務必定義 schema 回呼函式。這會自動出現在 OPTIONS 請求中，讓 AI 知道這個端點接受什麼參數、回傳什麼格式。
2. 情境式過濾 (Context Filtering)：支援 _fields 參數。AI 呼叫 API 時往往需要節省 Token，如果你的 API 支援只回傳需要的欄位（例如 GET /products?_fields=id,price），這會大幅提升 AI 處理的效能。

總結：好的 API 是優雅的溝通

設計 API 不只是把資料庫撈出來噴成 JSON。它是一種溝通介面，體現了你對系統架構的理解。遵循 REST 原則、使用正確的 HTTP 動詞與狀態碼、規範 JSON 結構，這些看似龜毛的要求，其實是在為未來的你自己（和接手你程式碼的可憐人）省下無數的加班夜晚。

寫程式要有「儀式感」，把每一個 Endpoint 當作一個精緻的產品來設計，這才是一個資深工程師該有的素養。

延伸閱讀

想更深入了解如何打造堅固的 WordPress API 架構嗎？建議你參考以下這幾篇我整理的實戰指南：

• API 回傳一坨垃圾？資深工程師教你用 JSON Schema 打造 WordPress 堅不可摧的資料驗證層
• WordPress 只能寫文章？錯！資深工程師手把手教你用 REST API 自訂端點，打造無頭應用超能力！
• API 半夜又斷線？資深工程師的 WordPress API 串接防爆聖經：從 Rate Limit 到優雅重試 (Exponential Backoff)