GraphQL 参数

11. GraphQL 参数

概述

继续我们下一个功能！

在本课中，我们将

了解GraphQL 参数以及如何在解析器函数中访问它们
了解如何在 GraphQL 操作中使用变量

模型

这是我们的下一个功能：播放列表页面。

Mockup of the playlist page

我们很可能通过几种方式到达此页面：从特色播放列表页面点击特定的播放列表，或者可能直接通过 URL 链接。

无论我们如何到达此页面，我们都需要播放列表 ID，这使其成为使用 GraphQL 参数的完美用例。

一个参数是您为查询中的特定字段提供的值。

解析器可以使用字段提供的参数来帮助确定如何填充该字段的数据。参数可以帮助检索特定对象，过滤一组对象，甚至转换字段的返回值。例如，执行搜索的查询通常会将用户的搜索词作为参数提供。

新的入口点

我们的模式再次演变！我们正在添加一个新的入口点。

在Query 类中，我们将添加一个新的解析器称为 playlist，它返回一个可为空的 Playlist 类型。我们将其设为可为空，因为我们正在查找的播放列表可能不存在（例如，它可能已被删除）。

此解析器将是 async 的，我们将使用 strawberry.field 作为装饰器。

api/query.py

@strawberry.field
async def playlist(self) -> Playlist | None:
    ...

记住，在 self 作为参数添加到解析器函数内部是一个良好的做法。

我们还将添加另一个参数： id 类型为 strawberry.ID 表示它应该在 GraphQL 中为 ID 类型。

请注意， id 参数可以命名为任何东西，例如 playlist_id！我们建议与您的团队协商命名约定。使用 id 作为 GraphQL 参数名称是一种常见约定。

api/query.py

@strawberry.field
async def playlist(
  self,
  id: strawberry.ID
) -> Playlist | None:
    ...

我们还将包含 info 参数，我们稍后将使用它来访问 spotify_client：

api/query.py

@strawberry.field
async def playlist(
  self,
  id: strawberry.ID,
  info: strawberry.Info
) -> Playlist | None:
    ...

在文件顶部，让我们导入一个从 mock_spotify_rest_api_client 包中获取播放列表的函数，称为 get_playlist。

api/query.py

from mock_spotify_rest_api_client.api.playlists import get_playlist

现在回到 playlist 解析器，让我们使用此函数从 REST API 获取播放列表数据。我们将传入相同的 spotify_client 值，以及 id 参数，用于函数期望的 playlist_id 参数。

与 featured_playlists 解析器一样，我们将 await 结果并将它们存储在 data 变量中。

api/query.py

spotify_client = info.context["spotify_client"]
data = await get_playlist.asyncio(client=spotify_client, playlist_id=id)

如果 data 是 None，这很可能意味着没有具有该特定 ID 的播放列表。在这种情况下，我们将返回 None。

api/query.py

if data is None:
    return None

此解析器需要返回一个 Playlist 类型，但 data（如果它不是 None）是一个 SpotifyObjectPlaylist 类型。

所以让我们用我们拥有的数据属性创建一个新的 Playlist 对象，并返回它。

api/query.py

return Playlist(
    id=strawberry.ID(data.id),
    name=data.name,
    description=data.description,
)

不要忘记 GraphQL 对解析器的描述！我们可以将其添加到 @strawberry.field 装饰器中。

api/query.py

@strawberry.field(description="Retrieves a specific playlist.")

import strawberry
from mock_spotify_rest_api_client.api.playlists import get_featured_playlists
from mock_spotify_rest_api_client.api.playlists import get_playlist
from .types.playlist import Playlist

@strawberry.type
class Query:
    @strawberry.field(description="Playlists hand-picked to be featured to all users.")
    async def featured_playlists(self, info: strawberry.Info) -> list[Playlist]:
        spotify_client = info.context["spotify_client"]

        data = await get_featured_playlists.asyncio(client=spotify_client)

        return [
            Playlist(
                id=strawberry.ID(playlist.id),
                name=playlist.name,
                description=playlist.description,
            )
            for playlist in data.playlists.items
        ]

    @strawberry.field(description="Retrieves a specific playlist.")
    async def playlist(
        self,
        id: strawberry.ID,
        info: strawberry.Info
    ) -> Playlist | None:
        spotify_client = info.context["spotify_client"]

        data = await get_playlist.asyncio(client=spotify_client, playlist_id=id)

        if data is None:
            return None

        return Playlist(
            id=strawberry.ID(data.id),
            name=data.name,
            description=data.description,
        )

