GraphQL 服务端开发

// 一次查询拿到订单、下单用户与商品名，服务端只查必要字段
// query {
//   order(id: 42) {
//     id
//     total
//     customer { name }
//     items { product { name } quantity }
//   }
// }

// 用 C# 类型定义 Object Type，字段与领域模型对齐
public sealed class OrderType : ObjectType<Order>
{
    protected override void Configure(IObjectTypeDescriptor<Order> descriptor)
    {
        descriptor.Field(o => o.Id).Type<NonNullType<IdType>>();
        descriptor.Field(o => o.Total).Type<NonNullType<DecimalType>>();
        descriptor.Field(o => o.Status).Type<NonNullType<EnumType<OrderStatus>>>();

        // 计算字段：不落在数据库列上，由 Resolver 按需计算
        descriptor.Field("itemCount")
            .Type<NonNullType<IntType>>()
            .Resolve(ctx => ctx.Parent<Order>().Items.Count);

        // 明确标记弃用，客户端工具会给出提示
        descriptor.Field(o => o.LegacyCode)
            .Deprecated("改用 id 字段");
    }
}

// 分页：用 Relay 风格的 Connection，把游标分页约定固化进 Schema
public sealed class Query
{
    [UsePaging(MaxPageSize = 100, DefaultPageSize = 20)]
    [UseProjection]
    [UseFiltering]
    [UseSorting]
    public IQueryable<Order> GetOrders([Service] AppDbContext db) => db.Orders;
}

// 显式 Resolver：参数绑定清晰，便于加缓存与日志
public sealed class OrderResolvers
{
    public Task<Customer?> GetCustomerAsync(
        [Parent] Order order,
        [Service] ICustomerService customers,
        CancellationToken ct)
        => customers.FindAsync(order.CustomerId, ct);

    public async Task<IReadOnlyList<OrderEvent>> GetTimelineAsync(
        [Parent] Order order,
        [Service] IOrderEventStore events,
        [Service] IMemoryCache cache,
        CancellationToken ct)
    {
        var key = $"order:{order.Id}:timeline";
        return await cache.GetOrCreateAsync(key, async entry =>
        {
            entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromSeconds(30);
            return await events.ListAsync(order.Id, ct);
        })!;
    }
}

// 注册：把 Query 与 Resolver 都挂上，并开启全局能力
builder.Services
    .AddGraphQLServer()
    .AddQueryType<Query>()
    .AddType<OrderType>()
    .AddTypeExtension<OrderResolvers>()
    .AddFiltering()
    .AddSorting()
    .AddProjections()
    .AddInMemorySubscriptions()
    .ModifyRequestOptions(o => o.IncludeExceptionDetails = builder.Environment.IsDevelopment());

// 批量数据加载器：一次查询取回全部客户
public sealed class CustomerBatchDataLoader(
    IDbContextFactory<AppDbContext> factory,
    IBatchScheduler scheduler) : BatchDataLoader<int, Customer>(scheduler)
{
    protected override async Task<IReadOnlyDictionary<int, Customer>> LoadBatchAsync(
        IReadOnlyList<int> keys, CancellationToken ct)
    {
        await using var db = await factory.CreateDbContextAsync(ct);
        return await db.Customers
            .Where(c => keys.Contains(c.Id))
            .ToDictionaryAsync(c => c.Id, ct);
    }
}

// Resolver 改用 DataLoader，签名从「单个 ID」变成「一批 ID」
public sealed class OrderResolvers
{
    public Task<Customer?> GetCustomerAsync(
        [Parent] Order order,
        CustomerBatchDataLoader loader,
        CancellationToken ct)
        => loader.LoadAsync(order.CustomerId, ct);   // 自动合并同轮次的请求
}

// 分组加载器：当批量查询的 key 不是主键，而是外键时使用
public sealed class ItemsByOrderIdDataLoader(
    IDbContextFactory<AppDbContext> factory,
    IBatchScheduler scheduler)
    : GroupedDataLoader<int, OrderItem>(scheduler)
{
    protected override async Task<ILookup<int, OrderItem>> LoadGroupedBatchAsync(
        IReadOnlyList<int> keys, CancellationToken ct)
    {
        await using var db = await factory.CreateDbContextAsync(ct);
        var items = await db.OrderItems.Where(i => keys.Contains(i.OrderId)).ToListAsync(ct);
        return items.ToLookup(i => i.OrderId);
    }
}

// 订阅类型：返回异步流，事件到达即推送
public sealed class Subscription
{
    [Subscribe]
    [Topic($"{{{nameof(orderId)}}}")]
    public OrderStatusChanged OnOrderStatusChanged(
        int orderId,
        [EventMessage] OrderStatusChanged message) => message;
}

// Mutation 中发布事件，主题按订单 ID 区分
public sealed class Mutation
{
    public async Task<Order> UpdateStatusAsync(
        int id,
        OrderStatus status,
        [Service] IOrderService orders,
        [Service] ITopicEventSender sender,
        CancellationToken ct)
    {
        var order = await orders.UpdateStatusAsync(id, status, ct);
        await sender.SendAsync($"onOrderStatusChanged:{id}",
            new OrderStatusChanged(id, status), ct);
        return order;
    }
}

// 生产环境用 Redis 做事件总线，让多实例部署也能正确推送
builder.Services
    .AddGraphQLServer()
    .AddSubscriptionType<Subscription>()
    .AddRedisSubscriptions(_ => ConnectionMultiplexer.Connect("redis:6379"));

// 客户端订阅示例：
// subscription {
//   onOrderStatusChanged(orderId: 42) { orderId status }
// }

// 防护配置：深度限制 + 复杂度分析 + 生产关闭内省
builder.Services
    .AddGraphQLServer()
    .AddQueryType<Query>()
    .ModifyRequestOptions(o => o.ExecutionTimeout = TimeSpan.FromSeconds(10))
    .AddMaxExecutionDepthRule(maxAllowedDepth: 12)
    .AddCostAnalyzer(options => options.DefaultCost = 1)   // 字段级成本
    .DisableIntrospection(!builder.Environment.IsDevelopment())
    .AddPagingArguments();

// 字段级成本：列表字段按分页上限计费，防止一次拉取百万行
public sealed class OrderType : ObjectType<Order>
{
    protected override void Configure(IObjectTypeDescriptor<Order> descriptor)
    {
        descriptor.Field(o => o.Items)
            .Cost(10)                  // 列表字段成本更高
            .UsePaging(MaxPageSize = 50);
    }
}

// 字段级遥测：记录每个字段的调用次数与调用方
public sealed class FieldUsageDiagnosticListener : IDiagnosticEventListener
{
    private readonly Meter _meter = new("graphql.usage");

    public override void ExecuteOperation(IRequestContext context)
    {
        // 从 context.Operation 遍历 SelectionSet，上报字段路径
        foreach (var path in context.Operation.GetFieldPaths())
        {
            _meter.CreateCounter<long>("graphql.field.calls")
                  .Add(1, new KeyValuePair<string, object?>("field", path));
        }
    }
}

# 部署侧：单一端点 + 持久化查询白名单，兼顾缓存与安全
apiVersion: apps/v1
kind: Deployment
metadata:
  name: graphql-gateway
spec:
  template:
    spec:
      containers:
        - name: api
          image: contoso/graphql:1.4.0
          env:
            - name: GraphQL__PersistedQueriesOnly
              value: "true"
            - name: GraphQL__MaxDepth
              value: "12"