GraphQL Part I: hello, world.

GraphQL with ASP.NET Core (Part- I : Hello World)

厌倦了 REST? 让我们谈一下 GraphQL, GraphQL 提供声明式的方式从服务器获取数据。您可以从 GraphQL 的官方站点看到所有的优点。当前，在这个博客系列中，我将使用 ASP.NET Core 来展现如何集成 GraphQL ，将它实现为 API 的查询语言。

这意味着您只需要声明您所需要的属性，相对与 REST，对于特定的端点返回固定的数据集，然后您需要找到需要的属性。

对于 C# 来说，社区已经提供了一个开源的 graphql-dotnet，我们将使用它来完成项目。让我们开始吧。

首先从创建一个 ASP.NET Core 应用开始

dotnet new web

我们将会构建一个 GraphQL 的中间件（在下一篇文章），但是，第一步，让我们先从基础开始，假设您已经对 GraphQL 有了一点了解。所以，考虑一个简单的 Hello World 应用：我们将从服务器查询 hello 属性，然后服务器将返回 "world" 字符串，所以，这个 hello 属性一定是字符串类型。

在我们的空项目中，添加 GraphQL package for dotnet，然后，获取这个包。

dotnet add package GraphQL --version 2.0.0-alpha-912
dotnet restore

该系列的文章将会使用包的最新更新。如果我忘了更新文章，使得示例不能工作，请留言告诉我需要更新了。

让我们创建一个 query 并命名为 HelloWorldQuery。它是一个简单的类用于定义查询的字段。任何 query 类应该从 ObjectGraphType 派生出来。所以，HelloWorldQuery 类应该包含一个字符串的字段，如下所示：

using GraphQL.Types;
public class HelloWorldQuery : ObjectGraphType
{
    public HelloWorldQuery()
    {
        Field<StringGraphType>(
            name: "hello",
            resolve: context => "world"
        );
    }
}

字段定义在构造函数中

注意，我们使用泛型版本的 Field 并传递了一个 GraphQL 字符串类型（StringGraphType）来使得查询知道 hello 字段包含字符串类型的返回结果。

现在我们拥有了一个查询，然后我们需要为它构建一个 schema。

在 Startup.cs 文件的 Configure 方法中，删除现存的代码并粘贴如下代码。

var schema = new Schema { Query = new HelloWorldQuery() };

app.Run(async (context) =>
{
    var result = await new DocumentExecuter().ExecuteAsync(options =>
    {
        options.Schema = schema;
        options.Query = @"
            query {
                hello
            }
        ";
    }).ConfigureAwait(false);

    var json = new DocumentWriter(indent: true).Write(result)
    await context.Response.WriteAsync(json);
});

请注意，我们通过 HelloWorldQuery 对象的实例创建了一个新的 GraphQL schema。

DocumentExecuter 的 ExecuteAsync() 方法获取一个 ExecutionOptions 类型的 Action。这里初始化了 schema 并基于它执行提供的查询。

仔细查看赋予 Query (doc.Query) 的字符串。这里我们仅仅请求 hello 字段。您可以重写这个字符串为 {hello} ( 不需要 query 部分 )，它也同样工作。

最后，执行的结果被使用 DocumentWriter 类的 Write() 函数转换为 JSON。最终但不是最后我们将 JSON 输出到响应中。

现在，运行应用

dotnet run

您将会从浏览器获得以下输出。

您会发现它并不难。我们可以添加其他的字段，比如或 howdy ，然后让它返回字符串 universe。如下在 HelloWorldQuery 类中添加另外一个字段。

Field<StringGraphType>(
    name: "howdy",
    resolve: context => "universe"
);

现在，回到 Startup.cs，这次我们仅仅查询 howdy 在查询中 { howdy } 。您将收到如下的回应。

并且，您可以通过如下的 query 查询两个字段，如下所示：

{
    hello
    howdy
}

您将收到如下的响应：

所以，在这一步，您可以从声明的角度来查询您所感兴趣的部分。GraphQL 足够智能来理解您的需要并返回适当的响应。

我们仅仅草创了表面的东西。hello world 应用是有用的，因为在下一章，我们将开始构建中间件；我们不会有任何一行不理解的代码。

参考资料：

• C#: Why you should use ConfigureAwait(false) in your library code
• Getting Started with graphql-dotnet
• GraphQL Scaler Types