让我们保存更改并确保我们的服务器仍然成功运行，没有任何问题。

探索时间！

是时候看看我们的 GraphQL 模式在这些更改后是如何演变的！让我们回到 Sandbox 并创建一个新的工作区。

在 Explorer 页面中，导航回 Query 类型的根节点文档面板，我们可以看到一个新的字段： playlist(...) 字段。

单击“字段”旁边的 + 按钮，将所有三个播放列表字段添加到操作中。

https://127.0.0.1:8000

GetPlaylist operation in Sandbox

query Playlist($playlistId: ID!) {
  playlist(id: $playlistId) {
    id
    name
    description
  }
}

我们在这里会注意到一些新东西：一个美元符号 ($) 后面跟着名称 playlistId。

变量

在 $ 符号表示变量在 GraphQL 中。 $ 符号后面的名称是我们变量的名称，我们可以在整个查询中使用它。冒号后面的变量类型必须与我们将用于它的参数的类型匹配。

变量很棒，它们允许我们动态地从客户端传递参数值，因此我们不必将值硬编码到我们的查询中。每当我们使用参数创建查询时，都会使用它们。

在我们的例子中，我们有一个名为 playlistId 的变量，它由 Explorer 在下面的变量部分为我们设置。现在，它被设置为 null。

https://127.0.0.1:8000

GetPlaylist operation with null variable

如果我们现在尝试运行查询，我们仍然会得到一个 JSON 对象，但这次它包含一个 errors 键，而不是 data：

响应

{
  "errors": [
    {
      "message": "Variable `playlistId` is required.",
      "locations": [
        {
          "line": 1,
          "column": 16
        }
      ],
      "extensions": {
        "code": "HC0018",
        "variable": "playlistId"
      }
    }
  ]
}

这让我们知道我们不能将 playlistId 设为 null，因为模式专门将 id 参数 (我们在使用 playlistId 变量) 定义为不可为空的类型！

让我们继续更新 null 值，使其成为我们从 featuredPlaylists 查询中知道存在的播放列表 ID。

变量

{
  "playlistId": "6Fl8d6KF0O4V5kFdbzalfW"
}

最后，我们将操作重命名为更具描述性的名称，例如 GetPlaylistDetails。

GraphQL 操作

query GetPlaylistDetails($playlistId: ID!) {
  playlist(id: $playlistId) {
    id
    name
    description
  }
}

运行查询以获取 Sweet Beats & Eats 播放列表的详细信息！

https://127.0.0.1:8000

GetPlaylist operation with playlistId

练习

GraphQL 参数在解析器中的目的是什么？

为了定义解析器的資料來源。指定解析器的返回类型。过滤和转换特定字段的資料。确定模式中的入口点。

为什么从 playlist 解析器返回的 Playlist 类型被标记为可为空的？

这是代码中的错误，它不应该可为空。表示播放列表可能不存在。允许解析器使用可选参数。这是 Hot Chocolate 的约定。

在 GraphQL 中，变量如何在查询中表示？

使用 var 关键字。用方括号 [ ] 包围。使用 ! 符号后跟变量名。使用 $ 符号后跟变量名。

主要收获

参数是为 GraphQL 查询中的特定字段提供的值。解析器使用字段参数来确定如何填充该字段的资料。
在 $ 符号表示变量在 GraphQL 中。 $ 符号后面的名称是我们变量的名称，我们可以在整个查询中使用它。冒号后面的变量类型必须与我们将用于它的参数的类型匹配。

接下来

我们听到你的声音，你已经准备好享受一些音乐了！我们将在下一课中添加播放列表的曲目。

上一步

下一步

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

本课程目前处于

测试版

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

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