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