SDL - GraphQL 架构定义语言 - GraphQL 教程

3. 架构定义语言 (SDL)

概述

为了开始将我们 GraphQL 服务器的各个部分拼凑在一起，我们需要仔细研究 架构定义语言，或 SDL。这是让我们能够实际定义对象类型及其字段的语法，以便 GraphQL 服务器能够理解。

在本课中，我们将

探索 SDL 语法
使用一个Query 和一个 Listing 类型来定义基本架构
添加我们的 DGS 依赖项

📄 探索 SDL

您可以将我们的服务器的架构视为契约，服务器与任何请求数据的客户端之间达成协议。它定义了 GraphQL API 可以做什么和不能做什么，以及客户端如何请求或更改数据。它是一个抽象层，为使用者提供灵活性，同时隐藏后端实现细节。

在实践中，架构是 对象类型 的集合，包含字段。每个字段都有自己的类型。字段的类型可以是标量（例如 Int 或 String），或者可以是 另一个对象类型。我们很快就会看到一个例子。

GraphQL 类型语法

我们使用 type 关键字声明类型，后面跟着类型的名称（PascalCase 是最佳实践），然后用大括号括起其字段：

示例 GraphQL 类型

type Planet {

}

字段由其名称（camelCase）、冒号，然后是字段的类型（标量或对象）来声明。字段还可以包含列表，用方括号表示：

type Planet {
  id: ID
  name: String
  mass: Int
  namesOfMoons: [String]
}

仔细研究 namesOfMoons 字段；它返回列表的 String 类型。

namesOfMoons: [String]

这种表示让我们可以想象 namesOfMoons 数据可能采用的形状：

{
  "namesOfMoons": [
    "Calypso",
    "Argo XIV",
    "Telemachus-5"
  ]
}

在架构的未来迭代中，我们可能会决定使用每个名称来构建一个单独的 Moon 类型，这将让我们能够更详细地描述特定卫星的数据。现在，这个简单的示例旨在说明 GraphQL 列表语法的用途。

GraphQL 中的可空性

此外，我们可以指示每个字段值是可空还是不可空。如果字段永远不能为 null，我们在其类型后面添加一个感叹号：

type Planet {
  id: ID!
  name: String!
  mass: Int
  namesOfMoons: [String]
}

此语法表明，对于 Planet 返回 null 用于 id 或 name 字段是无效的；我们要求它们返回与指定数据类型匹配的值。相反，我们将允许 mass 和 namesOfMoons 为 null，如果我们没有数据要返回。

一种方法是使架构反映我们的“业务”领域规则。

type Planet {
  id: ID! # REQUIRED!
  name: String! # REQUIRED!
  mass: Int 
  namesOfMoons: [String]
}

考虑到上面的 Planet 类型，如果我们缺少唯一标识符（id 字段）或 name，我们将难以使用这些数据。允许这些字段 ใดใด 返回 null 从我们的“业务”角度来看没有意义。

但是，我们可能对 namesOfMoons 或 mass 的感受没有那么强烈：毕竟，行星可能没有卫星，我们可能不知道行星的质量！

使用多个对象类型

GraphQL 还让我们能够表示之间对象的关系。例如，这两个对象类型：

type Planet {
  id: ID!
  name: String!
  mass: Int
}

type Galaxy {
  id: ID!
  name: String!
  yearDiscovered: Int
}

假设我们要表示行星和星系之间的关系。例如，我们可能希望每个行星都指明它所属的星系。我们如何在 GraphQL 中表示这一点？

在这种情况下，我们可以使用 Planet 更新一个字段，该字段返回 另一个 对象类型；指定它所属的哪个星系。

type Planet {
  id: ID!
  name: String!
  mass: Int
  galaxy: Galaxy
}

type Galaxy {
  id: ID!
  name: String!
  yearDiscovered: Int
}

这种关系让我们能够查询关于行星的详细信息，然后查询它所在的星系的更多详细信息。我们可以对我们的数据提出更复杂的问题——比如 “这颗行星的质量是多少，它所属的星系叫什么名字？”——并在一个整齐打包的响应中获得所有答案。

记录架构

好的，在我们开始编写架构之前，最后一点：描述。

记录你的架构是一个好习惯，就像对你的代码添加注释一样有帮助。它使你的队友（和未来的你）更容易理解发生了什么事。它还允许 GraphOS Studio 资源管理器等工具在 API 使用者需要的时候和地方引导他们了解你的 API 可以实现什么。

为此，SDL 允许你通过在类型和字段上方直接写入字符串（用引号括起来）来添加描述。

"I'm a regular description"

三对“双引号”允许你添加换行符，以便更清楚地格式化较长的注释。

"""
I'm a block description
with a line break
"""

以下是完全记录的 GraphQL 类型的示例。

"Astronomical information for a single planet."
type Planet {
  "The ID for the planet"
  id: ID!
  "The planet's name"
  name: String!
  "The total estimated mass of the planet (in kg)"
  mass: Int
  "The galaxy the planet is located in"
  galaxy: Galaxy
}

练习

以下哪些是有效的字段类型？

[Int]字符串整数字符串!

字段类型后面的感叹号表示什么？

该字段有默认值。该字段的值可以为空。该字段是标量类型。该字段的值不能为空。

以下哪些关于 Query 类型的描述始终为真？

它定义了客户端可以在我们的模式中查询的数据。它定义了进入我们模式的入口点。它的字段不能为空。它包含每个其他模式类型的字段。

关键要点

The fields of the Query type are entry points into our schema. These are the top-level fields that a GraphQL consumer can query for.
GraphQL object types define fields we can query for data. These fields can return scalar data (such as String or Int) or return other object types.

接下来

最后一点内容已经讲解完毕，让我们开始下一课，构建我们的模式！

上一课

下一课

分享你对本课的疑问和评论

本课程目前处于

测试版

.你的反馈有助于我们改进！如果你卡住或困惑，请告知我们，我们会帮助你。所有评论都是公开的，必须遵守 Apollo行为准则。请注意，已解决或处理的评论可能会被删除。

你需要一个GitHub账户才能在下方发布。没有账户？请改为在我们的Odyssey论坛中发布。