使用C#的GraphQL API：实践逐步教程

引言：为什么GraphQL和C#是理想组合

现代Web开发需要灵活且高效的API。尽管REST API广受欢迎，但它常常面临过度获取（获取多余数据）和获取不足（需要多次请求才能获取完整信息）的问题。GraphQL解决了这些问题，允许客户端在一次请求中只获取所需的数据。

在本教程中，我们将使用Hot Chocolate库（.NET中最流行的GraphQL实现）创建一个完整的GraphQL API。您将学习如何配置服务器、定义模式、实现查询（queries）、变更（mutations）和订阅（subscriptions）。所有代码示例都是实用的，可直接使用。

本教程适合：希望掌握GraphQL的.NET开发者，以及正在寻找REST替代方案的人。具备C#和ASP.NET Core的基础知识会有所帮助，但并非必需。

1. 项目设置与安装Hot Chocolate

创建ASP.NET Core项目

首先创建一个新项目。打开终端或命令行并执行：

dotnet new web -n GraphQLDemo\ncd GraphQLDemo

现在安装Hot Chocolate包：

dotnet add package HotChocolate.AspNetCore\ndotnet add package HotChocolate.AspNetCore.Playground

HotChocolate.AspNetCore包添加了处理GraphQL请求的中间件，而HotChocolate.AspNetCore.Playground提供了内置的IDE（GraphQL Playground）用于测试。

配置Startup

编辑Program.cs文件（对于.NET 5及以下版本，编辑Startup.cs）。添加基本配置：

var builder = WebApplication.CreateBuilder(args);\n\n// 添加GraphQL服务\nbuilder.Services\n    .AddGraphQLServer()\n    .AddQueryType<Query>()\n    .AddMutationType<Mutation>(); // 稍后添加\n\nvar app = builder.Build();\n\n// 添加中间件\napp.UseRouting();\napp.MapGraphQL(); // 端点 /graphql\napp.MapGraphQLPlayground(); // Playground可通过 /playground 访问\n\napp.Run();

注意：Query和Mutation是我们稍后将创建的类。目前只保留Query。

2. 创建数据模型和第一个查询（Query）

Book模型

创建一个简单的图书模型。添加文件Models/Book.cs：

namespace GraphQLDemo.Models;\n\npublic class Book\n{\n    public int Id { get; set; }\n    public string Title { get; set; } = string.Empty;\n    public string Author { get; set; } = string.Empty;\n    public int Year { get; set; }\n    public decimal Price { get; set; }\n}

Query类

现在创建包含数据获取方法的Query类。添加文件GraphQL/Query.cs：

using GraphQLDemo.Models;\n\nnamespace GraphQLDemo.GraphQL;\n\npublic class Query\n{\n    // 临时数据存储（实际项目中应为数据库）\n    private static readonly List<Book> Books = new()\n    {\n        new Book { Id = 1, Title = "战争与和平", Author = "列夫·托尔斯泰", Year = 1869, Price = 29.99m },\n        new Book { Id = 2, Title = "罪与罚", Author = "费奥多尔·陀思妥耶夫斯基", Year = 1866, Price = 24.99m },\n        new Book { Id = 3, Title = "大师与玛格丽特", Author = "米哈伊尔·布尔加科夫", Year = 1967, Price = 19.99m }\n    };\n\n    // 查询：获取所有图书\n    public IQueryable<Book> GetBooks() => Books.AsQueryable();\n\n    // 查询：根据ID获取图书\n    public Book? GetBookById(int id) => Books.FirstOrDefault(b => b.Id == id);\n}

返回数据的方法称为解析器。Hot Chocolate会自动