.NET Core开发日志——GraphQL

GraphQL是什么

GraphQL既是一种用于API的查询语言也是一种通过使用对应数据的类型系统，执行数据查询的服务端运行时。GraphQL没有局限于任何数据库或存储引擎，而是通过既有代码及数据获得支持。

Schema

GraphQL的Schema是GraphQL服务端实现的核心部分。它负责描述能够被客户端程序使用的功能。而在Schema中，类型系统又是其基石。包含了创建类型之间的联系，定义数据获取操作(查询)及数据处理操作(增删改)，以及自我描述等特性。

程序语言支持

GraphQL服务端类库已经被多种程序语言支持。

• C# / .NET
• Clojure
• Elixir
• Erlang
• Go
• Groovy
• Java
• JavaScript
• PHP
• Python
• Scala
• Ruby

Package

要想在.NET Core中使用GraphQL，执行以下命令添加所需类库包。

dotnet add package GraphQL

ASP.NET Core

在ASP.NET中使用GraphQL有两种方式。

其一，是在传统的Controller里调用GraphQL的方法：

[Route("api/[controller]")]
[ApiController]
public class GraphQLController : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> Post([FromBody]GraphQLQuery query)
    {
        var schema = Schema.For(@"
            type Query {
                user: Person
            }
            type Person {
                id: String
                name: String
            }
        ");

        var root = new { User = new { Id = "1", Name = "Ken" } };

        var result = await new DocumentExecuter().ExecuteAsync(_ =>
        {
            _.Schema = schema;
            _.Query = query.Query;
            _.Root = root;
        }).ConfigureAwait(false);

        return Ok(result);
    }
}

public class GraphQLQuery
{
    public string OperationName { get; set; }
    public string NamedQuery { get; set; }
    public string Query { get; set; }
    public Inputs Variables { get; set; }
}

运行程序后，可用Postman作为客户端测试，并在请求内容中输入以下数据：

{
    "query": "query { user { id name }}"
}

可得结果：

{
    "data": {
        "user": {
            "id": "1",
            "name": "Ken"
        }
    }
}

其二是通过Middleware的方式。

首先追加类库包GraphQL.Server.Transports.AspNetCore。

接着定义Schema类与ObjectGraphType(假设尚未创建)：

public class Person
{
    public string Id { get; set; }
    public string Name { get; set; }
}
public class PersonType: ObjectGraphType<Person>
{
    public PersonType()
    {
        Field(x => x.Id);
        Field(x => x.Name);
    }
}

public class UserQuery : ObjectGraphType
{
    public UserQuery()
    {
        Field<PersonType>(name: "user", resolve: ctx=> new Person {  Id = "1", Name = "Ken" });
    }
}

public class UserSchema: Schema
{
    public UserSchema()
    {
        Query = new UserQuery();
    }
}

然后在Startup文件里，添加GraphQL相关内容。

public void ConfigureServices(IServiceCollection services)
{
    services.AddScoped<UserSchema>();
    services.AddGraphQL(_ =>
    {
        _.EnableMetrics = true;
        _.ExposeExceptions = true;
    });
}

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseGraphQL<UserSchema>("/graphql");
}

运行后，客户端调用方法与第一种方式相同。

除了使用Postman作为客户端调用GraphQL之外，还可以尝试GraphQLPlayground获得更便捷的体验。

安装相关类库包：dotnet add package GraphQL.Server.Ui.Playground

在Configure方法里增加一行代码。

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseGraphQL<UserSchema>("/graphql");
    app.UseGraphQLPlayground(new GraphQLPlaygroundOptions());
}

然后运行程序，访问http://url地址/ui/playground，即可直接在网页中调用GraphQL。