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

# GraphQL 結構描述
<a name="schema-components"></a>

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 的其他元件，以及它們如何使用結構描述。