Всем привет! Меня зовут Илья, я фронтенд-разработчик в hh.ru. В статье расскажу, как внедрить GraphQL на фронте, не переломав всё на своем пути.

В проекте мы используем React и Redux, для асинхронных запросов у нас есть собственная библиотека, а бэкенд работает на Java. Для получения данных используем страничные URL, а когда заходим на страницу, прямо по URl-у забираем все данные Аяксом. Это влечет за собой две проблемы — overfetching и underfetching. Проще говоря, либо у нас избыток данных, которые используются в данном рендере, либо их нехватка. Эту беду и призван решить GraphQL.

Если лень читать или больше нравится видеоформат — вам сюда.

Начнем ресерч

Итак, мы вместе с бэкендом уходим на ресерч. В процессе бэк выбирает свой фреймворк, а мы смотрим, что у нас там есть на фронте. А там целых три фреймворка — Relay, Apollo и URQL.

Relay

https://relay.dev/

Relay — это библиотека Фейсбука, очень мощный инструмент. В нем целая плеяда возможностей, но он оказывает довольно сильное влияние на архитектуру фронтенда и даже бэкенда. Это нам не очень подходит.

Apollo

https://www.apollographql.com/docs/react/

У Apollo потрясающее комьюнити, очень много пакетов, плюшек и свистелок. Это очень подкупает, но поскольку это большой фреймворк, он теряет в гибкости. Впрочем, все еще оставаясь привлекательным. Советую посмотреть доклады Павла Черторогова, он очень здорово качает тему GraphQL, и Apollo в частности. Если вы начинаете делать что-то с нуля, я бы посоветовал использовать только Apollo, он дает офигенный старт, и в принципе создает хорошую базу для приложения или клиент-сервера на Node.js или BFF.

URQL

https://formidable.com/open-source/urql/docs/

Теперь про URQL. В отличие от двух предыдущих — это библиотека, и нам она очень понравилась. Она позволяет гибко все настроить и оказывает не такое сильное влияние на архитектуру в самом приложении. А поскольку у нас React и Redux, достаточно старый стек и приложению больше пяти лет, нам требуется гибкое решение, чтобы пробовать разные гипотезы. URQL хорошо подходит для использования GraphQL на маленьких и больших проектах. Он максимально гибкий и при этом имеет такие же плюшки, как Apollo. Да, их не настолько много, но комьюнити активно развивается.

Ниже приведена таблица с указанием плюсов и минусов URQL по отношению к другим фреймворкам.

https://formidable.com/open-source/urql/docs/comparison/#comparison-by-features

All features are marked to indicate the following:

