什麼是 GraphQL？
GraphQL 是一種與 API 通信的替代方式，特別適合複雜的資料結構及在其上構建介面。與將資料視為獨立的獨立片段不同，GraphQL 展示了資料片段如何連接和相互關聯，使獲取和接收資訊變得容易。
將 GraphQL 視為一種查詢語言，允許您如同直接與資料庫通信一樣與 API 交談。使用 GraphQL 能讓您盡可能接近資料庫，讓您挑選和選擇您想要的資料及獲取方式，帶來巨大的性能優勢。
GraphQL 由 Facebook 建立以解決複雜資料結構的擴展問題。由於他們成功採用，越來越多公司開始認識到 GraphQL 對其 API 的優勢。
已經了解 REST？GraphQL 會很熟悉。
GraphQL API 比您可能認為的更容易使用。如果您習慣使用 REST API，以下是 REST 的核心概念如何轉換為 GraphQL。
| 功能↕ | REST↕ | GraphQL↕ |
|---|---|---|
| 端點 | 請求向多個端點發送以進行不同的操作 | 所有請求都向單一端點發送（例如 /graphql） |
| 資料檢索 | 使用特定端點上的 GET 方法檢索資料 | 使用 查詢 來請求精確需要的資料，減少過度獲取或獲取不足 |
| 資料修改/操作 | 使用 HTTP 方法（如 POST、PUT、PATCH 或 DELETE）修改或處理資料。 | 使用 mutations 執行操作（例如，建立方，計算著陸成本） |
| 回應格式 | 固定的回應格式返回所有預定義欄位，無論是否需要 | 靈活的回應允許指定要包括的確切欄位，減少不必要的資料傳輸（如果這種靈活性感覺複雜，只需在我們的文件中使用預先編寫的查詢範例以獲得 REST 體驗） |
| 資料連接 | 通常需要多個請求來獲取相關資料 | 巢狀查詢能在單一請求中檢索相關資料（例如，方的詳細資訊和出貨項目一起）。使用者也可以構建工作流程以在單一 GraphQL 請求中管理多個 mutations，減少複雜性並提高效率 |
GraphQL 的優勢
更快的回應
GraphQL 透過精確的資料檢索、單一端點的使用以及改進的批次處理和快取能力提供更快的回應。
精確的資料檢索
REST 的一個常見挑戰是資料過度獲取或獲取不足——要麼獲取太多不必要的資訊，要麼在一個請求中獲取不足需要的資訊。GraphQL 透過允許請求正好所需的資料來消除這一點——不多不少。這種特異性不僅改進性能，還簡化了與 API 交互的過程，使系統更高效且用戶友好。
使用此方式的例子：
- 這允許前端開發人員獲取他們的 UI 元件所需的確切資料，減少伺服器的往返次數並改進性能。
- 想像您想獲得 HS 代碼分類、紙箱化、出貨評等和結帳時商品的著陸成本報價。如果您透過 GraphQL API 整合，您可以使用必要的 工作流程進行單一呼叫以獲取您所需的一切（以及您不需要的都沒有）在單一回應中。相比之下，使用 REST API，您需要先呼叫 分類 REST API，然後之後單獨呼叫 評等 REST API，最後將該分類和出貨評等插入您對 著陸成本 REST API的第三個呼叫中。所有這些 REST API 都會返回他們能提供的每一段資訊，導致您必須解析回應以找到您需要的資料。這種速度節省在購物者離開前快速返回完整著陸成本方面產生影響。
單一端點
GraphQL API 通常有單一端點，不像 REST API 通常為不同資源和操作有多個端點。這使 API 更簡單易管理和理解。
批次處理和快取
GraphQL 的批次查詢能力及其對快取策略的支持導致顯著的性能改進。這些功能減少了網路和伺服器的負載，轉化為更快、更可靠的使用者交互。
定義明確的 schemas
GraphQL API 基於強型別 schema。此 schema 定義了可用資料的結構和可執行的操作。這提供了關於什麼資料可用以及如何存取的明確性，可以改進開發人員的生產力並減少錯誤。例如，前端團隊可以探索圖形以獲取他們所需的確切內容，而不是等待新的 REST 端點。
在不破壞現有客戶端的情況下改進的能力
在 GraphQL 中添加新功能或修改現有功能不會因為其靈活的查詢結構而中斷當前的整合。這種能力確保改進可以在不破壞與現有客戶端相容性的情況下進行。
最新的文件
得益於 GraphQL 的內省功能，文件會隨著每項更改自動生成和更新。這確保提供給開發人員的所有資訊都是最新的，減少與過時文件相關的整合問題和支持工單——這是 REST API 文件面臨的常見挑戰。
檢視我們的 GraphQL 文件和我們的 REST 文件以查看差異。
一個類比
想像您在一家餐廳，菜單讓您完全按照喜好訂購菜餚，相比之下另一家餐廳您只能選擇套餐。GraphQL 就像第一家餐廳：
- 獲取您想要的確切內容： 使用 GraphQL，您可以要求確切的資料，不多不少。想像您只想要菜名和價格，而不是整個配料清單。使用 REST API，您必須獲取整個菜的詳細資訊並忽略您不需要的部分。
- 組合自訂菜餚： 我們的 GraphQL API 可以輕鬆組合以建立更多自訂解決方案，類似於自助餐廳，您可以使用他們已經擁有的配料精確按照需要建立獨一無二的菜餚。相比之下，REST API 就像一家烘焙店，裝有預製商品的籃子——您只能訂購已經建立的東西，無法選擇只帶回您想要的一片。
- 較少等待： 由於您可以在單一請求中獲取所有您需要的資訊，這就像要求服務員一次帶來您的開胃菜、主菜和甜點，而不是在課程之間等待。大多數 REST API 需要您發送多個請求以獲取不同的資訊片段。
- 輕鬆更改訂單： 如果您的應用程式資料需求更改，GraphQL 可以更容易地調整。您只需更改您所需內容的查詢。使用 REST，您可能需要等待廚房（後端）為菜單建立新菜（端點），這需要更多時間。
GraphQL 相比 REST API 為獲取資料提供更多靈活性、效率和簡洁性，尤其是當您的需求更改或增長時。
Zonos 如何使用 GraphQL
在過去幾年現代化平台的過程中，Zonos 選擇使用 GraphQL 而非 REST 為我們的 API 構建新功能。我們決定這樣做是因為我們的資料是複雜且相互連接的，很像導致 Facebook 建立 GraphQL 的資料。這種複雜性使得難以構建可擴展的 REST API，因為開發人員需要獲取和使用資料的方式在實作間變化很大，而 REST 不靈活。
GraphQL 透過允許實作我們 API 的開發人員挑選和選擇確切的資料及他們想要它的方式，完美地解決了這個問題。這允許他們不需要 Zonos 為每種情況進行自訂工作（同時他們等待）就能將其配合他們的工作流程。
使用 GraphQL 和我們平台現代化的組合結果使我們的 API 性能更強，使將 Zonos 整合到您的系統變得更快，並使 Zonos 能夠更快速地交付新功能。
更好的功能
Zonos 持續開發新功能，GraphQL 是第一個（通常是唯一一個）接收這些更新的功能。相比之下，我們的 REST API 被視為生命週期結束，無法存取我們的許多新功能。
限於 GraphQL 的功能範例：
- Inclusive pricing
- Labels API
- New Checkout and Hello
- Box sizes in API response
- Dashboard reporting
- Ability to request a DDP quote if possible, but still return a DDU quote if DDP is unavailable to that country with that service level
- Detailed breakdown of duties, taxes, and fees (item-level information, specific fees)—Dashboard is powered by GraphQL and shows this data for all stores, but the REST API response does not include this level of detail
- Test mode (coming soon)
為什麼要使用 GraphQL
了解我們為什麼推薦透過 GraphQL 而非 REST 進行整合。
在 Zonos，我們為整合提供兩種主要 API 類型：GraphQL 和 REST。雖然 REST API 已經存在更長時間，可能對許多人更熟悉，但我們已轉向 GraphQL 以提供更高的靈活性和更快的創新速度。雖然兩種都仍然受支持，但本指南解釋了為什麼 GraphQL 不僅是我們整合的未來，也是整體整合的未來，並且是今天滿足您需求的更強大工具。