跳至主要內容

GraphQL（HotChocolate）

SunnyFan大约 11 分钟约 3262 字

GraphQL（HotChocolate）

简介

GraphQL 是一种 API 查询语言和运行时，允许客户端按需指定需要的数据字段，避免过度获取（Over-fetching）和不足获取（Under-fetching）问题。HotChocolate 是 .NET 生态中最成熟、功能最丰富的 GraphQL 框架，支持从 C# 类型自动推断 Schema、DataLoader 批量加载、WebSocket Subscription 实时订阅、权限控制和查询复杂度分析。深入理解 GraphQL 的 Schema 设计、Resolver 模式、N+1 问题解决方案和性能优化策略，有助于在需要灵活数据查询和多端复用 API 的场景中做出正确的技术选型。

特点

GraphQL 基础

核心概念

GraphQL 三种操作类型：

1. Query — 读取数据（类比 GET）
   query {
     user(id: 1) {
       name
       email
       orders {
         id
         total
       }
     }
   }

2. Mutation — 修改数据（类比 POST/PUT/DELETE）
   mutation {
     createUser(input: { name: "张三", email: "zhangsan@example.com" }) {
       id
       name
     }
   }

3. Subscription — 实时订阅（类比 WebSocket）
   subscription {
     onOrderCreated {
       id
       total
       customer {
         name
       }
     }
   }

Schema 结构：
  type Query { ... }      — 定义所有查询入口
  type Mutation { ... }   — 定义所有变更入口
  type Subscription { ... } — 定义所有订阅入口
  type User { ... }       — 定义用户类型
  type Order { ... }      — 定义订单类型

核心优势：
  - 客户端按需获取字段（避免过度获取）
  - 单次请求获取关联数据（避免多次请求）
  - 类型系统保证数据一致性
  - 内省查询自动生成文档

基础 Query 与 Mutation

实体与数据服务

// 实体定义
public class User
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public string Email { get; set; } = "";
    public DateTime CreatedAt { get; set; }
    public List<Order> Orders { get; set; } = new();
}

public class Order
{
    public int Id { get; set; }
    public decimal Total { get; set; }
    public int UserId { get; set; }
    public OrderStatus Status { get; set; }
    public DateTime CreatedAt { get; set; }
    public List<OrderItem> Items { get; set; } = new();
}

public class OrderItem
{
    public int Id { get; set; }
    public string ProductName { get; set; } = "";
    public int Quantity { get; set; }
    public decimal UnitPrice { get; set; }
}

public enum OrderStatus { Pending, Processing, Shipped, Delivered, Cancelled }

// 数据服务接口
public interface IUserService
{
    Task<User?> GetByIdAsync(int id);
    Task<List<User>> GetAllAsync(int? skip = null, int? take = null);
    Task<User> CreateAsync(string name, string email);
}

public interface IOrderService
{
    Task<List<Order>> GetByUserIdAsync(int userId);
    Task<Order> CreateAsync(int userId, List<OrderItem> items);
}

Query 类型

public class Query
{
    // 简单查询
    public async Task<User?> GetUser(int id, [Service] IUserService userService)
    {
        return await userService.GetByIdAsync(id);
    }

    // 带分页的查询
    [UsePaging(MaxPageSize = 50, DefaultPageSize = 20)]
    [UseProjection]
    [UseFiltering]
    [UseSorting]
    public async Task<IQueryable<User>> GetUsers([Service] AppDbContext db)
    {
        return db.Users;
    }

    // 搜索查询
    public async Task<List<User>> SearchUsers(
        string? name,
        string? email,
        [Service] IUserService userService)
    {
        var users = await userService.GetAllAsync();
        if (!string.IsNullOrEmpty(name))
            users = users.Where(u => u.Name.Contains(name, StringComparison.OrdinalIgnoreCase)).ToList();
        if (!string.IsNullOrEmpty(email))
            users = users.Where(u => u.Email.Contains(email, StringComparison.OrdinalIgnoreCase)).ToList();
        return users;
    }
}