• ✅ Supported 1st-class and documented.
• ???? Supported and documented, but requires custom user-code to implement.
• ???? Supported, but as an unofficial 3rd-party library. (Provided it's commonly used)
• ???? Not officially supported or documented.

Core Features

Итого: в результате ресерча мы поняли, что нам не подходит ни Relay, ни Apollo, ни URQL. Бэкенд сообщил, что ему необходимо сделать достаточно много изменений в бэке и архитектуре, и, если бы они начали это делать одновременно с нашим фронтендом, то мы бы просто заморозили разработку.

Нам было нужно очень гибкое решение где-то в сторонке, чтобы мы могли писать запросы GraphQL, не сильно вмешиваясь в архитектуру фронтенд приложения. Мы договорились решать всё на сетевом уровне: оставляем приложение как есть, делаем запросы и инжектим клиент в библиотеку для асинхронных экшенов. Но прежде чем это сделать, мы выдвинем некоторые требования, которые хотелось бы видеть от нашей разработки.

Требования

1. GraphQL клиент
2. CI/CD и pre-commit
3. Playground
4. Unit-тесты
5. Стабы
6. GraphQL схема

Делаем GraphQL клиент

Мы используем на проекте axios и к нему написано много интерцептеров, которые также должны работать и для graphql запросов.

Для работы graphql на проекте понадобятся пакеты graphql, graphql-tag

Выполняем
yarn add graphql
yarn add -D graphql-tag

// Функция print работает с ast, преобразовывая его в строку запроса
import { print } from 'graphql/language/printer';
// Наша обертка над axios
import { HttpClient, HttpClientError } from 'Modules/http/httpClient';
import { graphQLEndPoint } from 'Utils/domain';

const httpGraphqlClient = new HttpClient({
  baseURL: graphQLEndPoint,
});

const getHttpConfig = ({ query, variables, ...rest }, operationName) => ({
  method: 'POST',
  data: {
    // в query попадает ast, которое подготовлено лоадером вебпак graphql-tag/loader
    // утилитой print из graphql ast преобразуем query в строку
    query: print(query),
    variables,
    // данные для мониторинга
    operationName,
  },
  params: {
    // дополнительно к запросу запишем параметр operationName, чтобы в логах видеть конкретную операцию graphqlEndpoint?operationName=xxx
    operationName,
  },
  ...rest,
});

const extractOperationName = (query) => {
  const { definitions } = query;
  const [def] = definitions;
  const {
    name: { value },
  } = def;
  return value;
};

const checkOperationType = (query, operationType) => {
  const { definitions } = query;
  const [def] = definitions;
  const { operation } = def;
  return operation === operationType;
};

const request = async (config) => {
  const { query, operationType } = config;
  const operationName = extractOperationName(query);

  if (!checkOperationType(query, operationType)) {
    throw new HttpClientError('fetcherGraphQL request invalid operation');
  }

  const { data } = await httpGraphqlClient.request(getHttpConfig(config, operationName));

  return data;
};

// Example 
async function fn() {
  const { data } = await request({ query: GraphQlQueryFile })
  return data;
}

Наша библиотека для асинхронных экшенов

Поговорим о нашей асинхронной библиотеке, чтобы вы понимали, как у нас работает код, и в чем фишка внедрения GraphQL на уровне сети. Для асинхронных операций у нас есть middleware. Называется она signal-middleware и находится в этом репозитории. Signal-middleware достаточно простая: у нас есть некоторый сигнал, мы на этот сигнал подписываемся по ключу и выполняем тот или иной action. Сюда мы можем заинжектить любые нужные нам функции. В данном случае сюда инжектится базово dispatch и, например, store.

Получили по ключику нашу функцию callback, исполнили, сделали запрос, записали ответ, и если что-то не так — обработали. В нашем случае библиотека доработана. Мы дополнительно провайдим наши клиенты для http-запросов. Добавив префикс :gql: в наименование сигнала, мы понимаем, какой http-клиент нужно заинжектить.

import { addReaction } from 'signal-middleware';

// http клиенты
import fetcher from 'Utils/fetcher/fetcher';
import fetcherGraphQL from 'Utils/fetcher/fetcherGraphQL';

// addReaction.js
export default (signalName, cancelType, signalReaction) => {
  let [cancelName, reactionHandler] = [cancelType, signalReaction];
  const processFetcher = signalName.includes(':gql:') ? fetcherGraphQL : fetcher;

  if (typeof cancelName === 'function') {
    cancelName = null;
    reactionHandler = cancelType;
  }

  const reaction = (storeUtils, ...args) =>
    reactionHandler(
      {
        ...storeUtils,
        fetcher: cancelName === null ? processFetcher : processFetcher.uniq(cancelName),
      },
      ...args
    );

  addReaction(signalName, reaction);
};

// signal.js
addReaction(`:gql:signal`, async ({ fetcher }) => {
    const data  = await fetcher.query(GraphQLQueryFile);
    //....
})

Проверки на CI/CD и pre-commit

Проверки на этапах CI/CD и pre-commit нужны в ситуации, если мы как-то ошибемся и наша схема не сойдется с бэкендом. Или что-то может пойти не так: мы передадим не тот аргумент, обратимся к полю, которого не существует или опечатаемся.

Настраиваем конфигурацию graphql на проекте, используя graphql-config

# .graphqlrc

# Путь до схемы
schema: "./.codegen/schema.graphql"
# Путь до операций и фрагментов
documents: "./app/**/**/*.graphql"

Далее подключаем плагин для eslint @graphql-eslint/eslint-plugin

Настраиваем конфигурацию:

// .eslintrc
    {

      "files": "*.graphql",
      "extends": "plugin:@graphql-eslint/operations-recommended",
      "plugins": ["@graphql-eslint"],
      "rules": {
        "prettier/prettier": [2, { "parser": "graphql" }],
        "spaced-comment": "off",
        "@graphql-eslint/executable-definitions": "error",
        "@graphql-eslint/fields-on-correct-type": "error",
        "@graphql-eslint/fragments-on-composite-type": "error",
        "@graphql-eslint/known-argument-names": "error",
        "@graphql-eslint/known-directives": "error",
        "@graphql-eslint/known-type-names": "error",
        "@graphql-eslint/no-anonymous-operations": "error",
        "@graphql-eslint/no-deprecated": "error",
        "@graphql-eslint/no-unused-variables": "error",
        "@graphql-eslint/provided-required-arguments": "error",
        "@graphql-eslint/scalar-leafs": "error",
        "@graphql-eslint/unique-argument-names": "error",
        "@graphql-eslint/unique-input-field-names": "error",
        "@graphql-eslint/unique-variable-names": "error",
        "@graphql-eslint/value-literals-of-correct-type": "error",
        "@graphql-eslint/variables-are-input-types": "error",
        "@graphql-eslint/variables-in-allowed-position": "error",
        "@graphql-eslint/require-id-when-available": "off",
        // Ограничиваем глубину запроса
        "@graphql-eslint/selection-set-depth": ["error", { "maxDepth": 20}],
        // Правила нейминга для операции и фрагментов
        "@graphql-eslint/naming-convention": [
          "error",
          {
            "VariableDefinition": "camelCase",
            "OperationDefinition": {
              "style": "PascalCase",
              "forbiddenPrefixes": ["Query", "Mutation", "Subscription", "Get"],
              "forbiddenSuffixes": ["Query", "Mutation", "Subscription"]
            },
            "FragmentDefinition": {
              "style": "camelCase",
              "forbiddenPrefixes": ["Fragment"],
              "forbiddenSuffixes": ["Fragment"]
            }
          }
        ],
        // Метчинг нейминга для файлов
        "@graphql-eslint/match-document-filename": [
          "error",
          {
            "fileExtension": ".graphql",
            "query": { "style": "camelCase", "suffix": ".query" },
            "mutation": { "style": "camelCase", "suffix": ".mutation" },
            "fragment": { "style": "camelCase", "suffix": ".fragment" }
          }
        ]
      }
    }

Напишем запрос:

query Person($id: Int!) {
  person(id: $id) {
    ... on PersonItem {
      area {
        someField
      }
    }
  }
}

Делаем наш обычный git-add и выполним команду lint-staged, который у нас запускает линтинг. Команда запустилась, но линтинг сообщает, что мы не можем это зафиксить: someField нет на типе Area.

  5:9  error  Cannot query field "someField" on type "Area"  @graphql-eslint/fields-on-correct-type
✖ 1 problem (1 error, 0 warnings)

Как результат, ошибку отловим на pre-commit или на этапе CI/CD.

Playground

В качестве плейграунда мы выбрали песочницу GraphiQL. Существует еще ряд графических редакторов для GraphQL, но этот понравился нам больше всего. Находится плейграунд в этом репозитории, он достаточно простой, кастомизированный, и нам этого достаточно.

Мы решили подключать его как cdn. У нас есть сборка, которую мы перекладываем в папочку build, подготовленные файлы — graphiql.min.jsи graphiql.min.css. И подключаем в html.

Заходим в плейграунд и выполняем простой запрос, который будет выглядеть так: выберем всех кандидатов, которые есть в базе.

Запрос выполнен — получили ожидаемый результат (плейграунд с готовой документацией и хорошей интроспекцией). А написанный запрос точно так же переносится в код.

Unit-тесты

Для нашего GraphQL клиента написали небольшую функцию, с помощью которой можно замокать данные. Под капотом мы используем Nock, библиотеку для мок сети, к ней написали маленькую обертку.

Пример запроса:

query PersonExample {
  person {
    name
  }
}

// ...
const result = await request(PersonExample);
// Имя запроса будет подставлено параметром
// http://localhost/graphql?operationName=PersonExample
//...

Напишем функцию, которая будет перехватывать все запросы по параметру operationName.

import nock from 'nock';

import { graphQLEndPoint } from 'Utils/domain';

const [endPointUrl] = graphQLEndPoint.split('/graphql');

/**
 * Мок функция для удобной работы с сетевыми http-запросами graphql
 *
 * @param {string} requestName имя query или mutation для сопоставления запроса
 * @prop {object={}} params
 * @prop {boolean} [params.persist] сохранять все перехватчики
 */
export const createMockFetcherGraphQL = (requestName, { persist = false } = {}) => {
  const scope = persist ? nock(endPointUrl).persist() : nock(endPointUrl);
  //
  const request = scope.post(`/graphql?operationName=${requestName}`);

  return {
    /**
     * Прокси метод над nock.reply
     *
     * @see https://github.com/nock/nock#specifying-replies
     * @see https://github.com/nock/nock/blob/main/types/index.d.ts#L165-L184
     * @param {number} statusCode
     * @param {object|function} [reply={}] для удобства используем как body или callback для доступа к req
     * @returns
     */
    reply(statusCode, reply) {
      return request.reply(statusCode, reply);
    },
  };
};

/**
 * Сброс моков
 */
export const clearMocksFetcherGraphQL = () => {
  nock.cleanAll();
  nock.restore();
};

Теперь любой запрос на проекте можем перехватить c помощью createMockFetcherGraphQL('operationName') и подменить тело ответа.

Для наглядности рассмотрим пример, в котором хотим проверить, правильно ли прокидываются наши variables.

Подготавливаем сет данных expectVariables и expectResponse, в которых мы заинтересованы. Вызываем функцию, она должна сработать, когда у нас будет FetcherGraphQLGetTest.

Делаем запрос, сравниваем, подходят ли перехваченные variables, которые у нас есть в запросе.

Проверка прошла успешно. Именно таким образом мы можем мокать данные в unit-тестах.

Стабы

В нашем стандартном клиенте есть механизм стабов, поэтому хотелось бы видеть его и в GraphQL. Тут достаточно простая реализация: у нас есть некоторый запрос, мы смотрим на фиче-флаг — если он включен, отдаем стабы по operationName.

async function request(config) {
    //..
  try {
    if (featureEnabled(FEATURE_STUB)) {
      const result = await stubs(`graphql/${operationName}`, 'POST');
      try {
        if (result) {
            // result это объект new Response(стаб);
          const { data } = await result();
          return data;
        }
      } catch (err) {
        return Promise.reject(err.response.data);
      }
    }
  } catch (ignore) {}
  //...
}

Подготавливаем json файлы, которые будут подменять тело ответа при вызове stubs(graphql/operationName);

// Делаем проверку на окружение, чтобы стабы не попали в продакшн сборку
if (process.env.NODE_ENV === 'development') {
  // eslint-disable-next-line import/no-dynamic-require
  const requireHelper = (file) => require(`App/stubs/json/${file}.json`);
  hardcodedItems = [
    {
      regexp: 'example',
      action: createResponse(bindReceiver(requireHelper('get-example')), 200),
      method: 'GET',
      delay: 0,
    },
    {
      regexp: 'graphql/PersonsList',
      method: 'POST',
      action: createResponse(bindReceiver(requireHelper('persons.query')), 200),
      delay: 0,
    },
  ];
}

У нас есть подготовленный стаб для операции PersonsList.

Есть страничка “persons”. На скриншоте видно, что данные получаем из запроса graphql?operationName=PersonsList

Включаем стаб и для наглядности что-нибудь поменяем. Выполним достаточно простой пример: сделаем всем кандидатам зарплату, например, 100500.

Такой механизм стабов помогает разрабатывать в отрыве от бэкенда, готовить компоненты к данным или пробовать на фронтенде сложную логику.

Более подробно об этой фиче рассказывает Никита Мостовой в докладе "Стабы для фронтенда".

Получение GraphQL схемы

Для этого написали простой скрипт, который делает запрос к graphql серверу и преобразовывает ответ в готовый SDL graphql.

const { getIntrospectionQuery, buildClientSchema, printSchema } = require('graphql/utilities');

async function fetchSchema() {
  try {
    // eslint-disable-next-line no-console
    console.log('fetchSchema', 'start', GRAPHQL_END_POINT_SCHEMA);
    const {
      data: { data: introspection },
    } = await axios({
      url: GRAPHQL_END_POINT_SCHEMA,
      method: 'POST',
      headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json',
      },
      data: JSON.stringify({ query: getIntrospectionQuery(), operationName: 'IntrospectionQuery' }),
    });
    // eslint-disable-next-line no-console
    console.log('fetchSchema', 'ok');
    return buildClientSchema(introspection);
  } catch (e) {
    console.error(`fetchSchema ${e.message}`);
  }
}
//...

