GraphQL

GraphQL 是一種用於 API 的查詢語言，也是一個使用您現有資料來滿足這些查詢的執行環境。它由 Facebook 於 2012 年開發，並於 2015 年開源。

與 REST 不同，REST 為不同的資源暴露多個端點（例如 /users, /posts, /comments），GraphQL 通常暴露單一端點（通常是 /graphql）。客戶端發送一個描述它們確切需要的資料結構的查詢，伺服器返回符合該結構的 JSON 回應。

核心概念

Schema (SDL)：客戶端和伺服器之間的契約。它定義了類型和關係。

Query：唯讀的獲取操作（相當於 GET）。

Mutation：寫入操作（相當於 POST/PUT/DELETE）。

Subscription：用於即時更新的通用長效連線。

Resolver：為 schema 中的每個欄位檢索實際資料的函式。

程式碼範例：Schema

在 GraphQL 中，您使用 Schema Definition Language (SDL) 定義類型：

比較：GraphQL vs. REST

功能	REST	GraphQL
端點	多個（基於資源）	單一（通常是 `/graphql`）
資料獲取	固定結構（過度獲取 Over-fetching / 獲取不足 Under-fetching）	客戶端定義確切結構
版本控制	v1, v2 URL 前綴	透過棄用演進（schema 優先）
快取	內建 HTTP 快取	需要專門的設定（例如 Apollo）
效能	較大的負載，簡單的處理	較小的負載，複雜的伺服器處理

何時使用 GraphQL？

行動應用程式：透過僅獲取所需欄位來最小化頻寬。解決了串連多個 API 呼叫的「瀑布 (waterfall)」問題。

微服務聚合：GraphQL「Gateway」可以將來自多個後端微服務的資料縫合到一個統一的前端 API 中。

快速迭代：前端團隊可以修改查詢以獲取新資料，而無需等待後端團隊建立新端點。

在 Apidog 中除錯 GraphQL

Apidog 提供一流的 GraphQL 客戶端體驗，包括 schema 內省 (introspection) 和文件生成。

1. 建立請求

建立一個新端點。

將方法設定為 POST。

在 Body 分頁中，選擇 GraphQL。

2. 智慧查詢編輯

利用 Apidog 的內省功能：

獲取 Schema：點擊 Fetch Schema 從伺服器下載類型定義。

自動完成：在編輯器中輸入以查看可用的欄位、類型和參數。

驗證：針對 schema 進行即時錯誤檢查。

3. 使用變數

Apidog 支援使用 Query Variables 將查詢邏輯與資料值分開。

查詢：

變數 (JSON)：

{
  "id": "123"
}

查看詳情 GraphQL

關鍵收穫

單一端點：GraphQL 使用單一 URL（例如 /graphql）進行所有資料互動。

客戶端規格：客戶端確切定義它們需要什麼資料，防止過度獲取和獲取不足。

強型別：Schema Definition Language (SDL) 確保了客戶端和伺服器之間的嚴格契約。

內省：Apidog 可以「讀取」您的 GraphQL schema 以自動提供自動完成和文件。

繼續閱讀 → gRPC

核心概念#

程式碼範例：Schema#

比較：GraphQL vs. REST#

何時使用 GraphQL？#

在 Apidog 中除錯 GraphQL#

1. 建立請求#

2. 智慧查詢編輯#

3. 使用變數#

關鍵收穫#