第 7 章 高级主题
7.4 HATEOAS
全称 Hypermedia AS The Engine Of Application State，即超媒体作为应用程序状态引擎。它作为 REST 统一界面约束中的一个子约束，是 REST 架构中最重要、最复杂，也是构建成熟 REST 服务的核心
Richardson 成熟度模型是根据 REST 约束对 API 成熟度进行衡量的一种方法，该成熟模型使用3个因素来决定服务的成熟度，即 URI、HTTP 方法和 HATEOAS。一个 API 应用程序越多地采用这些特性，就越成熟。根据上述3个因素，RESTful API 应用的成熟度分为3级：
- 第 1 级：资源
- 第 2 级：HTTP 动词
- 第 3 级：超文本驱动，即 HATEOAS
HATEOAS 使 API 在其响应消息中不仅提供资源，还提供 URL。这些 URL 能够告诉客户端如何使用 API，它们由服务器根据应用程序当前的状态动态生成，而客户端在得到响应后，通过这些 URL 就能够知道服务器提供哪些操作，并使用这些链接与服务器进行交互
7.5 GraphQL
全称 Graph Query Language，作为查询语言，最主要的特点是能够根据客户端准确地获得它所需要的数据
作为 API 查询语言，GraphQL 提供了一种以声明的方式从服务器上获取数据的方法
{
authors{
name,
email
}
}
执行后的结果如下：
{
"data":{
"authors":{
"name":"Author 1",
"email":"author1@xxx.com"
},
...
}
}
尽管 GraphQL 能够与 REST 实现同样的目的，但它们各自的实现方式以及特点有较大的差异，主要体现在：
- （1）端点：对 REST 而言，每一个 URL 相当于一个资源，而 GraphQL 通过一个端点可以返回用户所需要的任何数据
- （2）请求方式：REST 充分使用 HTTP 动词来访问不同的端点，而 GraphQL 所有请求都是向服务器相同端点发送类似 JSON 格式的信息
- （3）资源表现形式：REST 得到的资源是事先定义好的固定的数据结构，而 GraphQL 能够根据客户端的请求灵活地返回所需要的形式
- （4）版本：GraphQL 是在客户端来定义资源的表现形式，因此服务端数据结构变化不影响客户端的使用，即使服务器发生更改，也是向后兼容
GraphQL 仅使用一个端点即可执行并响应所有 Graph 查询请求，因此它完全可以与 Library.API 项目中现有的 REST 端点共存，弥补 RESTful API 的不足
添加nuget
Install-Package GraphQL
GraphQL 中有一个非常重要的概念--Schema，它定义了 GraphQL 服务提供什么样的数据结构，执行查询时，必须指定一个 Schema
添加两个类 AuthorType 和 BookType
namespace Library.API.GraphQLSchema
{
public class AuthorType : ObjectGraphType<Author>
{
public AuthorType(IRepositoryWrapper repositoryWrapper)
{
Field(x => x.Id, type: typeof(IdGraphType));
Field(x => x.Name);
Field(x => x.BirthData);
Field(x => x.BirthPlace);
Field(x => x.Email);
Field<ListGraphType<BookType>>("books", resolve: context => repositoryWrapper.Book.GetBooksAsync(context.Source.Id).Result);
}
}
}
namespace Library.API.GraphQLSchema
{
public class BookType : ObjectGraphType<Book>
{
public BookType()
{
Field(x => x.Id, type: typeof(IdGraphType));
Field(x => x.Title);
Field(x => x.Description);
Field(x => x.Pages);
}
}
}
接下来创建查询类 LibraryQuery
namespace Library.API.GraphQLSchema
{
public class LibraryQuery : ObjectGraphType
{
public LibraryQuery(IRepositoryWrapper repositoryWrapper)
{
// 返回所有作者的信息
Field<ListGraphType<AuthorType>>("authors",
resolve: context => repositoryWrapper.Author.GetAllAsync().Result);
// 返回指定作者信息
Field<AuthorType>("author", arguments: new QueryArguments(new QueryArgument<IdGraphType>()
{
Name = "id"
}),
resolve: context =>
{
Guid id = Guid.Empty;
if (context.Arguments.ContainsKey("id"))
{
id = new Guid(context.Arguments["id"].ToString() ?? string.Empty);
}
return repositoryWrapper.Author.GetByIdAsync(id).Result;
});
}
}
}
接下来创建 Schema
namespace Library.API.GraphQLSchema
{
public class LibrarySchema : Schema
{
public LibrarySchema(LibraryQuery query, IDependencyResolver denDependencyResolver)
{
Query = query;
DependencyResolver = denDependencyResolver;
}
}
}
当 GraphQL 类型、查询以及 Schema 都创建完成后，应将它们添加到依赖注入容器中
添加一个扩展方法，并在扩展方法中添加所有类型
namespace Library.API.Extentions
{
public static class GraphQLExtensions
{
public static void AddGraphQLSchemaAndTypes(this IServiceCollection services)
{
services.AddSingleton<AuthorType>();
services.AddSingleton<BookType>();
services.AddSingleton<LibraryQuery>();
services.AddSingleton<ISchema, LibrarySchema>();
// 用于执行 Graph 查询
services.AddSingleton<IDocumentExecuter, DocumentExecuter>();
// 用于获取指定的依赖
services.AddSingleton<IDependencyResolver>(provider =>
new FuncDependencyResolver(provider.GetRequiredService));
}
}
}
为了方便解析客户端请求中的 GraphQL 查询内容，添加一个类
namespace Library.API.GraphQLSchema
{
public class GraphQLRequest
{
/// <summary>
/// 用于接收客户端请求正文中的 Graph 查询
/// </summary>
public string Query { get; set; }
}
}
接下来，在项目中添加一个控制器
namespace Library.API.Controllers
{
[Route("graphql")]
[ApiController]
public class GraphQLController : ControllerBase
{
public IDocumentExecuter DocumentExecuter { get; set; }
public ISchema LibrarySchema { get; set; }
public GraphQLController(ISchema librarySchema, IDocumentExecuter documentExecuter)
{
LibrarySchema = librarySchema;
DocumentExecuter = documentExecuter;
}
[HttpPost]
public async Task<IActionResult> Post([FromBody] GraphQLRequest query)
{
var result = await DocumentExecuter.ExecuteAsync(options =>
{
options.Schema = LibrarySchema;
options.Query = query.Query;
});
if (result.Errors?.Count > 0)
{
return BadRequest(result);
}
return Ok(result);
}
}
}
运行程序，以 POST 方式请求 URL：http://localhost:5001/graphql
请求内容如下：
{
"query":
"query{
authors{
id,
name,
birthPlace,
birthDate,
books{
title,
pages
}
}
}"
}
可以得到与请求的内容完全一致的请求结果，表明客户端可以根据需要在请求的查询中定义所需要的信息，通过一次查询，即可返回所有需要的数据
在 LibraryQuery 类中还添加了对指定 author 的查询，可以通过以下请求内容查询
{
"query":
"query{
authors(id:"86072f62-5ec8-4266-9356-752a8496d56a"){
id,
name,
birthPlace,
birthDate,
books{
title,
pages
}
}
}"
}
本作品采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议进行许可。
欢迎转载、使用、重新发布，但务必保留文章署名 郑子铭 （包含链接： http://www.cnblogs.com/MingsonZheng/ ），不得用于商业目的，基于本文修改后的作品务必以相同的许可发布。
如有任何疑问，请与我联系 (MingsonZheng@outlook.com) 。