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

3. 架构定义语言 (SDL)

概述

为了开始将我们 GraphQL 服务器的各个部分拼凑起来，我们需要仔细研究 架构定义语言，即 SDL。它允许我们用 GraphQL 服务器可理解的方式定义对象类型及其字段。

在本课中，我们将

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

📄 探索 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 Explorer 等工具在 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]StringIntString!

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

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

以下哪些关于 Query 类型的描述始终正确？

它定义了我们模式的入口点。它包含其他所有模式类型对应的字段。它的字段不能为 null。它定义了客户端可以在我们模式中查询哪些数据。

关键要点

字段是 Query 类型的入口点。它们是 GraphQL 消费者可以查询的顶级字段。
GraphQL 对象类型定义了我们可以在其中查询数据的字段。这些字段可以返回标量数据（例如 String 或 Int ）或返回其他对象类型。

下一步

最后一点已经介绍完毕，让我们进入下一节课并构建我们的模式！

分享您关于本节课的问题和评论

本课程目前处于

测试版

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

您需要一个 GitHub 帐户才能在下面发帖。没有帐户？请在我们的 Odyssey 论坛中发帖。