Введение в GraphQL

4 июня 2022 г. · 6 мин. чтения

1. Обзор

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

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

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

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

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

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

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

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

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

с помощью языка определения интерфейса GraphQL (IDL)
используя один из поддерживаемых языков программирования

Давайте продемонстрируем пример с использованием 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 («пользователь») как указание на то, что этот класс отображается 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));
      });
}

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

@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, теперь мы создаем UserMutation, который будет управлять всеми операциями, направленными на изменение некоторых заданных данных, хранящихся на стороне сервера:

@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 : @GraphQLName («запрос») и @GraphQLName («мутация»). Эти аннотации используются для определения операций запроса и мутации соответственно.

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

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

{
    "query": "mutation($name: String! $email: String!){
       createUser (name: $name email: $email) { id name email age } }",
    "parameters": {
        "name": "John",
        "email": "john@email.com"
     }
}

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

{
    "data": {
        "createUser": {
            "id": 1,
            "name": "John",
            "email": "john@email.com"
        }
    } 
}

Для операции ПОЛУЧИТЬ:

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

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

{
    "data": {
        "retrieveUser": {
            "name": "John",
            "email": "john@email.com"
        }
    }
}

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

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

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

{
    "data": {
        "retrieveUser": {
            "email": "john@email.com"
        }
    }
}

5. Вывод

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

Как всегда, пример доступен в нашем репозитории GitHub .

1. Обзор​

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

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

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

4. GraphQL-java​

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

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

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

5. Вывод​