透過 HTTP 提供服務

HTTP 是使用 GraphQL 時最常見的用戶端伺服器協定選擇，因為它無所不在。以下是設定 GraphQL 伺服器透過 HTTP 執行的一些準則。

網路請求管線#

大多數現代網路架構使用管線模型，其中請求會傳遞到中間軟體堆疊（又稱篩選器/外掛程式）。當請求流經管線時，可以檢查、轉換、修改或終止請求並傳送回應。GraphQL 應置於所有驗證中間軟體之後，以便您可以存取與在 HTTP 端點處理常式中相同的會話和使用者資訊。

URI、路由#

HTTP 通常與 REST 關聯，而 REST 使用「資源」作為其核心概念。相反地，GraphQL 的概念模型是實體圖表。因此，GraphQL 中的實體不會由 URL 識別。相反地，GraphQL 伺服器在單一 URL/端點（通常為 /graphql）上執行，而針對特定服務的所有 GraphQL 請求都應導向此端點。

HTTP 方法、標頭和主體#

您的 GraphQL HTTP 伺服器應處理 HTTP GET 和 POST 方法。

GET 要求#

在收到 HTTP GET 要求時，GraphQL 查詢應指定在「查詢」查詢字串中。例如，如果我們要執行下列 GraphQL 查詢

{
  me {
    name
  }
}

此要求可透過 HTTP GET 傳送，如下所示

http://myapi/graphql?query={me{name}}

查詢變數可作為 JSON 編碼字串，傳送在稱為 variables 的其他查詢參數中。如果查詢包含多個命名操作，則 operationName 查詢參數可控制執行哪一個。

POST 要求#

標準 GraphQL POST 要求應使用 application/json 內容類型，並包含下列形式的 JSON 編碼主體

{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}

operationName 和 variables 是選用欄位。如果查詢中存在多個操作，則僅需要 operationName。

回應#

不論查詢和變數透過哪種方法傳送，回應都應以 JSON 格式傳回在要求的主體中。如同規格中所述，查詢可能會產生一些資料和一些錯誤，且這些應傳回在形式為

{
  "data": { ... },
  "errors": [ ... ]
}

的 JSON 物件中。如果未傳回任何錯誤，回應中不應存在 "errors" 欄位。如果未傳回任何資料，根據 GraphQL 規格，僅當執行期間未發生任何錯誤時，才應包含 "data" 欄位。

節點#

如果您使用 NodeJS，我們建議查看伺服器實作清單。

草案傳輸規範#

一個詳細的 HTTP 傳輸規範 正在開發中。儘管尚未定稿，但這些草案規範作為 GraphQL 客戶端和程式庫維護人員的單一真實來源，詳細說明如何使用 HTTP 傳輸公開和使用 GraphQL API。與語言規範不同，遵循規範並非強制性的，但大多數實作正朝向這些標準邁進，以最大化互操作性。