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

GraphQL библиотека C# (.NET) — GraphQL.NET

GraphQL — это язык запросов для API, который позволяет клиентам запрашивать только те данные, которые им действительно нужны. В экосистеме .NET одной из самых популярных реализаций является библиотека GraphQL.NET (также известная как graphql-dotnet). Она предоставляет мощные инструменты для создания гибких, типизированных и эффективных API на платформе C# (.NET).

В этой статье мы подробно рассмотрим, как использовать GraphQL.NET, разберём ключевые концепции и приведём практические примеры кода.

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

GraphQL.NET — это библиотека с открытым исходным кодом, которая реализует спецификацию GraphQL для платформы .NET. Она поддерживает как .NET Core, так и .NET Framework. Основные возможности:

• Создание строго типизированных схем на C#.
• Поддержка запросов (Query), мутаций (Mutation) и подписок (Subscription).
• Встроенная валидация и выполнение запросов.
• Интеграция с популярными веб-фреймворками (ASP.NET Core, Nancy и другие).
• Поддержка подписок через WebSockets (SignalR).

Установка и настройка

Для начала работы установите пакет через NuGet:

dotnet add package GraphQL
dotnet add package GraphQL.SystemTextJson  // для JSON сериализации

Если вы используете ASP.NET Core, дополнительно установите:

dotnet add package GraphQL.Server.Transports.AspNetCore
dotnet add package GraphQL.Server.Ui.Playground  // встроенный UI для тестирования

Создание первой схемы

GraphQL строится вокруг схемы, которая определяет типы данных и доступные операции. Рассмотрим простой пример — API для получения информации о книгах.

Шаг 1. Определите модель данных:

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

Шаг 2. Создайте GraphQL типы:

public class BookType : ObjectGraphType<Book>
{
    public BookType()
    {
        Field(x => x.Id).Description("Идентификатор книги");
        Field(x => x.Title).Description("Название книги");
        Field(x => x.Author).Description("Автор");
        Field(x => x.Pages).Description("Количество страниц");
    }
}

Шаг 3. Определите корневой запрос (Query):

public class BookQuery : ObjectGraphType
{
    public BookQuery(IDataStore dataStore)
    {
        Field<BookType>("book")
            .Arguments(new QueryArguments(new QueryArgument<StringGraphType> { Name = "id" }))
            .Resolve(context => dataStore.GetBookById(context.GetArgument<string>("id")));

        Field<ListGraphType<BookType>>("books")
            .Resolve(context => dataStore.GetAllBooks());
    }
}

Шаг 4. Соберите схему:

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

Интеграция с ASP.NET Core

Зарегистрируйте сервисы в Program.cs (или Startup.cs):

builder.Services.AddGraphQL(b => b
    .AddSystemTextJson()
    .AddSchema<BookSchema>()
    .AddGraphTypes(typeof(BookType).Assembly));

builder.Services.AddScoped<IDataStore, InMemoryDataStore>();

Добавьте middleware:

app.UseGraphQL<BookSchema>();  // эндпоинт по умолчанию /graphql
app.UseGraphQLPlayground();    // UI для тестирования (опционально)

Выполнение запроса

Теперь вы можете отправлять GraphQL запросы. Например, получить все книги:

{
  books {
    id
    title
    author
  }
}

Или получить конкретную книгу по ID:

{
  book(id: "1") {
    title
    pages
  }
}

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

Для добавления или изменения данных используются мутации. Пример:

public class BookMutation : ObjectGraphType
{
    public BookMutation(IDataStore dataStore)
    {
        Field<BookType>("addBook")
            .Arguments(new QueryArguments(
                new QueryArgument<NonNullGraphType<StringGraphType>> { Name = "title" },
                new QueryArgument<NonNullGraphType<StringGraphType>&