綱要

圖 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
}

我們可以看到，在結構描述中定義了三種類型：PersonQuery、、和Mutation。看著Person，我們可以猜測，這是一個公司員工的實例的藍圖，這將使這種類型的對象。在它的範圍內，我們看到idname、、和age。這些是定義的屬性的字段Person。這意味著我們的數據源將每個Person數據源存儲name為String標量（原始）類型和ageInt標量（原始）類型。作id為每個標識符的特殊唯一標識符Person。這也是由!符號表示的必需值。

接下來的兩個物件類型的行為不同。GraphQL 會針對特殊物件類型保留幾個關鍵字，這些關鍵字會定義資料在結構描述中的填入方式。Query類型將從源中檢索數據。在我們的例子中，我們的查詢可能會從數據庫中檢索Person對象。這可能會提醒您 RESTful 術語中的GET操作。A Mutation 將修改數據。在我們的例子中，我們的突變可能會向數據庫添加更多Person對象。這可能會讓您想起或之類PUT的狀態變化操作。POST本節稍後將說明所有特殊物件類型的行為。

讓我們假設Query在我們的例子將從數據庫中檢索的東西。如果我們看一下的領域Query，我們看到一個名為字段people。其欄位值為[Person]。這意味著我們要檢索數據庫Person中的某些實例。但是，添加括號意味著我們要返回所有Person實例的列表，而不僅僅是一個特定的實例。

該Mutation類型負責執行狀態更改操作，如數據修改。突變負責對數據源執行某些狀態更改操作。在我們的例子中，我們的突變包含一個名為的操作，addPerson該操作將新Person對象添加到數據庫中。突變使用 a，Person並且需要idname、和age欄位的輸入。

在這一點上，您可能想知道這樣的操addPerson作如何在沒有代碼實現的情況下工作，因為它應該執行某些行為並且看起來很像具有函數名稱和參數的函數。目前，它將不起作用，因為模式僅用作聲明。為了實現的行為addPerson，我們將不得不向其添加一個解析器。解析器是每當調用其關聯字段（在本例中為addPerson操作）時執行的代碼單元。如果你想使用一個操作，你必須在某個時候添加解析器實現。在某種程度上，您可以將模式操作視為函數聲明，並將解析器視為定義。解析器將在不同的部分中進行說明。

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

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