Mutation 类型

public record CreateUserInput(string Name, string Email);
public record CreateOrderInput(int UserId, List<CreateOrderItemInput> Items);
public record CreateOrderItemInput(string ProductName, int Quantity, decimal UnitPrice);

public class Mutation
{
    // 创建用户
    public async Task<User> CreateUser(
        CreateUserInput input,
        [Service] IUserService userService)
    {
        return await userService.CreateAsync(input.Name, input.Email);
    }

    // 创建订单
    public async Task<Order> CreateOrder(
        CreateOrderInput input,
        [Service] IOrderService orderService)
    {
        var items = input.Items.Select(i => new OrderItem
        {
            ProductName = i.ProductName,
            Quantity = i.Quantity,
            UnitPrice = i.UnitPrice
        }).ToList();

        return await orderService.CreateAsync(input.UserId, items);
    }

    // 更新订单状态
    public async Task<Order> UpdateOrderStatus(
        int orderId,
        OrderStatus status,
        [Service] IOrderService orderService)
    {
        // 实现更新逻辑...
        return new Order { Id = orderId, Status = status };
    }
}

注册与配置

// NuGet: HotChocolate.AspNetCore

var builder = WebApplication.CreateBuilder(args);

// 注册 GraphQL 服务
builder.Services.AddGraphQLServer()
    .AddQueryType<Query>()
    .AddMutationType<Mutation>()
    .AddSubscriptionType<Subscription>()
    .AddType<OrderStatusType>() // 自定义枚举类型
    .AddAuthorization()          // 启用授权
    .AddErrorFilter<GraphQLErrorFilter>(); // 自定义错误过滤器

var app = builder.Build();

// 映射 GraphQL 端点
app.MapGraphQL();       // POST /graphql
app.MapGraphQLTool();   // GET /graphql/tool (Banana Cake Pop IDE)

app.Run();

DataLoader 解决 N+1 问题

N+1 问题说明

N+1 问题示例：

查询：
  query {
    orders {
      id
      user { name }   ← 每个订单都要查询一次用户表
    }
  }

没有 DataLoader：
  SELECT * FROM Orders          → 1 次查询
  SELECT * FROM Users WHERE Id = 1  → 1 次查询
  SELECT * FROM Users WHERE Id = 2  → 1 次查询
  SELECT * FROM Users WHERE Id = 3  → 1 次查询
  ...
  共 1 + N 次查询！

使用 DataLoader：
  SELECT * FROM Orders                    → 1 次查询
  SELECT * FROM Users WHERE Id IN (1,2,3) → 1 次查询（批量）
  共 2 次查询！

DataLoader 实现

// 用户 DataLoader — 批量加载用户
public class UserDataLoader : BatchDataLoader<int, User>
{
    private readonly IUserRepository _userRepository;

    public UserDataLoader(IUserRepository repository, IBatchScheduler scheduler)
        : base(scheduler)
    {
        _userRepository = repository;
    }

    protected override async Task<IReadOnlyDictionary<int, User>> LoadBatchAsync(
        IReadOnlyList<int> keys,
        CancellationToken cancellationToken)
    {
        // 一次查询获取所有用户
        var users = await _userRepository.GetUsersByIdsAsync(keys, cancellationToken);

        // 返回 Dictionary（键是用户 ID，值是用户对象）
        return users.ToDictionary(u => u.Id);
    }
}

// 在 Order 的 Resolver 中使用 DataLoader
[ExtendObjectType(typeof(Order))]
public class OrderResolvers
{
    // 使用 DataLoader 加载关联的用户
    public async Task<User> GetUserAsync(
        [Parent] Order order,
        [DataLoader] UserDataLoader userLoader,
        CancellationToken cancellationToken)
    {
        return (await userLoader.LoadAsync(order.UserId, cancellationToken))!;
    }
}

// 注册 DataLoader
builder.Services.AddGraphQLServer()
    .AddQueryType<Query>()
    .AddDataLoader<UserDataLoader>();