Полученную схему складываем в папку codegen.

По такому принципу мы и работаем с бэкендом. А если говорить о подходе сode-first, то мы просто переключаемся на стенды, где раскатана бэк-ветка с новой схемой, и оттуда забираем схему.

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

Боевая задача

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

У нас есть список с пагинацией, в левом сайдбаре живут фильтры, с помощью которых можно отсортировать кандидатов по возрасту, вакансии или зарплате.

Попробуем перенести все это на GraphQL и сделаем запрос в GraphQL Playground.

Пробуем в Playground

Пишем наш первый запрос, назовем его PersonsList. Начинаться он будет с ключевого слова query. Нам подсказывают, что у нас есть persons — то что нужно, здесь у нас будут кандидаты. Появился резолвер, у него есть три аргумента, но нам пока интересен только аргумент first. Он определяет, сколько элементов нам нужно выдать для рендера. Для наглядности возьмем три кандидата.

Посмотрим, что у нас внутри person: фильтры, pageinfo и items. Из айтемов нам нужны: firstName, lastName, age и id. Запишем в запрос:

Справа на скриншоте — тело ответа.

Окей, persons получили. Теперь попробуем сделать пагинацию. Проваливаемся в документацию и выбираем pageInfo:

Здесь видим такой флажочек — есть ли у нас следующий список кандидатов и endCursor, после которого нам надо будет выдать следующую пачку. Попробуем воспользоваться этим резолвером и посмотрим, что у него внутри:

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

