欢迎光临
我的个人博客网站

ASP.NET Core 系列之 GraphQL – 完全教程(译)

ASP.NET Core 系列之 GraphQL - 完全教程(译)

原文地址:Getting Started with GraphQL in ASP.NET Core – Complete Guide

在这篇文章中,我们主要讨论一下 GraphQL 的趋势,这是一项由 Facebook 开发并进行开源的酷技术。我们将与 REST API 进行对比,并理解 GraphQL 的使用场景。同时,我们也将建立一个小的示例程序来演示如果将 GraphQL 集成到 ASP.NET Core 中,您可以在文章模块找到源代码。下面步入正题!

什么是 GraphQL?

GraphQL(或者叫图形化查询语言)是由 Facebook 发明和开源的 API 标准。它基本上是对 REST API 的一种替代。GraphQL 不像传统的 REST API,它将控制权交由给客户端,以便客户端应用/用户能够请求他自己想要的特定数据。简单来讲,它是一种可以取代 REST API 以构建高性能 API 的技术。话虽如此,但这并不意味着 REST API 将很快被取消。在大多数情况下, GraphQL 要优于 REST API。

GraphQL 是 API 的查询语言,它为 API 中的数据提供了定义(和 Swagger 类似,但可以做更多)。它本质上是一种技术,运行客户访问他们需要的数据,不会多,也不会少。这为客户端和开发人员提供了很大的权力和灵活性。

设计 GraphQL 背后的主要目标是使查询更智能。到目前为止,使用传统的 REST API 方法,我们可能经历了数据 过度提取(API返回 10 个字段,但我们只需要 2 个字段)或 抓取不足(API 仅返回 ID,但我们需要更多的相关数据,这迫使我们进行第二次 API 资源调用)。这意味着请求和响应始总是修改,并在应用程序的整个生命周期内保持固定,是这样的吗?GraphQL 使您的系统更智能,只提供所需的内容,从而减少到服务器的路由请求数量。

让我们说得更透彻一些。

以下是 REST API 的工作方式。

api/player/ – 从数据库中获取所有玩家
api/player/10 – 返回玩家 10 的所有详细信息。在恢复响应时,我们必须手动映射/分配所需的属性。服务器不会为您执行此工作。

几个例子,我们需要获取 id 为 10 的用户数据,只需要他的名字和年龄。

REST API 的请求和响应看起来是这样的:

请求:api/user/10
响应:

{     "userName" : "Mukesh",     "Name" : "Mukesh Murugan",     "Destination" :"Trivandrum",     "age" : 25,     "email" : "mukesh@codewithmukesh.com",     "something-else": "more data" } 

现在,我们得到该响应,接着必须要处理它,以筛选出当前所需字段的内容。这不是一项巨大的任务和资源浪费,但想象一下,将这个影响扩到到整个应用程序,如 Fackbook,这将产生昂贵的服务器开销。

让我们看一下 GraphQL 查询是什么样的。这是一个请求,客户可以问他到底需要什么。(我们将在文章的稍后介绍该如何查询和编写。这里只是一个例子。)

{     user(id: 10)    {         name,         age     } } 

并且,响应不多也不少

{    "data":    {        "user":        {            "name" : "Mukesh Murugan",            "age" : 25        }    } } 

这可能是我们从未考虑的地方。我们忙于使代码更智能,但从未真正想过 API 终结点的静态性。同样,这并不意味着您必须放弃 REST API 并转到 GraphQL,但 GraphQL 可以节省服务器资源/时间的消耗,如 Facebook 进行这样的扩展意义是巨大的。

您将需要了解 GraphQL 要解决的问题,以及它是如何与 REST API 进行比较,我们将在下一节中介绍这些问题。

GraphQL 解决的问题

我们从 GraphQL 如何出现开始讲起。我们将看到一个真实的场景。早在 2012 年左右, Facebook 发布了它自己的 Android / ios 应用程序。随着 Facebook 等面向客户服务的复杂性,人们很快注意到,这些应用消耗了太多的带宽、内存、RAM 使用量,并且时刻会进行十几次 API 调用。如果您在那个特定时间在 Facebook 工作, 您可能也会亲身经历过。这最终导致差评和 UX。

为什么它会进行多次 API 调用?这是显而易见的,对吧?例如,请考虑 Facebook 在移动设备上的新闻源。它有与您的个人资料相关的数据,来自您朋友的通知,来自你的朋友/页面/群的更新/帖子,以及大约一百万个😛其他内容,Facebook有一个API端点。现在,在加载新闻源时,将调用所有这些终结点,获取数据(包含大约 40-50% 未使用的字段),并在应用上显示。这产生了几个往返请求。一定会有更好的解决办法,对吧?

因此,GraphQL 引入了将所有这些百万个 API 终结点都凝结到单个终结点。现在,客户可以询问他/她/它到底想要什么,并得到所需的响应。

Facebook 关于其实施 GraphQL 的相关链接:https://developers.facebook.com/docs/graph-api

GraphQL VS REST API

