REST vs GraphQL：為你的專案選擇 API 設計
你正開始一個新專案，需要設計 API。REST 與 GraphQL 之間的爭論經常出現，但哪一個才適合你的使用情境？本文將拆解實務上的差異、取捨與決策因素，幫助你自信地做出選擇。
什麼是 REST？
REST（Representational State Transfer）是一種分散式系統的架構風格。它依賴無狀態的客戶端-伺服器通訊，通常透過 HTTP 進行。資源由 URL 標識，標準 HTTP 方法（GET、POST、PUT、DELETE）定義操作。
關鍵特性：
- 資源導向：每個端點代表一個資源（例如
/users/123）。 - 無狀態：每個請求包含所有必要資訊；伺服器不儲存客戶端上下文。
- 可快取：回應可使用 HTTP 標頭進行快取。
- 統一介面：一致的命名與方法簡化了互動。
REST 成熟、被廣泛採用，並且與 HTTP 快取、負載平衡器和 API 閘道搭配良好。
什麼是 GraphQL？
GraphQL 是一種 API 的查詢語言與執行環境，由 Facebook 於 2012 年開發，並於 2015 年開源。它允許客戶端請求確切需要的資料，不多也不少。單一端點（/graphql）處理所有查詢與變更。
關鍵特性：
- 客戶端驅動查詢：客戶端指定回應的形狀。
- 強型別結構描述：API 由結構描述定義，可進行驗證與內省。
- 單一請求取得多個資源：避免過度擷取與擷取不足。
- 即時能力：訂閱功能可實現推送式更新。
GraphQL 在現代前端框架（React、Vue）和行動應用中很受歡迎，因為頻寬與靈活性很重要。
主要差異：REST vs GraphQL
| 面向 | REST | GraphQL |
|---|---|---|
| 端點結構 | 每個資源有多個端點 | 單一端點 |
| 資料擷取 | 固定回應；可能過度或不足擷取 | 客戶端指定確切欄位 |
| 快取 | HTTP 快取（ETags、Cache-Control） | 複雜；需要客戶端或持久化查詢 |
| 版本控制 | URL 或標頭版本控制 | 結構描述演進；無版本控制 |
| 錯誤處理 | HTTP 狀態碼 | 200 OK 搭配 errors 陣列 |
| 學習曲線 | 低；熟悉的 HTTP 模式 | 中等；需要結構描述與查詢語言 |
| 工具 | 成熟（Swagger、Postman） | 成長中（Apollo、GraphiQL） |
何時選擇 REST
REST 通常是以下情況的務實選擇：
- 簡單的 CRUD API：如果你的資料模型自然對應到資源，且操作直觀。
- 公開 API：REST 的簡潔性與 HTTP 快取使其成為外部開發者的理想選擇。
- 微服務：每個服務可以暴露自己的 REST 端點，促進鬆散耦合。
- API 新手團隊：學習曲線較平緩，且工具無所不在。
- 檔案上傳/下載：REST 能很好地處理二進位資料與串流。
何時選擇 GraphQL
GraphQL 在以下情況表現出色：
- 客戶端需求各異：行動與網頁客戶端需要不同的資料形狀；GraphQL 避免多次往返。
- 快速前端迭代：前端團隊可以調整查詢而無需後端變更。
- 聚合多個來源：GraphQL 可以統一來自微服務、資料庫和第三方 API 的資料。
- 即時功能：訂閱提供高效的推送更新。
- 強型別與內省：結構描述作為活文件，並啟用強大的工具。
效能考量
REST 使用 HTTP 快取可以大幅降低伺服器負載。GraphQL 由於單一端點和 POST 請求，在 HTTP 層較難快取。解決方案包括持久化查詢、使用 GET 的 CDN 快取，以及像 Apollo 這樣的客戶端快取。
如果解析器未最佳化，GraphQL 也可能遇到 N+1 查詢問題。像 DataLoader 這樣的工具會批次處理請求來緩解此問題。REST 由於端點固定，通常具有更可預測的效能。
安全性影響
兩種方法都需要注意安全性：
- REST：使用 HTTPS、驗證輸入、實作速率限制，並遵循 OWASP 指南。
- GraphQL：限制查詢深度與複雜度以防止 DoS、在生產環境中停用內省，並實作查詢白名單。
GraphQL 的靈活性可能是一把雙面刃；惡意客戶端可以精心設計昂貴的查詢。基於查詢成本的速率限制至關重要。
如何決定：逐步指南
- 識別你的客戶端：它們是否多樣（行動、網頁、第三方）？GraphQL 可能減少過度擷取。
- 評估資料關係：高度連接的資料受益於 GraphQL 的圖形模型。
- 評估快取需求：如果 HTTP 快取至關重要，REST 更簡單。
- 考慮團隊專業知識：REST 更容易採用；GraphQL 需要結構描述設計與解析器最佳化。
- 規劃演進：REST 版本控制 vs GraphQL 的附加式結構描述變更。
- 製作原型：用兩者建構一個小功能，以評估開發者體驗。
可以兩者並用嗎？
可以。有些團隊使用 REST 作為公開 API，並使用 GraphQL 進行內部前端聚合。或者他們從 REST 開始，之後再加入 GraphQL。混合方法並沒有任何規則禁止。
常見問題
GraphQL 總是比 REST 好嗎？
不。GraphQL 解決了特定問題，如過度擷取和多次往返，但 REST 更簡單、更易快取，且通常已足夠。最佳選擇取決於你專案的需求。
我可以快取 GraphQL 回應嗎？
可以，但更複雜。你可以使用持久化查詢、使用 GET 請求的 CDN 快取，或客戶端快取。HTTP 快取不像 REST 那樣直接。
如何保護 GraphQL API？
實作查詢深度與複雜度限制、在生產環境中停用內省、使用基於查詢成本的速率限制，並驗證所有輸入。與 REST 類似，但有 GraphQL 特有的考量。
結論
REST 和 GraphQL 都是強大的工具。REST 在簡潔性、快取和廣泛採用方面表現出色。GraphQL 為複雜資料圖提供靈活性、效率和強型別。評估你專案的需求、團隊技能和長期維護，以做出明智的決定。
當你需要檢查或格式化 API 回應時，試試我們的 JSON Formatter 來快速驗證和美化 JSON 資料。