开源地址

Github：https://github.com/ChilliCream/graphql-platform (opens new window)

GraphQL 是一种查询语言和运行时环境，可用于构建 API。它由 Facebook 开发，并已在许多大型应用程序中得到广泛应用。而 .NET 中的 GraphQL-Platform 提供了一个完整的、开放的和可扩展的解决方案，使开发人员可以轻松地使用 GraphQL API。

在本篇文章中，我们将介绍如何在 .NET 中使用 GraphQL-Platform 构建和部署 API，并提供一些详细的使用示例。

安装和配置 GraphQL-Platform

首先，我们需要安装 GraphQL-Platform 的 NuGet 包。我们可以使用 Visual Studio 中的 NuGet 包管理器或在控制台中使用以下命令：

Install-Package GraphQL-Platform

接下来，我们需要在我们的应用程序中配置 GraphQL-Platform。在 Startup.cs 文件中，我们需要添加以下代码：

public void ConfigureServices(IServiceCollection services)
{
    services.AddGraphQL()
        .AddSystemTextJson()
        .AddGraphTypes(typeof(Startup));
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseGraphQL()
       .UsePlayground();
}

这段代码将启用 GraphQL-Platform，并配置系统文本 JSON 作为默认序列化程序。它还将自动扫描应用程序程序集，找到我们定义的所有 GraphQL 类型，并将它们添加到 GraphQL 架构中。

最后，我们需要使用 UsePlayground() 方法来启用 GraphQL Playground。这是一个用于测试和调试 GraphQL API 的交互式 IDE。我们可以在浏览器中打开以下 URL 来启动 Playground：

http://localhost:5000/graphql

创建 GraphQL 查询

现在，我们已经完成了 GraphQL-Platform 的安装和配置，我们可以开始定义我们的 GraphQL 查询。让我们创建一个简单的查询来获取所有用户：

public class Query
{
    [GraphQLName("users")]
    [GraphQLDescription("Get all users.")]
    public IEnumerable<User> GetUsers()
    {
        // TODO: Implement logic to get all users.
    }
}

在上面的代码中，我们定义了一个名为 users 的查询，它返回一个 IEnumerable<User> 类型。我们还为查询添加了一个 GraphQLName 属性，以便在 GraphQL Playground 中显示一个更友好的名称。

接下来，我们需要定义 User 类型：

public class User
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

现在我们已经定义了我们的查询和类型，我们可以重新启动应用程序，并在 Playground 中测试查询。我们可以使用以下查询来获取所有用户：

query {
  users {
    id
    firstName
    lastName
  }
}

添加查询参数

GraphQL-Platform 允许我们向查询添加参数，以便过滤、排序和分页结果。让我们向我们的 GetUsers() 方法添加一个名为 search 的参数来过滤结果：

public class Query
{
    [GraphQLName("users")]
    [GraphQLDescription("Get all users.")]
    public IEnumerable<User> GetUsers(string search)
    {
    // TODO: Implement logic to get users based on search criteria.
    }
}

现在，我们可以重新启动应用程序，并在 Playground 中测试带有搜索参数的查询：

query {
  users(search: "John") {
    id
    firstName
    lastName
  }
}

添加 GraphQL 基因库

现在我们已经了解了如何创建和测试 GraphQL 查询，让我们介绍一下 GraphQL 基因库。GraphQL 基因库是一组 .NET 类型，它们提供了一种将现有数据模型转换为 GraphQL 查询的简单方法。GraphQL 基因库还提供了一个可扩展的框架，使开发人员可以轻松地添加自定义逻辑和验证规则。

让我们通过添加 GraphQL 基因库来改进我们的示例。我们将使用 Entity Framework Core（EF Core）作为数据访问层，并使用 GraphQL 基因库自动生成我们的查询。首先，我们需要安装以下 NuGet 包：

Install-Package GraphQL-Genius -Version 3.0.0-preview6
Install-Package GraphQL-Genius.EntityFrameworkCore -Version 3.0.0-preview6

接下来，我们需要定义我们的数据模型和 DbContext：

public class User
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

public class UserDbContext : DbContext
{
    public UserDbContext(DbContextOptions<UserDbContext> options)
        : base(options)
    {
    }

    public DbSet<User> Users { get; set; }
}

现在我们已经定义了我们的数据模型和 DbContext，我们可以使用以下代码自动生成我们的查询：

public class Query : EfObjectGraphType<UserDbContext>
{
    public Query(UserDbContext db) : base(db)
    {
        Field<ListGraphType<UserGraphType>>(
            "users",
            resolve: context => db.Users.ToListAsync());
    }
}

在上面的代码中，我们使用 EfObjectGraphType<TContext> 类型作为查询基类，其中 TContext 是我们的 DbContext 类型。然后，我们使用 Field() 方法添加一个名为 users 的字段，并使用 EF Core 异步查询返回所有用户。

现在我们已经定义了我们的查询，我们可以重新启动应用程序，并在 Playground 中测试我们的查询：

query {
  users {
    id
    firstName
    lastName
  }
}

添加 GraphQL 突变

到目前为止，我们已经学习了如何创建 GraphQL 查询。现在，让我们学习如何创建 GraphQL 突变。突变允许我们修改数据并在同一请求中返回结果。

让我们创建一个简单的突变来创建新用户。首先，我们需要定义一个输入类型：

public class UserInput
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

然后，我们可以使用以下代码定义我们的突变：

public class Mutation
{
    public Mutation(UserDbContext db)
    {
        FieldAsync<UserGraphType>(
            "createUser",
            arguments: new QueryArguments(
                new QueryArgument<NonNullGraphType<UserInputGraphType>> { Name = "user" }
                ),
            resolve: async context =>
            {
                var user = context.GetArgument<User>("user");
                db.Users.Add(user);
                await db.SaveChangesAsync();
                return user;
            });
    }
}

在上面的代码中，我们使用 FieldAsync() 方法添加一个名为 createUser 的突变。我们还定义了一个名为 user 的输入参数，并将其包装在 NonNullGraphType 中，以确保它不为空。然后，我们在突变的解析函数中获取 user 参数，并将其添加到数据库中。最后，我们返回新用户。

现在我们已经定义了我们的突变，我们可以重新启动应用程序，并在 Playground 中测试我们的突变：

mutation {
  createUser(user: { firstName: "John", lastName: "Doe" }) {
    id
    firstName
    lastName
  }
}

结论

在本文中，我们介绍了如何在 .NET 中使用 GraphQL-Platform 构建和部署 API。我们学习了如何创建 GraphQL 查询和突变，并介绍了如何使用 GraphQL 基因库自动生成查询。

GraphQL-Platform 提供了一个完整的、开放的和可扩展的解决方案，使开发人员可以轻松地使用 GraphQL API。如果您正在寻找一种快速、安全和可扩展的方法来构建 API，那么 GraphQL-Platform 是一个不错的选择。