«Введение в GraphQL» - Spring на русском

«1. Обзор

GraphQL — это язык запросов, созданный Facebook с целью создания клиентских приложений на основе интуитивно понятного и гибкого синтаксиса для описания их требований к данным и взаимодействий.

Одной из основных проблем с традиционными вызовами REST является неспособность клиента запросить настраиваемый (ограниченный или расширенный) набор данных. В большинстве случаев, когда клиент запрашивает информацию с сервера, он либо получает все поля, либо ничего не получает.

Другая трудность заключается в работе и обслуживании нескольких конечных точек. По мере роста платформы, следовательно, число будет увеличиваться. Поэтому клиентам часто приходится запрашивать данные с разных конечных точек.

При создании сервера GraphQL необходимо иметь только один URL-адрес для получения и изменения всех данных. Таким образом, клиент может запросить набор данных, отправив строку запроса, описывающую то, что он хочет, на сервер.

2. Базовая номенклатура GraphQL

Давайте рассмотрим базовую терминологию GraphQL.

Запрос: это операция только для чтения, запрашиваемая на сервере GraphQL. Мутация: это операция чтения-записи, запрашиваемая на сервере GraphQL. отвечает за обработку запроса. Он аналогичен серверной части MVC в приложении RESTFul. Тип: тип определяет форму данных ответа, которые могут быть возвращены с сервера GraphQL, включая поля, которые являются границами для других типов. Ввод: как тип, но определяет форму входных данных. который отправляется на сервер GraphQL Scalar: это примитивный тип, такой как String, Int, Boolean, Float и т. д. Интерфейс: интерфейс будет хранить имена полей и их аргументы, поэтому объекты GraphQL могут наследоваться от него, гарантируя использование определенных полей Схема: в GraphQL схема управляет запросами и мутациями, определяя, что разрешено выполнять на сервере GraphQL

2.1. Загрузка схемы

Существует два способа загрузки схемы на сервер GraphQL:

by using GraphQL’s Interface Definition Language (IDL)
by using one of the supported programming languages

Давайте продемонстрируем пример с использованием IDL:

type User {
    firstName: String
}

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

GraphQLObjectType userType = newObject()
  .name("User")  
  .field(newFieldDefinition()
    .name("firstName")
    .type(GraphQLString))
  .build();

3. Язык определения интерфейса

Язык определения интерфейса (IDL) или язык определения схемы (SDL) — это наиболее краткий способ указать схему GraphQL. Синтаксис четко определен и будет принят в официальной спецификации GraphQL.

Например, давайте создадим схему GraphQL для пользователя/электронной почты, которые могут быть указаны следующим образом:

schema {
    query: QueryType
}

enum Gender {
    MALE
    FEMALE
}

type User {
    id: String!
    firstName: String!
    lastName: String!
    createdAt: DateTime!
    age: Int! @default(value: 0)
    gender: [Gender]!
    emails: [Email!]! @relation(name: "Emails")
}

type Email {
    id: String!
    email: String!
    default: Int! @default(value: 0)
    user: User @relation(name: "Emails")
}

4. GraphQL-java

GraphQL-java — это реализация, основанная на спецификации и справочнике по JavaScript. выполнение. Обратите внимание, что для правильной работы требуется как минимум Java 8.

4.1. Аннотации GraphQL-java

GraphQL также позволяет использовать аннотации Java для создания определения схемы без всего шаблонного кода, созданного с использованием традиционного подхода IDL.

4.2. Зависимости

Чтобы создать наш пример, давайте сначала начнем импортировать необходимую зависимость, которая опирается на модуль Graphql-java-annotations:

<dependency>
    <groupId>com.graphql-java</groupId>
    <artifactId>graphql-java-annotations</artifactId>
    <version>3.0.3</version>
</dependency>

Мы также реализуем библиотеку HTTP, чтобы упростить настройку в нашем приложении. Мы собираемся использовать Ratpack (хотя его можно реализовать и с помощью Vert.x, Spark, Dropwizard, Spring Boot и т. д.).

Давайте также импортируем зависимость Ratpack:

<dependency>
    <groupId>io.ratpack</groupId>
    <artifactId>ratpack-core</artifactId>
    <version>1.4.6</version>
</dependency>

4.3. Реализация

