GraphQL 結構描述 - AWS AppSync GraphQL

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

GraphQL 結構描述

GraphQL 結構描述是 GraphQL API 的基礎。它可做為定義資料形狀的藍圖。它也是用戶端和伺服器之間的合約，定義如何擷取和/或修改您的資料。

GraphQL 結構描述是以結構描述定義語言 (SDL) 撰寫。SDL 由具有已建立結構的類型和欄位組成：

  • 類型：類型是 GraphQL 如何定義資料的形狀和行為。GraphQL 支援許多類型，本節稍後會說明這些類型。結構描述中定義的每個類型都會包含自己的範圍。範圍內的一個或多個欄位，可以包含 GraphQL 服務中使用的值或邏輯。類型會填入許多不同的角色，最常見的是物件或純量 （基本值類型）。

  • 欄位：欄位存在於 類型的範圍內，並保留從 GraphQL 服務請求的值。這些與其他程式設計語言的變數非常相似。您在欄位中定義的資料形狀將決定資料在請求/回應操作中的結構。這可讓開發人員在不了解服務的後端實作方式的情況下預測將傳回的內容。

若要視覺化結構描述的外觀，讓我們檢閱簡單 GraphQL 結構描述的內容。在生產程式碼中，您的結構描述通常位於名為 schema.graphql或 的檔案中schema.json。假設我們正在對等至實作 GraphQL 服務的專案。此專案正在儲存公司人員資料，而 schema.graphql 檔案會用來擷取人員資料，並將新人員新增至資料庫。程式碼看起來可能如下所示：

schema.graphql
type Person {                                  
   id: ID!
   name: String                                  
   age: Int
}
type Query {                                   
  people: [Person]
}
type Mutation {
  addPerson(id: ID!, name: String, age: Int): Person
}

我們可以看到結構描述中定義了三種類型：Person、 Query和 Mutation。查看 Person，我們可以猜測這是公司員工執行個體的藍圖，這會讓此類型成為物件。在其範圍內，我們看到 id、 name和 age。這些欄位定義 的屬性Person。這表示我們的資料來源會將每個 Person的 String 儲存name為純量 （基本） 類型和純量 age Int （基本） 類型。id 可做為每個 的特殊、唯一識別符Person。它也是以 !符號表示的必要值。

接下來的兩個物件類型行為不同。GraphQL 會為特殊物件類型保留一些關鍵字，以定義資料在結構描述中填入的方式。Query 類型會從來源擷取資料。在我們的範例中，我們的查詢可能會從資料庫擷取Person物件。這可能會提醒您 RESTful 術語中的GET操作。Mutation 將修改資料。在我們的範例中，我們的變動可能會將更多Person物件新增至資料庫。這可能會提醒您 PUT或 等狀態變更操作POST。本節稍後將說明所有特殊物件類型的行為。

假設範例中Query的 會從資料庫擷取物件。如果我們查看 的欄位Query，就會看到一個名為 的欄位people。其欄位值為 [Person]。這表示我們希望擷取Person資料庫中的一些 執行個體。不過，新增括號表示我們想要傳回所有Person執行個體的清單，而不只是特定執行個體。

Mutation 類型負責執行變更狀態的操作，例如資料修改。變動負責對資料來源執行一些狀態變更操作。在我們的範例中，我們的變動包含名為 的操作addPerson，可將新Person物件新增至資料庫。變動會使用 ，Person並預期 id、 name和 age 欄位的輸入。

此時，您可能會想知道，如果沒有程式碼實作，像是 addPerson 操作的運作方式，因為它應該會執行一些行為，看起來就像是具有函數名稱和參數的函數。目前，它無法運作，因為結構描述僅做為宣告。若要實作 的行為addPerson，我們必須新增解析程式。解析程式是程式碼單位，每當呼叫其相關聯的欄位時 （在此案例中為 addPerson操作） 就會執行。如果您想要使用 操作，您必須在某個時間點新增解析程式實作。透過某種方式，您可以將結構描述操作視為函數宣告，並將解析程式視為定義。解析程式將在不同的章節中說明。

此範例僅顯示結構描述操作資料的最簡單方式。您可以利用 GraphQL 和 的功能來建置複雜、強大且可擴展的應用程式 AWS AppSync。在下一節中，我們將定義您可以在結構描述中使用的所有不同類型和欄位行為。

如您所見，GraphQL 中有許多移動元件。在本節中，我們展示了簡單結構描述的結構，以及結構描述支援的不同類型和欄位。在下一節中，您將探索 GraphQL API 的其他元件，以及它們如何使用結構描述。