Як використовувати HotChocolate для застосування директиви Key до типів об’єктів у GraphQL

Оптимізація типів об’єктів за допомогою ключової директиви в HotChocolate

Під час використання GraphQL із HotChocolate вам може знадобитися розширити типи об’єктів за допомогою директив, таких як @ключ директиви, щоб забезпечити сумісність з Apollo Federation. Це особливо важливо для об’єднаних схем, у яких ключі ідентифікують сутності в кількох службах. Важливо розуміти, як правильно проектувати типи об’єктів за допомогою цих директив.

Ця стаття покаже, як використовувати HotChocolate щоб прикрасити типи об’єктів за допомогою @ключ директива. Ми також розглянемо конкретні приклади використання коду C# для створення простого Батько клас і як змінити створену схему GraphQL. Акцент буде зроблено на фактичних діях, які ви можете зробити, щоб створити цю функціональність.

Під час використання HotChocolate для створення типів об’єктів GraphQL, @ключ Директива не може бути застосована миттєво, як очікувалося. Натомість схема може створювати просту структуру типу, у якій відсутні важливі функції, необхідні для об’єднання. Ми розглянемо, як це вирішити, щоб ваша схема працювала належним чином.

Ми також розглянемо найважливіші завдання конфігурації, такі як зміна налаштувань сервера GraphQL і використання правильного HotChocolate і Федерація Аполлон пакети. За допомогою належної конфігурації ви можете легко застосувати директиви та забезпечити належне об’єднання схем для своїх служб.

Розуміння ролі ключових директив у HotChocolate

Перший сценарій пояснює, як реалізувати @ключ директива використання HotChocolate у C#. Цей сценарій гарантує, що створена схема GraphQL містить @ключ директива для федерації з федерацією Apollo. Сценарій починається зі створення a Батько класу та присвоєння в [Ключ] і [ID] атрибутів до його полів. Ці властивості важливі для інформування HotChocolate про позначення id поле як унікальний ідентифікатор сутності. Це має вирішальне значення при створенні об’єднаної служби GraphQL, у якій об’єкти можуть використовуватися кількома службами. Позначення цього поля дозволяє службі GraphQL розпізнавати сутність у об’єднаних запитах.

The ReferenceResolver функція також є важливим компонентом сценарію. Ця статична функція дозволяє HotChocolate розпізнати сутність шляхом пошуку Батько об'єкт у сховищі. The ParentRepository зареєстровано на сервері GraphQL, і отримати метод отримує батьківський елемент за його id. У коді початкового завантаження, .AddQueryType інструкція реєструє Запит об’єкт, який використовується для виконання запитів GraphQL.RegisterService дозволяє впроваджувати залежності, такі як ParentRepository, у резолвери GraphQL. Цей дизайн спрощує пошук даних, зберігаючи чіткий розподіл проблем.

У другому прикладі використовується підхід на основі схеми, використовуючи GraphQL SDL (Schema Definition Language) для визначення @ключ директива в схемі. Це рішення особливо ефективне для команд, які вже знайомі з синтаксисом SDL GraphQL. У цьому прикладі @ключ директива застосовується до Батько типу, чітко вказуючи на id поле як унікальний ідентифікатор. Використання schema-first дозволяє розробникам мати більше контролю над тим, як будується схема GraphQL, і змінювати її, не вдаючись до коду C#, що робить її більш гнучким варіантом для великих команд.

Нарешті, компонент модульного тестування підтверджує, що код працює належним чином. Використовуючи структуру тестування xUnit, Assert.The Contains команда гарантує, що результуюча схема включає @ключ директива. Цей тест перевіряє схему на наявність @ключ директива, яка підтверджує, що службу правильно налаштовано для об’єднання. Модульне тестування є найкращою практикою для того, щоб переконатися, що зміни у схемі GraphQL або методах резолвера не порушують функціональність, особливо в об’єднаній системі, де кілька служб повинні безперебійно працювати разом.

using HotChocolate;
using HotChocolate.Types;
using HotChocolate.Types.Relay;
using Microsoft.Extensions.DependencyInjection;
public class Parent
{
    public Parent(string id, string name)
    {
        Id = id;
        Name = name;
    }
    [Key]
    [ID]
    public string Id { get; }
    public string Name { get; }
    [ReferenceResolver]
    public static Parent? Get(ParentRepository repository, string id)
    {
        return repository.GetParent(id);
    }
}
public class Query
{
    public Parent GetParent(string id, [Service] ParentRepository repository)
    {
        return repository.GetParent(id);
    }
}
public void ConfigureServices(IServiceCollection services)
{
    services.AddGraphQLServer()
        .AddQueryType<Query>()
        .RegisterService<ParentRepository>()
        .AddApolloFederation();
}

type Parent @key(fields: "id") {
    id: ID!
    name: String!
}
extend type Query {
    parent(id: ID!): Parent
}
extend type Mutation {
    createParent(id: ID!, name: String!): Parent
}
directive @key(fields: String!) on OBJECT | INTERFACE

schema {
    query: Query
    mutation: Mutation
}

using Xunit;
using HotChocolate.Execution;
using Microsoft.Extensions.DependencyInjection;
public class ParentTests
{
    [Fact]
    public async Task ParentSchema_ContainsKeyDirective()
    {
        var serviceCollection = new ServiceCollection();
        serviceCollection.AddGraphQLServer()
            .AddQueryType<Query>()
            .AddApolloFederation();
        var serviceProvider = serviceCollection.BuildServiceProvider();
        var schema = await serviceProvider.GetRequiredService<ISchemaAsync>().ExecuteAsync();
        Assert.Contains("@key(fields: \"id\")", schema.ToString());
    }
}

Покращення GraphQL за допомогою Apollo Federation і HotChocolate

Використання GraphQL із HotChocolate у федеративному середовищі вимагає добре структурованого з’єднання схем. Apollo Federation дозволяє розробникам розділяти схеми між кількома службами, зберігаючи єдиний інтерфейс. Використовуючи @ключ за допомогою директиви HotChocolate, ви можете вказати, як об’єкти GraphQL розпізнаються в кількох службах. Це робить ваш API більш модульним і масштабованим, що особливо корисно у великих розподілених системах, де кілька команд контролюють різні аспекти схеми GraphQL.

У типовій об’єднаній схемі такі сутності, як Батько може існувати в багатьох службах. Федерація Apollo використовує @ключ директива для унікальної ідентифікації сутності на основі вказаного поля, наприклад id. Підтримка HotChocolate Apollo Federation гарантує, що ваш сервіс легко інтегрується у більшу інфраструктуру. Окрім встановлення ключів, ви можете використовувати директиви об’єднання, наприклад as @extends або @зовнішній для керування полями даних, розподіленими між кількома мікросервісами, забезпечуючи більшу гнучкість налаштування GraphQL.

Іншим ключовим фактором при використанні HotChocolate є оптимізація продуктивності. Надлишок даних є поширеною проблемою API GraphQL, особливо в об’єднаних контекстах. Використовуючи правильні резольвери, такі як ReferenceResolver описаний у попередніх випадках, гарантує, що ваш API надає лише необхідні дані без надмірних пошуків. Крім того, HotChocolate підтримує розширені алгоритми групування запитів і кешування, які можуть збільшити швидкість відповіді API та ефективність у об’єднаній схемі.