GraphQL 参数

10. GraphQL 参数

概述

继续我们的下一个功能！

在本课中，我们将

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

模型

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

Mockup of the playlist page

我们很有可能通过几种方式进入此页面：从精选播放列表页面点击特定播放列表，或者可能直接通过 URL 链接。

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

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

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

新的入口点

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

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

Query.cs

public Playlist? Playlist()
{


}

这可能会让您稍微困惑，因为有一个名为与对象类型相同的解析器函数，所以我们可以做的是将此解析器重命名为 GetPlaylist。在幕后，Hot Chocolate 将删除 Get 前缀并将其映射到与如果我们将其命名为 Playlist 相同的 GraphQL 字段。

Query.cs

public Playlist? GetPlaylist()

注意： Hot Chocolate 将对以结尾的函数执行相同的操作 Async。

作为函数中的参数，我们将定义一个 id，类型为 string，并添加 [ID] 属性以表示这应该在 GraphQL 中为 ID 类型。

请注意，id 参数可以命名为任何名称，例如 playlistId！我们建议与您的团队协作以决定命名约定。使用 id 作为 GraphQL 参数名称为常用约定。

Query.cs

public Playlist? GetPlaylist([ID] string id)

我们还将在此解析器中包含 SpotifyService。

Query.cs

public Playlist? GetPlaylist([ID] string id, SpotifyService spotifyService) {

我们需要从 spotifyService 中调用的数据源方法是 GetPlaylistAsync，它将 id 作为参数。我们将结果保存在名为 response 的变量中。

Query.cs

var response = spotifyService.GetPlaylistAsync(id);

这里的模式将与 FeaturedPlaylists 的解析器非常相似。我们将使函数 async，等待响应并返回 Task<T> 类型。

Query.cs

public async Task<Playlist?> GetPlaylist([ID] string id, SpotifyService spotifyService)
{
    var response = await spotifyService.GetPlaylistAsync(id);
}

此解析器需要返回 Playlist 类型，但 response 目前为 SpotifyWeb.Playlist 类型。

跳到 Playlist.cs 文件中，让我们在 Playlist 类中添加一个新的、附加的构造函数。我们将传入一个 SpotifyWeb.Playlist 对象并使用其属性初始化我们自己的 Playlist 的属性。

Playlist.cs

public Playlist(SpotifyWeb.Playlist obj)
{
    Id = obj.Id;
    Name = obj.Name;
    Description = obj.Description;
}

(我们将在下一课中处理播放列表的曲目！)

回到解析器中，让我们通过使用 response 创建 Playlist 对象，然后返回结果来完成此熟悉的模式。

Query.cs

var playlist = new Playlist(response);
return playlist;

不要忘记 GetPlaylist 的描述解析器！

Query.cs

[GraphQLDescription("Retrieves a specific playlist.")]

using SpotifyWeb;

namespace Odyssey.MusicMatcher;

public class Query
{
    [GraphQLDescription(
        "Playlists hand-picked to be featured to all users."
    )]
    public async Task<List<Playlist>> FeaturedPlaylists(SpotifyService spotifyService)
    {
        var response = await spotifyService.GetFeaturedPlaylistsAsync();
        return response.Playlists.Items.Select(item => new Playlist(item)).ToList();
    }

    [GraphQLDescription("Retrieves a specific playlist.")]
    public async Task<Playlist?> GetPlaylist([ID] string id, SpotifyService spotifyService)
    {
        var response = await spotifyService.GetPlaylistAsync(id);
        var playlist = new Playlist(response);
        return playlist;
    }
}

using SpotifyWeb;

namespace Odyssey.MusicMatcher;

[GraphQLDescription("A curated collection of tracks designed for a specific activity or mood.")]
public class Playlist
{
    [GraphQLDescription("The ID for the playlist.")]
    [ID]
    public string Id { get; }

    [GraphQLDescription("The name of the playlist.")]
    public string Name { get; set; }

    [GraphQLDescription("Describes the playlist, what to expect and entices the user to listen.")]
    public string? Description { get; set; }

    public Playlist(string id, string name)
    {
        Id = id;
        Name = name;
    }

    public Playlist(PlaylistSimplified obj)
    {
        Id = obj.Id;
        Name = obj.Name;
        Description = obj.Description;
    }

    public Playlist(SpotifyWeb.Playlist obj)
    {
        Id = obj.Id;
        Name = obj.Name;
        Description = obj.Description;
    }
}

让我们保存更改并确保我们的服务器仍然在没有问题的情况下成功运行。

探索时间！

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

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

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

https://studio.apollographql.com/sandbox/explorer

GetPlaylist operation in Sandbox

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

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

变量

The $ symbol indicates a variable in GraphQL. The name after the $ symbol is the name of our variable, which we can use throughout the query. After the colon is the variable's type, which must match the type of the argument we'll use it for.

Variables are great—they let us pass argument values dynamically from the client-side so we don't have to hardcode values into our query. We'll use them every time we create a query with arguments.

In our case, we have a variable called playlistId that the Explorer set up for us down in the Variables section. Right now, it's set to null.

https://studio.apollographql.com/sandbox/explorer

GetPlaylist operation with null variable

If we try to run the query now, we'll still get a JSON object back, but this time with an errors key, instead of data:

Response

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

This lets us know that we can't leave the playlistId as null, because the schema specifically defines the id argument (where we're using the playlistId variable) as a non-nullable type!

Let's go ahead and update the null value to a playlist ID we know exists from the featuredPlaylists query.

变量

{
  "playlistId": "6Fl8d6KF0O4V5kFdbzalfW"
}

Lastly, we'll rename the operation to be a bit more descriptive — like GetPlaylistDetails.

GraphQL operation

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

Run the query to get the details of the Sweet Beats & Eats playlist!

https://studio.apollographql.com/sandbox/explorer

GetPlaylist operation with playlistId

Practice

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

指定解析器的返回值类型。确定架构中的入口点。过滤和转换特定字段的数据。定义解析器的数据源。

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

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

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

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

Key takeaways

Arguments are values provided for a particular field in a GraphQL query. Resolvers use field arguments to determine how to populate data for that field.
The $ symbol indicates a variable in GraphQL. The name after the $ symbol is the name of our variable, which we can use throughout the query. After the colon is the variable's type, which must match the type of the argument we'll use it for.

Up next

我们明白你的意思，你已经准备好开始享受音乐了！在下一课中，我们将添加播放列表的曲目。

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

本课程目前处于

测试版

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

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