// DataLoader 的工作原理：
// 1. 同一个请求中的多次 LoadAsync 会被合并
// 2. 等待当前执行帧结束后，一次性批量加载
// 3. 结果自动分发到各个调用点

自定义 DataLoader

// 订单商品 DataLoader
public class OrderItemsDataLoader : BatchDataLoader<int, List<OrderItem>>
{
    private readonly IOrderRepository _orderRepository;

    public OrderItemsDataLoader(IOrderRepository repository, IBatchScheduler scheduler)
        : base(scheduler)
    {
        _orderRepository = repository;
    }

    protected override async Task<IReadOnlyDictionary<int, List<OrderItem>>> LoadBatchAsync(
        IReadOnlyList<int> keys,
        CancellationToken cancellationToken)
    {
        // 按 OrderId 分组查询
        var allItems = await _orderRepository.GetItemsByOrderIdsAsync(keys, cancellationToken);

        var result = allItems
            .GroupBy(item => item.OrderId)
            .ToDictionary(g => g.Key, g => g.ToList());

        // 确保所有 key 都有值（没有订单项的订单返回空列表）
        foreach (var key in keys)
        {
            if (!result.ContainsKey(key))
                result[key] = new List<OrderItem>();
        }

        return result;
    }
}

// 使用分组 DataLoader
[ExtendObjectType(typeof(Order))]
public class OrderItemResolvers
{
    public async Task<List<OrderItem>> GetItemsAsync(
        [Parent] Order order,
        [DataLoader] OrderItemsDataLoader itemLoader,
        CancellationToken cancellationToken)
    {
        return await itemLoader.LoadAsync(order.Id, cancellationToken);
    }
}

Subscription 实时订阅

订阅实现

// NuGet: HotChocolate.Subscriptions.InMemory
// NuGet: HotChocolate.Subscriptions.Redis（生产环境推荐）

public class Subscription
{
    // 订阅订单创建事件
    [Subscribe]
    [Topic("OrderCreated")]
    public Order OnOrderCreated([EventMessage] Order order) => order;

    // 订阅订单状态变更
    [Subscribe]
    [Topic("OrderStatusChanged")]
    public OrderStatusChangedEvent OnOrderStatusChanged(
        [EventMessage] OrderStatusChangedEvent evt) => evt;
}

public record OrderStatusChangedEvent(int OrderId, OrderStatus OldStatus, OrderStatus NewStatus, DateTime ChangedAt);

// 在 Mutation 中发布事件
public class Mutation
{
    public async Task<Order> CreateOrder(
        CreateOrderInput input,
        [Service] ITopicEventSender sender,
        [Service] IOrderService orderService)
    {
        var order = await orderService.CreateAsync(input.UserId, input.Items);

        // 发布事件到订阅者
        await sender.SendAsync("OrderCreated", order);

        return order;
    }

    public async Task<Order> UpdateOrderStatus(
        int orderId,
        OrderStatus newStatus,
        [Service] ITopicEventSender sender,
        [Service] IOrderService orderService)
    {
        var oldStatus = OrderStatus.Pending; // 从数据库获取旧状态
        var order = await orderService.UpdateStatusAsync(orderId, newStatus);

        await sender.SendAsync("OrderStatusChanged",
            new OrderStatusChangedEvent(orderId, oldStatus, newStatus, DateTime.UtcNow));

        return order;
    }
}

// 注册 Subscription
builder.Services.AddGraphQLServer()
    .AddQueryType<Query>()
    .AddMutationType<Mutation>()
    .AddSubscriptionType<Subscription>()
    .AddInMemorySubscriptions(); // 开发环境用内存

// 生产环境使用 Redis：
// builder.Services.AddRedisSubscription("__myApp_subscriptions__");

客户端订阅

// WebSocket 订阅
const ws = new WebSocket('ws://localhost:5000/graphql');