Еще здесь есть аргумент after, в который мы вставим то, что скопировали из endCursor:

Запрос выполнился, появилась следующая пачка кандидатов. Пагинация работает как надо.

Следующая задача — сделать фильтры из сайдбара, который я демонстрировал выше. В рамках нашей тестовой задачи будем фильтровать кандидатов по возрасту. Для начала нам нужно понять, какие состояния у фильтров. Пишем filters и смотрим, что GraphQL предлагает нам по PersonsFilters:

Очень удобно, что можно провалиться прямо на ходу — интроспекция отличная. Можно посмотреть информацию о каждом поле. У нас есть ageFrom и поле used, которое говорит, какой возраст используется в данный момент.

Напишем, что наш query принимает аргументы и попробуем их передать. Начнем с $cursor, потому что мы уже его проработали. Обозначим, что это поле string. В after тоже будет приходить $cursor. Теперь попробуем его прокинуть.

Запрос выполнился, пришли те же самые кандидаты. А, значит, все работает. Теперь попробуем с фильтром. Впишем его в query, назовем $filterInput: PersonFilterInput. Передадим его в persons и выполним запрос.

Запрос прошел, но used пустой. Выходит, нужно прокинуть параметры для фильтра. Пишем ageFrom и фильтруем кандидатов от 25 лет. Запускаем.