Давайте создадим наш пример: простой API, предоставляющий «CRUDL» (создание, извлечение, обновление, удаление и список) для пользователей. Во-первых, давайте создадим наш POJO пользователя:

@GraphQLName("user")
public class User {

    @GraphQLField
    private Long id;
 
    @GraphQLField
    private String name;
 
    @GraphQLField
    private String email;
  
    // getters, setters, constructors, and helper methods omitted
}

В этом POJO мы видим аннотацию @GraphQLName(“user”), как указание на то, что этот класс отображается GraphQL вместе с каждым полем, аннотированным @GraphQLField.

Далее мы создадим класс UserHandler. Этот класс наследует от выбранной библиотеки HTTP-коннектора (в нашем случае Ratpack) метод-обработчик, который будет управлять и вызывать функцию Resolver GraphQL. Таким образом, перенаправление запроса (полезных данных JSON) на правильный запрос или операцию мутации:

@Override
public void handle(Context context) throws Exception {
    context.parse(Map.class)
      .then(payload -> {
          Map<String, Object> parameters = (Map<String, Object>)
            payload.get("parameters");
          ExecutionResult executionResult = graphql
            .execute(payload.get(SchemaUtils.QUERY)
              .toString(), null, this, parameters);
          Map<String, Object> result = new LinkedHashMap<>();
          if (executionResult.getErrors().isEmpty()) {
              result.put(SchemaUtils.DATA, executionResult.getData());
          } else {
              result.put(SchemaUtils.ERRORS, executionResult.getErrors());
              LOGGER.warning("Errors: " + executionResult.getErrors());
          }
          context.render(json(result));
      });
}

@GraphQLName("query")
public class UserQuery {

    @GraphQLField
    public static User retrieveUser(
     DataFetchingEnvironment env,
      @NotNull @GraphQLName("id") String id) {
        // return user
    }
    
    @GraphQLField
    public static List<User> listUsers(DataFetchingEnvironment env) {
        // return list of users
    }
}

«Теперь класс, который будет поддерживать операции запросов, т. е. UserQuery. Как уже упоминалось, все методы, которые извлекают данные с сервера на клиент, управляются этим классом:

@GraphQLName("mutation")
public class UserMutation {
 
    @GraphQLField
    public static User createUser(
      DataFetchingEnvironment env,
      @NotNull @GraphQLName("name") String name,
      @NotNull @GraphQLName("email") String email) {
      //create user information
    }
}

Аналогично UserQuery, теперь мы создаем UserMutation, который будет управлять всеми операциями, предназначенными для изменения некоторых заданных данных, хранящихся на на стороне сервера:

Стоит обратить внимание на аннотации в классах UserQuery и UserMutation: @GraphQLName («запрос») и @GraphQLName («мутация»). Эти аннотации используются для определения операций запроса и мутации соответственно.

Поскольку сервер GraphQL-java может выполнять операции запроса и мутации, мы можем использовать следующие полезные данные JSON для проверки запроса клиента на сервере:

{
    "query": "mutation($name: String! $email: String!){
       createUser (name: $name email: $email) { id name email age } }",
    "parameters": {
        "name": "John",
        "email": "[email protected]"
     }
}

Для операции CREATE:

{
    "data": {
        "createUser": {
            "id": 1,
            "name": "John",
            "email": "[email protected]"
        }
    } 
}

Как ответ сервера на эту операцию:

{
    "query": "query($id: String!){ retrieveUser (id: $id) {name email} }",
    "parameters": {
        "id": 1
    }
}

Для операции RETRIEVE:

{
    "data": {
        "retrieveUser": {
            "name": "John",
            "email": "[email protected]"
        }
    }
}

Как ответ сервера на эту операцию:

{
    "query": "query($id: String!){ retrieveUser (id: $id) {email} }",
    "parameters": {
        "id": 1
    }
}

GraphQL предоставляет функции, которые клиент может настроить ответ. Итак, в последней операции RETRIEVE, используемой в качестве примера, вместо возврата имени и электронной почты мы можем, например, вернуть только электронную почту:

{
    "data": {
        "retrieveUser": {
            "email": "[email protected]"
        }
    }
}

Таким образом, возвращаемая информация с сервера GraphQL будет возвращать только запрашиваемые данные:

5. Заключение

GraphQL — это простой и довольно привлекательный способ минимизировать сложность между клиентом и сервером в качестве альтернативного подхода к REST API.

«Введение в GraphQL»