GraphQL 和 REST API 之间有很多区别。让我们看看主要的区别:

  • 使用 GraphQL,您只需要使用一个终结点,而使用 REST API 的 API 终结点只有 100 个。GraphQL 技术的工作原理是很酷的。这使得企业级 API 中 GraphQL 性能比 REST API 好得多。此外,由于应用中只有一个终结点,因此在应用程序扩展时维护 GraphQL 会更加容易。
  • GraphQL 不需要 HTTP 来运行,而 REST API 需要 HTTP。
  • GraphQL 仅支持后发自外服务请求,与 REST 模式不同,后跟 RESTPI。
  • GraphQL 和 REST API 都有 JSON 响应。
  • GraphQL 允许客户端/使用者以所需的格式对数据进行塑型。它给客户端提供完全控制,以定义请求和响应。如您所了解,使用 REST API 时,响应和请求始终在代码中的服务器端定义。基本上,GraphQL 允许您在数据方面拥有您想要的。
  • 基于上一点,使用 GraphQL 基本上不会接收不会使用的数据。例如,假设您对 api/product/2 发出请求,并且响应具有产品实体的所有字段。在 10 个案例中的 9 种情况下,您不会使用产品的所有字段,对吗?现在使用 GraphQL,您可以选择设计请求,以便只收到请求的响应。这使得整个系统效率高,并大大减少了带宽消耗。
  • 有了所有这些令人敬畏的功能,你真的不必担心 API 版本控制。每个客户都保留自己的版本!使用 REST API 是会有相应限制。

在 ASP.NET Core 中使用 GraphQL

创建新的 ASP.NET Core WebAPI 解决方案。

ASP.NET Core 系列之 GraphQL - 完全教程(译)

对于本示例,我们将有一个简单的实体。创建一个新类并命名它为 Models/Customer。类似这样的定义:

public class Customer {     public int Id { get; set; }     public string FirstName { get; set; }     public string LastName { get; set; }     public string Contact { get; set; }     public string Email { get; set; }     public DateTime DateOfBirth { get; set; } } 

由于此示例更侧重于 ASP.NET Core 中 GraphQL 的实现,所以我将跳过使用 Entity Framework Core 连接到数据库并获取客户记录的步骤。请记住,我们不会在这里创建任何 API 控制器。我提前将一堆示例客户数据输入我的数据库以进行测试。

如果您是初次使用 Entity Framework Core,我强烈建议您阅读以下文章来掌握 EF Core Entity Framework Core in ASP.NET Core – Getting Started

安装依赖包

打开包管理器对应的控制台,安装如下依赖包

Install-Package GraphQL Install-Package GraphQL.Server.Transports.AspNetCore Install-Package GraphQL.Server.Ui.Playground Install-Package Newtonsoft.Json 

这里解释一下为什么需要安装上述包。

  • GraphQL:在 .NET 中启用 GraphQL 相关服务的核心包
  • GraphQL.Server.Transports.AspNetCore:GraphQL 的 HTTP 中间件
  • GraphQL.Server.Ui.Playground:现在我们需要一种 UI 来使用 GraphQL 并执行一些测试。这更像是 Swagger,您可以访问 API 的 POST 方法。相反, Rather Playground 也支持智能感知,智能建议和更多其它内容

我们将必须在 ASP.NET Core 的容器中配hi服务,但由于我们创建了需要用到的 GraphQL 类,所以这一步放到最后再操作。

GraphQL 的类型

GraphQL 不了解 Models/Entities 或任何 C# 的 POCO。相反,它需要类型。如前所述,我们已经在 “Models” 文件夹中有一个创建了客户定义的类。要从 GraphQL 终结点获取数据,我们必须使用 ObjectGraphType 来进行扩展,其中 T 是客户的类型。

让我们创建一个新类,并取名为 GraphQL/Types/CustomerGraphType.cs

class CustomerGraphType : ObjectGraphType<Customer> {     public CustomerGraphType()     {         Name = "Customer";         Field(x => x.Id, type: typeof(IdGraphType)).Description("Customer Id");         Field(x => x.FirstName).Description("Customer's First Name");         Field(x => x.LastName).Description("Customer's Last Name");         Field(x => x.Contact).Description("Customer's Contact");         Field(x => x.Email).Description("Customer's Email");     } } 

您可以看到,我们将类定义为客户对象图类型。在这里,我们将映射所有应该公开给客户端的字段。这也增加了一个很好的抽象层。API 的安全性。我们还可以向属性添加说明,以帮助客户端更好地了解 GraphQL。

接下来,我们需要定义受支持的查询。这些查询必不可少地返回客户列表或单个客户实体。

创建一个新类并取名为 GraphQL/Queries/CustomerQuery.cs