Огонь! Отфильтровали новых кандидатов — все, кому меньше 25 лет, полностью исключены из выборки. Также в поле used появился флажок с активным фильтром. Итого: у нас получилось организовать фильтрацию и пагинацию — всё, что требовалось для выполнения задачи.

Пробуем в коде

Открываем наш асинхронный код, отвечающий за загрузку персон. Здесь у нас есть реакция, ключевой сигнал и тот же самый запрос, который делаем при страничном get. Мы что-то спрашиваем, обновляем и выполняем запрос:

Как это будет выглядеть в GraphQL? Да практически так же. У нас точно такой же сигнал и обработка. Единственное отличие — префикс, который позволяет прокидывать по другому префиксу правильный клиент для запроса. В нашем случае он называется fetcher:

Всё то же самое: делаем запрос, подготавливаем данные. Они немного отличаются по телу функции, потому что нам приходится мириться с тем, что нам нужно мапить данные под другие резолверы и экшены. Несущественный минус, поскольку всё это достаточно легко обработать.

Передаем в запрос PesonaListQuery и variables, которые мы прокидывали еще в playground.

Вот и вся наша реализация. Мы приложили минимум усилий, чтобы сделать GraphQL-запрос. У нас просто появился флажок, который спрашивает, что использовать для загрузки списка персон: GraphQL или старый страничный url. А сам запрос состоит из тех же самых полей.

Вместо заключения

У GraphQL есть свои преимущества и недостатки. Преимущества: бэкенд и фронтенд работают по строго типизированной схеме, документированный API из коробки и большое комьюнити. Недостатком является отсутствие в GraphQL классического подхода обработки ошибок (как с HTTP-кодами: мониторинг, подсчет SLA, откаты релизов при “пятисотках").

Итак, у нас получилось бесшовно внедрить GraphQL и получить плюшки фреймворков, не переломав всё на своем пути, а также предусмотреть последующую интеграцию во фреймворк или библиотеку.