plan-forge graphql.instructions.md

.NET GraphQL Patterns (Hot Chocolate)

Schema Design (Code-First)

Modular Root Types with ExtendObjectType

// ✅ Separate domains into their own query files
[ExtendObjectType(typeof(Query))]
public class ProducerQueries
{
    [Authorize]
    public async Task<Producer?> GetProducerByIdAsync(
        Guid id,
        [Service] IProducerRepository repository,
        CancellationToken ct)
    {
        return await repository.GetByIdAsync(id, ct);
    }

    [UsePaging(IncludeTotalCount = true)]
    [UseFiltering]
    [UseSorting]
    public IQueryable<Producer> GetProducers([Service] IProducerRepository repository)
        => repository.GetQueryable();
}

// ❌ NEVER: One massive Query class with all resolvers

Registration

builder.Services
    .AddGraphQLServer()
    .AddQueryType<Query>()
        .AddTypeExtension<ProducerQueries>()
        .AddTypeExtension<UserQueries>()
    .AddMutationType<Mutation>()
        .AddTypeExtension<ProducerMutations>()
    .AddSubscriptionType<Subscription>()
    .AddAuthorization()
    .AddFiltering()
    .AddSorting()
    .AddProjections()
    .AddInMemorySubscriptions()
    .AddMaxExecutionDepthRule(10)
    .AddQueryCostOptions(o => { o.MaxFieldCost = 10; o.MaxTypeCost = 1000; });

DataLoaders (N+1 Prevention)

// ✅ Batch load — single query for all requested IDs
public class ProducerByIdDataLoader : BatchDataLoader<Guid, Producer>
{
    private readonly IProducerRepository _repository;

    public ProducerByIdDataLoader(
        IProducerRepository repository,
        IBatchScheduler batchScheduler,
        DataLoaderOptions? options = null)
        : base(batchScheduler, options)
    {
        _repository = repository;
    }

    protected override async Task<IReadOnlyDictionary<Guid, Producer>> LoadBatchAsync(
        IReadOnlyList<Guid> keys,
        CancellationToken ct)
    {
        // ✅ Single batch query — WHERE id = ANY(@Ids)
        var producers = await _repository.GetByIdsAsync(keys, ct);
        return producers.ToDictionary(p => p.Id);
    }
}

// ✅ Usage in resolver
public async Task<Producer?> GetProducerAsync(
    [Parent] Order order,
    ProducerByIdDataLoader loader,
    CancellationToken ct)
{
    return await loader.LoadAsync(order.ProducerId, ct);
}