ws.onopen = () => {
    ws.send(JSON.stringify({
        id: '1',
        type: 'subscription_start',
        payload: {
            query: `
                subscription {
                    onOrderCreated {
                        id
                        total
                        status
                        createdAt
                        user { name email }
                    }
                }
            `
        }
    });
};

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'subscription_data') {
        console.log('新订单:', data.payload.data.onOrderCreated);
    }
};

权限与验证

授权指令

// 注册授权服务
builder.Services.AddAuthorization();
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options => { /* JWT 配置 */ });

// GraphQL 授权配置
builder.Services.AddGraphQLServer()
    .AddAuthorization()
    .AddQueryType<Query>()
    .AddMutationType<Mutation>();

// 在 Resolver 上使用授权
public class Query
{
    [Authorize] // 需要登录
    public async Task<User> GetCurrentUser([Service] IUserService userService, ClaimsPrincipal user)
    {
        var userId = user.FindFirst("sub")?.Value;
        return await userService.GetByIdAsync(int.Parse(userId!));
    }

    [Authorize(Roles = "Admin")] // 需要管理员角色
    public async Task<List<User>> GetAllUsers([Service] IUserService userService)
    {
        return await userService.GetAllAsync();
    }

    [Authorize(Policy = "CanManageOrders")] // 自定义策略
    public async Task<Order> UpdateOrderStatus(...)
    {
        // ...
    }
}

// 在类型级别授权
[Authorize]
public class AdminQuery
{
    public async Task<List<User>> GetUsers() => /* ... */;
}

// 字段级别授权
public class User
{
    [Authorize(Roles = "Admin")]
    public string Email { get; set; } = ""; // 只有管理员能查看邮箱
}

自定义错误过滤器

public class GraphQLErrorFilter : IErrorFilter
{
    public IError OnError(IError error)
    {
        // 不暴露内部错误详情给客户端
        if (error.Exception is not null)
        {
            return error
                .WithMessage("服务器内部错误")
                .RemoveException()
                .RemoveLocations()
                .SetCode("INTERNAL_ERROR");
        }

        // 验证错误保持原始信息
        if (error.Code == "VALIDATION_ERROR")
        {
            return error.WithMessage(error.Message);
        }

        return error;
    }
}

// 注册
builder.Services.AddGraphQLServer()
    .AddErrorFilter<GraphQLErrorFilter>();

查询复杂度分析

防止深度嵌套查询

// GraphQL 允许客户端自由组合查询，可能导致性能问题
// 例如：查询 1000 个用户，每个用户 100 个订单，每个订单 50 个商品
// 可能导致 O(1000 * 100 * 50) = 5,000,000 次解析

// 配置查询复杂度限制
builder.Services.AddGraphQLServer()
    .AddQueryType<Query>()
    .AddMutationType<Mutation>()
    .SetValidationOptions(options =>
    {
        // 查询深度限制（默认无限制）
        options.MaxExecutionDepth = 5;

        // 复杂度分析
        options.CostAnalyzer = new CostAnalyzer(options)
        {
            // 默认每个字段成本为 1
            DefaultCost = 1,
            // 列表类型的乘数
            DefaultListMultiplier = 10,
            // 最大查询成本
            MaxCost = 500
        };
    });

// 自定义字段成本
public class Query
{
    [Cost(1)] // 简单字段成本为 1
    public async Task<User?> GetUser(int id) => /* ... */;

    [Cost(10)] // 列表查询成本为 10
    public async Task<List<User>> GetUsers() => /* ... */;
}

性能优化

缓存策略

// HotChocolate 支持响应缓存
builder.Services.AddGraphQLServer()
    .AddQueryType<Query>()
    .AddCachingRequestExecutorInterceptor(); // 启用查询缓存

// 在 Resolver 上使用缓存
public class Query
{
    [UseCache("userById", 120)] // 缓存 120 秒
    public async Task<User?> GetUser(int id, [Service] IUserService userService)
    {
        return await userService.GetByIdAsync(id);
    }

