6. 构建模式
5m

概述

是时候从 "Hello world" 升级到 "Hello playlists" 了！

在本课中，我们将

  • 检查一个模型设计并创建一个 从中
  • 创建我们的第一个
  • 学习如何 一个 与 description

模型

首先，让我们看看 MusicMatcher 应用程序中的这个页面

A grid of featured playlists

它展示了一个精选的流行播放列表网格，您可能对此感兴趣！

分解每个播放列表，我们可以开始看到客户端应用程序需要哪些数据。这种将模型分解为数据片段的过程称为 模式优先设计。

The same mockup but with labels for each piece of data

播放列表需要名称和描述，这两者都是文本片段。

Strawberry 使用 代码优先 方法来实现 ，但仍然有助于牢记模式优先 设计 原则；考虑应用程序开发人员期望的类型和 ，以及我们的 函数将根据模型设计和数据进行定义。

类型 Playlist

让我们从 Playlist 类型开始。在 types 文件夹中，创建一个名为 playlist.py 的文件。

📦 odyssey-intro-strawberry
┣ 📂 api
┃ ┣ 📂 types
┃ ┃ ┣ 📄 __init__.py
┃ ┃ ┗ 📄 playlist.py
┃ ┣ 📄 __init__.py
┃ ┣ 📄 query.py
┃ ┗ 📄 schema.py
┣ 📄 // other folders & files

我们将在顶部导入 strawberry，定义类并对其应用 @strawberry.type 注释。

api/types/playlist.py
import strawberry


@strawberry.type
class Playlist:
    ...
    # Playlist properties go here

在 Playlist 类中，我们将首先将播放列表的名称定义为类型为 str 的属性。

api/types/playlist.py
name: str

默认情况下，此 是不可为空的，因此播放列表 需要 一个名称。

接下来，让我们定义播放列表的描述，它也是 str 类型。描述 可以 是 null，因此我们将使用 | None 语法将其标记为不可为空。

api/types/playlist.py
description: str | None

还有一件事！虽然它不是模型的一部分，但通常的做法也是为类定义一个 标识符。展望未来，当我们点击播放列表时，我们需要有一种方法来检索特定播放列表的详细信息，这正是标识符（或 ID）的用途。

ID 在 中表示为 ID 类型。Python 没有内置的 ID 类型，但幸运的是，Strawberry 提供了我们可以使用的 strawberry.ID 类型。

api/types/playlist.py
id: strawberry.ID

我们为播放列表定义的三个属性（id、name 和 description）充当这些 解析器 的 。在幕后，Strawberry 会根据属性名称自动为每个字段生成 。例如，name 将拥有一个返回 name 属性值的 。

探索模式

这个 Playlist 类在我们现在的 中是什么样子？让我们来了解一下！

我们首先需要将 Playlist 类注册到我们的 中。

打开 api/schema.py 文件并在文件顶部导入 Playlist 类。

api/schema.py
from .types.playlist import Playlist

接下来，在我们定义了 strawberry.Schema之后，我们将添加另一个名为 types 的参数，并将 Playlist 类分配到它接受的列表中。

api/schema.py
schema = strawberry.Schema(query=Query, types=[Playlist])

保存所有更改并重启服务器。

回到 Sandbox，让我们查看 Schema 页面。在左侧选择 Objects，然后点击 Playlist。

https://127.0.0.1:8000

Sandbox showing Schema Reference and Objects selected

太棒了，我们已经考虑了所有播放列表 ！

https://127.0.0.1:8000

Sandbox showing Playlist schema

现在，详细信息列显示“无描述”。虽然 名称现在感觉相当直观，但最好 架构的类型和字段，特别是对于我们 的使用者来说。

记录我们的架构

我们使用 描述 来 架构。（不要与我们的播放列表的描述 字段 混淆！）在 Strawberry 中，我们使用 description 的 strawberry.type，它接受一个 string 作为 来描述类型。

回到我们的 Playlist 类，让我们将 description 添加到 @strawberry.type 装饰器中。

api/types/playlist.py
@strawberry.type(
    description="A curated collection of tracks designed for a specific activity or mood."
)
class Playlist:
    ...

接下来，让我们添加 描述到 Playlist 中。我们将需要使用 strawberry.field 函数来处理每个 ，将 description 传递进去。

api/types/playlist.py
id: strawberry.ID = strawberry.field(description="The ID for the playlist.")
name: str = strawberry.field(description="The name of the playlist.")
description: str | None = strawberry.field(
    description="Describes the playlist, what to expect and entices the user to listen."
)

保存我们的更改并切换到 Sandbox 以查看我们清晰且有帮助的描述！

https://127.0.0.1:8000

Sandbox showing Playlist schema with descriptions

练习

以下哪些关于架构文档的陈述是正确的？
在 Apollo Sandbox 中，你会导航到哪个页面以获取关于你的 GraphQL 架构的详细参考？

关键要点

  • 将模型分解成数据片段并根据客户端应用程序需求实现功能被称为架构优先设计。
  • 在 strawberry.field 和 strawberry.type 上的 用于为 GraphQL 类型和 添加清晰且有帮助的描述。它将在 GraphQL IDE（如 ）中显示。
  • The strawberry.ID 类型定义了 类型的标识符。它表示相关属性代表一个唯一的标识符。

下一步

我们需要一种方法来 播放列表。现在，它只是漂浮在我们的架构中，没有办法访问它。让我们通过我们的 Query 类型（我们架构的入口点）来使其可用！

上一个

分享你关于这节课的问题和评论

本课程目前处于

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

你需要一个 GitHub 帐户才能在下面发帖。没有帐户吗？ 请改为在我们 Odyssey 论坛上发帖。