GraphQL订阅是GraphQL规范中用于实现服务端向客户端主动推送数据的功能，和查询、变更并列为核心操作类型。在C#项目中，我们可以借助HotChocolate这个主流的GraphQL库快速实现订阅能力，完成实时消息、数据变更通知等场景的开发。HotChocolate内置了订阅相关的底层支持，不需要开发者手动处理WebSocket连接等复杂逻辑，大幅降低了实现成本。
环境准备与依赖安装
首先我们需要创建一个ASP.NET Core Web API项目，然后通过NuGet安装HotChocolate相关的核心包，确保版本兼容性。需要安装的包包括HotChocolate.AspNetCore、HotChocolate.Subscriptions以及HotChocolate.Data，后者用于后续可能的数据查询集成。
安装完成后，我们需要在Program.cs中配置HotChocolate的服务，开启订阅功能。具体配置代码如下：
var builder = WebApplication.CreateBuilder(args);
// 添加HotChocolate GraphQL服务，开启订阅功能
builder.Services
.AddGraphQLServer()
.AddSubscriptionType<MessageSubscription>() // 注册订阅类型
.AddInMemorySubscriptions(); // 使用内存订阅存储，生产环境可替换为Redis等分布式存储
var app = builder.Build();
app.MapGraphQL(); // 映射GraphQL端点
app.Run();
定义订阅相关类型
消息模型定义
我们先定义一个简单的消息模型，作为订阅推送的载体，包含消息ID、内容和发送时间三个属性。
public class Message
{
public int Id { get; set; }
public string Content { get; set; }
public DateTime SendTime { get; set; }
}
订阅类型定义
订阅类型需要继承SubscriptionType，在类型中定义具体的订阅字段，每个订阅字段对应一个可监听的事件流。
using HotChocolate.Subscriptions;
public class MessageSubscription : SubscriptionType
{
// 定义名为onMessageAdded的订阅字段，返回Message类型
public ISourceStream<Message> OnMessageAdded(
[Service] ITopicEventReceiver receiver)
{
// 监听名为message_added的主题
return receiver.Subscribe<Message>("message_added");
}
}
变更类型定义（用于触发订阅）
订阅需要由服务端事件触发，我们可以定义一个变更类型，当客户端调用添加消息的变更时，触发订阅事件。
using HotChocolate.Subscriptions;
public class MessageMutation : MutationType
{
// 定义添加消息的变更
public async Task<Message> AddMessage(
string content,
[Service] ITopicEventSender sender)
{
var message = new Message
{
Id = new Random().Next(1, 1000),
Content = content,
SendTime = DateTime.Now
};
// 向message_added主题发送消息，触发所有订阅该主题的客户端接收数据
await sender.SendAsync("message_added", message);
return message;
}
}
定义完变更类型后，需要在Program.cs的服务配置中注册该类型：
builder.Services
.AddGraphQLServer()
.AddSubscriptionType<MessageSubscription>()
.AddMutationType<MessageMutation>() // 注册变更类型
.AddInMemorySubscriptions();
客户端订阅测试
我们可以使用Altair GraphQL Client这类工具测试订阅功能，首先建立WebSocket连接到GraphQL端点，默认端点是/graphql。然后发送订阅请求：
subscription {
onMessageAdded {
id
content
sendTime
}
}
接着在另一个请求中调用添加消息的变更：
mutation {
addMessage(content: "测试订阅消息") {
id
content
sendTime
}
}
此时订阅端会立即收到新添加的消息数据，说明订阅功能已经正常工作。
生产环境优化建议
- 内存订阅存储仅适合单实例部署场景，多实例部署时需要替换为Redis等分布式订阅存储，HotChocolate提供了对应的Redis订阅扩展包。
- 可以为订阅添加过滤参数，让客户端只订阅符合特定条件的事件，减少不必要的数据推送。
- 建议对订阅连接做鉴权处理，避免未授权的客户端订阅敏感数据，可以在GraphQL中间件中添加认证逻辑。
注意：如果项目中同时使用了其他WebSocket中间件，需要注意端口和路径的冲突，HotChocolate的订阅默认复用GraphQL端点的WebSocket连接，不需要额外配置单独的端口。
C#GraphQL订阅HotChocolate实时通信修改时间：2026-06-11 12:57:29