    // 使用全局缓存控制
    [CacheControl(maxAge: 300)]
    public async Task<List<Product>> GetProducts() => /* ... */;
}

// 查询计划缓存（相同查询结构复用编译后的执行计划）
builder.Services.AddGraphQLServer()
    .AddQueryType<Query>()
    .ModifyRequestOptions(options =>
    {
        options.IncludeExecutionPlan = true; // 开发环境
        options.ExecutionTimeout = TimeSpan.FromSeconds(30);
    });

优点

缺点

总结

HotChocolate 自动从 C# 类型推断 GraphQL Schema，支持 AddQueryType、AddMutationType、AddSubscriptionType 注册三种操作类型。Query 读取数据，Mutation 写入数据并可通过 ITopicEventSender 发布事件，Subscription 通过 WebSocket 实时订阅。DataLoader（BatchDataLoader<TKey, TValue>）批量加载关联数据，彻底解决 N+1 查询问题。权限通过 [Authorize] 特性控制，支持角色和策略。查询复杂度分析（CostAnalyzer）防止恶意深层嵌套查询。建议在需要灵活查询、多端复用 API（Web + Mobile + Desktop）的场景使用 GraphQL，纯 CRUD 场景 REST 更简单直接。

关键知识点

  • 先分清这个主题位于请求链路、后台任务链路还是基础设施链路。
  • 服务端主题通常不只关心功能正确，还关心稳定性、性能和可观测性。
  • 任何框架能力都要结合配置、生命周期、异常传播和外部依赖一起看。
  • 框架能力的真正重点是它在请求链路中的位置和对上下游的影响。

项目落地视角

  • 画清请求进入、业务执行、外部调用、日志记录和错误返回的完整路径。
  • 为关键链路补齐超时、重试、熔断、追踪和结构化日志。
  • 把配置与敏感信息分离，并明确不同环境的差异来源。
  • 画清执行顺序、入参来源、失败返回和日志记录点。

常见误区

  • 只会堆中间件或组件，不知道它们在链路中的执行顺序。
  • 忽略生命周期和线程池、连接池等运行时资源约束。
  • 没有监控和测试就对性能或可靠性下结论。
  • 知道 API 名称，却不知道它应该放在请求链路的哪个位置。

进阶路线

  • 继续向运行时行为、可观测性、发布治理和微服务协同深入。
  • 把主题和数据库、缓存、消息队列、认证授权联动起来理解。
  • 沉淀团队级模板，包括统一异常处理、配置约定和基础设施封装。
  • 继续补齐协议选型、网关治理、端点可观测性和契约演进策略。

适用场景

  • 当你准备把《GraphQL（HotChocolate）》真正落到项目里时，最适合先在一个独立模块或最小样例里验证关键路径。
  • 适合 API 服务、后台任务、实时通信、认证授权和微服务协作场景。
  • 当需求开始涉及稳定性、性能、可观测性和发布流程时，这类主题会成为基础设施能力。

落地建议

  • 先定义请求链路与失败路径，再决定中间件、过滤器、服务边界和依赖方式。
  • 为关键链路补日志、指标、追踪、超时与重试策略。
  • 环境配置与敏感信息分离，避免把生产参数写死在代码或镜像里。

排错清单

  • 先确认问题发生在路由、模型绑定、中间件、业务层还是基础设施层。
  • 检查 DI 生命周期、配置来源、序列化规则和认证上下文。
  • 查看线程池、连接池、缓存命中率和外部依赖超时。

复盘问题

  • 如果把《GraphQL（HotChocolate）》放进你的当前项目，最先要验证的输入、输出和失败路径分别是什么？
  • 《GraphQL（HotChocolate）》最容易在什么规模、什么边界条件下暴露问题？你会用什么指标或日志去确认？
  • 相比默认实现或替代方案，采用《GraphQL（HotChocolate）》最大的收益和代价分别是什么？

延伸阅读

Copyright © 2026 SunnyFan