public class CustomerQuery : ObjectGraphType {     private readonly ApplicationDbContext _appContext;     public CustomerQuery(ApplicationDbContext appContext)     {         this._appContext = appContext;         Name = "Query";         Field<ListGraphType<CustomerGraphType>>("customers", "Returns a list of Customer", resolve: context => _appContext.Customers.ToList());         Field<CustomerGraphType>("customer", "Returns a Single Customer",             new QueryArguments(new QueryArgument<NonNullGraphType<IntGraphType>> { Name = "id", Description = "Customer Id" }),                 context => _appContext.Customers.Single(x => x.Id == context.Arguments["id"].GetPropertyValue<int>()));     } } 
  • Line #3 – 6 – 注入应用数据库上下文用于对象访问
  • Line #7 – 在这里,我们设置查询的名称属性

在上面的查询类中,我们基本上定义了两个查询。

  • Line #8 – 查询以返回所有客户作为列表。我们使用附加上下文的方式负责获取数据的 dbContext 变量。
  • Line #9 – 查询以基于 ID (int) 返回特定客户。

GraphQL Schema

由于我们已经定义了查询,因此在 GraphQL 实例 Schema 中包括此查询非常重要。GraphQL Schema 包含以下属性:

  • Query – 只能获取数据的查询类。
  • Mutations – 更改数据的方法(编辑/删除/添加)。
  • Subscriptions – 通知客户端更改。这更像是一个基于事件的订阅。

对于本示例,我们将只关注 Schema 的查询部分。让我们添加新类并将其命名 GraphQL/DemoSchema.cs

public class DemoSchema : Schema {     public DemoSchema(IDependencyResolver resolver) : base(resolver)     {         Query = resolver.Resolve<CustomerQuery>();     } } 

有了这个查询 Schema 的定义,,我们可以在 ASP.NET Core 的服务容器中注入我们的服务了。打开 Startup,cs 并添加以下内容到 ConfigureServices 方法中。

services.AddTransient<IDependencyResolver>(x =>new FuncDependencyResolver(x.GetRequiredService)); services.AddTransient<DemoSchema>(); services.AddGraphQL(o => o.ExposeExceptions = true)         .AddGraphTypes(ServiceLifetime.Transient); services.Configure<KestrelServerOptions>(options => options.AllowSynchronousIO = true); services.Configure<IISServerOptions>(options => options.AllowSynchronousIO = true); 

接下来,将以下内容添加到 “Configure” 方法。在这里,我们将注册我们的 Schema,并配置 GraphQLPlayground。在执行应用程序时,我们将了解更多关于 GraphQL Playground 的信息。

app.UseGraphQL<DemoSchema>(); app.UseGraphQLPlayground(options: new GraphQLPlaygroundOptions()); 

这就是我们需要在 ASP.NET Core 中做的事情,准备启动我们的应用程序,并导航至 localhost:5001/ui/playground

ASP.NET Core 系列之 GraphQL - 完全教程(译)

关于 GraphQL Playground

GraphQL Playground 更多地像是将你的 GraphQL API 进行可视化的界面。它提供各种强大的功能,如智能感知,智能推荐,实时错误语法通知,请求格式化等。

点击右侧的 “Schema” 的 Tab 标签页,还记得我们之前为 GraphQL 创建的一个 Schema 查询么?你可以在这找到相关定义。在查询 Tab 标签页,你可以找到受支持的方法,即 GetALLCustomerGetALLCustomer

这里面提到的 Customer 类型,看起来和 Swagger UI 非常相似。

ASP.NET Core 系列之 GraphQL - 完全教程(译)

接着看一下每个查询的定义和字段,点击 Docs 你可以看到每个查询的更多详细信息,比如取消名称,描述信息,类型。客户端可以使用这些文档作为了解 GraphQL 功能的参考文案。

ASP.NET Core 系列之 GraphQL - 完全教程(译)

测试 GraphQL

让我们开始测试我们创建的两个查询

获取所有 Customers

假设我们需要获得所有客户,但只有某些字段,如名字,姓氏,电子邮件。GraphQL 正是为了解决这个问题,记得吗?

你的查询请求类似这样的:

{   customers{     firstName,     lastName,     email   } } 

添加请求后,只需点击 Play 按钮即可。这将针对数据库执行您的请求。您可以看到返回的结果正是您想要的,😀您也可以通过向请求对象添加新字段来进行测试。

ASP.NET Core 系列之 GraphQL - 完全教程(译)

通过 ID 获取某个 Customer

接下来,让我们测试一下基于我们传递的 ID 作为参数来获取单一 Customer 对象。我们将 20 作为要传递的 ID 参数来进行请求

{   customer(id: 20) {     id,     firstName,     lastName,     email   } } 

ASP.NET Core 系列之 GraphQL - 完全教程(译)

很好!正如我们所期望的那样。这是一种相当酷的技术, 是吗?现在让我们把文章总结一下。我们将在另一篇文章讨论 GraphQL 在 ASP.NET Core 中的一些更多的先进概念。

相关链接

赞(0) 打赏
未经允许不得转载:张拓的天空 » ASP.NET Core 系列之 GraphQL – 完全教程(译)
分享到: 更多 (0)

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址

专业的IT技术经验分享 更专业 更方便

联系我们本站主机

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

微信扫一扫打赏