在C#后端项目中引入GraphQL能力，HotChocolate是目前最成熟的方案之一。它支持代码优先与SDL优先两种模式，其中代码优先允许直接用C#类描述数据结构，由框架自动生成对应的GraphQL Schema。这种方式减少了重复定义，也方便利用C#的静态类型检查。
一、项目准备与基础服务配置
首先通过NuGet安装核心包。对于ASP.NET Core应用，通常需要HotChocolate.AspNetCore以及内存数据源相关的包。安装完成后，在Program.cs中注册GraphQL服务并映射端点。
下面的代码展示了最小化的配置过程。其中AddQueryType用于注册根查询类型，MapGraphQL则把默认的/graphql路径暴露为HTTP与WebSocket入口。这种配置方式对熟悉ASP.NET Core中间件的开发者十分直观。
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddGraphQLServer()
.AddQueryType<Query>();
var app = builder.Build();
app.MapGraphQL();
app.Run();
public class Query
{
public string Hello() => "World";
}
上述代码中，Query类里的公共方法Hello会被HotChocolate识别为一个GraphQL字段，返回字符串类型。启动应用后，访问/graphql即可在自带Playground中执行{ hello }查询。这种零配置映射降低了入门门槛，但也要求开发者理解方法签名与GraphQL类型的对应关系。
二、使用代码优先方式构建对象类型
实际业务中往往需要返回复杂结构。我们可以定义实体类，并在Query中返回该实体的集合。HotChocolate会自动将属性映射为GraphQL对象的字段，支持嵌套与列表。
以下示例定义了一个Book类以及对应的查询。通过构造函数注入内存数据，模拟从数据库读取。注意属性使用普通的C#类型，框架会推导出String、Int等GraphQL标量。
public class Book
{
public int Id { get; set; }
public string Title { get; set; }
public string Author { get; set; }
}
public class Query
{
private static readonly List<Book> _books = new()
{
new Book { Id = 1, Title = "C#进阶", Author = "张三" },
new Book { Id = 2, Title = "GraphQL实战", Author = "李四" }
};
public IQueryable<Book> GetBooks()
{
return _books.AsQueryable();
}
}
为了支持过滤与排序，需要额外调用AddFiltering与AddSorting扩展方法。这样GetBooks字段会自动接受where与order_by参数，无需手写解析逻辑。该特性基于IQueryable表达式树，能在接入EF Core时翻译为SQL，提升查询效率。
三、参数化查询与字段解析控制
除了返回集合，也可以编写带参数的字段方法。HotChocolate会把方法参数映射为GraphQL字段参数，并自动完成类型转换与必填校验。使用特性如[GraphQLNonNullType]可标记参数不可为空。
下面的代码演示根据Id获取单本书。若未找到则返回null，GraphQL客户端可据此处理异常状态。同时我们用[UseFiltering]特性显式启用过滤，方便统一行为。
using HotChocolate;
public class Query
{
private static readonly List<Book> _books = new()
{
new Book { Id = 1, Title = "C#进阶", Author = "张三" }
};
public Book GetBookById(int id)
{
return _books.FirstOrDefault(b => b.Id == id);
}
[UseFiltering]
public IQueryable<Book> GetBooks()
{
return _books.AsQueryable();
}
}
在注册时只需保持AddQueryType<Query>，框架会扫描方法上的特性并生成对应的Schema指令。相比纯手工编写SDL，这种方式的重构安全性更高：修改C#参数名后，Schema同步更新，不会出现两端不一致。
四、依赖注入与数据层集成
真实项目很少使用静态数据，而是通过仓储或服务访问数据库。HotChocolate原生支持构造函数注入，只要对应的服务已在DI容器注册，即可在Query类型中直接声明。
示例中我们抽象出IBookRepository，并在Program中注册为单例。Query类型通过构造参数接收实例，使数据访问与GraphQL逻辑解耦，便于单元测试。
public interface IBookRepository
{
IQueryable<Book> All();
}
public class BookRepository : IBookRepository
{
private readonly List<Book> _data = new()
{
new Book { Id = 1, Title = "C#进阶", Author = "张三" }
};
public IQueryable<Book> All() => _data.AsQueryable();
}
public class Query
{
private readonly IBookRepository _repo;
public Query(IBookRepository repo)
{
_repo = repo;
}
public IQueryable<Book> Books => _repo.All();
}
在Program.cs补充注册：builder.Services.AddSingleton<IBookRepository, BookRepository>(); 即可。这种结构让GraphQL层仅负责协议适配，业务逻辑下沉到仓储，符合分层架构原则。
五、查询示例与执行结果
完成上述步骤后，客户端可发送如下GraphQL查询，同时获取多本书并指定返回字段，减少过度获取。
query {
books {
id
title
author
}
bookById(id: 1) {
title
}
}
返回结果严格遵循请求的形状，未请求的字段不会序列化。这种特性使前端能精确控制载荷，降低带宽消耗。结合HotChocolate的自动持久化查询与缓存，可进一步提升高并发场景下的响应速度。
整体来看，用C#与HotChocolate构建GraphQL服务，核心在于将C#类型体系映射为Schema，并借助框架提供的过滤、排序与注入机制，把注意力集中在业务数据上，而非协议细节。
C#GraphQLHotChocolate修改时间：2026-08-01 11:24:28