GraphQL в C# (.NET): Полное руководство по библиотеке GraphQL.NET

GraphQL библиотека для C# (.NET): GraphQL.NET

GraphQL — это современный язык запросов для API, который предоставляет клиентам возможность запрашивать только необходимые данные, снижая избыточность и ускоряя работу приложений. Для платформы .NET существует мощная библиотека GraphQL.NET, которая позволяет разработчикам на C# создавать серверные части, полностью совместимые со спецификацией GraphQL. В этой статье мы подробно разберём её возможности, преимущества и приведём практические примеры.

Что такое GraphQL.NET?

GraphQL.NET — это open-source библиотека для C# (.NET), реализующая спецификацию GraphQL. Она предоставляет инструменты для определения схем (типов, запросов, мутаций и подписок), обработки входящих запросов, валидации и выполнения логики. Библиотека активно поддерживается сообществом и используется в production-средах.

Ключевые особенности:

• Гибкое определение схемы — типы, интерфейсы, union-типы и перечисления.
• Поддержка запросов (Query), мутаций (Mutation) и подписок (Subscription).
• Интеграция с DI-контейнерами (например, Microsoft.Extensions.DependencyInjection).
• Валидация и парсинг запросов на стороне сервера.
• Поддержка DataLoader для оптимизации N+1 запросов.
• Инструменты для тестирования и отладки.

Установка и подключение

Установка осуществляется через NuGet Package Manager. Выполните команду:

dotnet add package GraphQL
dotnet add package GraphQL.SystemTextJson

Для ASP.NET Core также понадобится пакет для middleware:

dotnet add package GraphQL.Server.Transports.AspNetCore

Создание простого GraphQL API

1. Определение типов данных

Сначала создадим модель данных и соответствующий GraphQL-тип:

public class Book
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Author { get; set; }
}

public class BookType : ObjectType<Book>
{
    protected override void Configure(IObjectTypeDescriptor<Book> descriptor)
    {
        descriptor.Field(b => b.Id).Type<NonNullType<IntType>>();
        descriptor.Field(b => b.Title).Type<NonNullType<StringType>>();
        descriptor.Field(b => b.Author).Type<StringType>();
    }
}

2. Определение запросов (Query)

Теперь создадим класс Query, который будет обрабатывать запросы:

public class Query
{
    private readonly List<Book> _books = new()
    {
        new Book { Id = 1, Title = "1984", Author = "George Orwell" },
        new Book { Id = 2, Title = "Brave New World", Author = "Aldous Huxley" }
    };

    public Book GetBook(int id)
    {
        return _books.FirstOrDefault(b => b.Id == id);
    }

    public List<Book> GetBooks()
    {
        return _books;
    }
}

Затем регистрируем этот класс в схеме:

public class BookSchema : Schema
{
    public BookSchema(IServiceProvider provider) : base(provider)
    {
        Query = provider.GetRequiredService<Query>();
    }
}

3. Настройка в Startup.cs

Добавляем сервисы и middleware в ASP.NET Core:

public void ConfigureServices(IServiceCollection services)
{
    services.AddGraphQL(builder => builder
        .AddSchema<BookSchema>()
        .AddSystemTextJson());
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseGraphQL<BookSchema>();
    app.UseGraphQLPlayground(); // Для тестирования
}

Мутации (Mutation) для изменения данных

Добавим возможность добавлять книги через мутации:

public class Mutation
{
    private readonly List<Book> _books = new();

    public Book AddBook(string title, string author)
    {
        var book = new Book { Id = _books.Count + 1, Title = title, Author = author };
        _books.Add(book);
        return book;
    }
}

Не забудьте зарегистрировать Mutation в схеме:

public class BookSchema : Schema
{
    public BookSchema(IServiceProvider provider) : base(provider)
    {
        Query = provider.GetRequiredService<Query>();
        Mutation = provider.GetRequiredService<Mutation>();
    }
}

Теперь клиент может отправлять запросы вида:

mutation {
  addBook(title: "Fahrenheit 451", author: "Ray Bradbury") {
    id
    title
    author
  }
}

Подписки (Subscriptions) — реальное время

Для работы с подписками используется Web