Мой OpenSource

• graphql-compose — генерация GraphQL-схем
  
• mongodb-memory-server — MongoDB для тестов
  
• lvovich — склонение городов (from, to, in)
  
• react-relay-network-layer — NetworkLayer для Relay
  
• и россыпь других

Сейчас в ps.kz

(казахстанской хостинговой компании)
строим облачный хостинг
и консоль к нему на GraphQL 👌

Если вы новичок в GraphQL,
то посмотрите выступление Ильи

GraphQL в 2018 / Илья Климов / MYKOLAIV JS 2018

https://www.youtube.com/watch?v=_vjSZhnYhfI

Ну что, погнали?!

А реально обернуть REST API в GraphQL?

• C авторизацией
• Без проблемы N+1 (DataLoader)
• С защитой от DoS (QueryCost)

РЕАЛЬНО!

Обычно обкатку технологии принято делать на TodoMVC.

Так и поступим!

А коль я непростой человек,
то придётся мне брать
и непростое Todo-приложение 😈

Возьму-ка систему управления проектами Wrike

Открою их REST API https://developers.wrike.com/api/v4

Фи, делов-то на пару дней!

– подумал я.

И вшатал 160 часов!

• только на демку, без слайдов
• из-за чёртового оптимизма

В REST API у Wrike оказалось:

• 22 entity
• 87 методов

Ну, нормально так Wrike прокачал свой "TodoMVC" за 14 лет 😅

В итоге,
GraphQL получился таким:

• 22 entity
• 41 поле в Query
• 65 полей в Mutation

Сперва у меня получился RestQL

слабосвязный GraphQL

Но потом добавил связей,
которые есть в Data Domain,
и получил полноценный
"волосатый" GraphQL

Любые генераторы REST API в GraphQL
выдадут RestQL (то что слева)

И только люди могут передать данные о связях для полноценного GraphQL (то что справа)

Немного итоговых GraphQL цифр:

• 134 GraphQL-типа
• 1002 поля и аргумента
• 51 явная прямая связь между entity
• 26 неявных обратных связей

И теперь у ещё одного 🦄
появилось удобное
"волосатое" GraphQL апи

Ну если АПИ есть, пора бы что-то нехитрое запросить

За один запрос получим данные для Dashboard

Даешь LEFT JOIN для клиента 😱

Практическая методология –
это алгоритм, набор приёмов и способов того, как достичь желаемой практической цели.

• M1: Создание обёртки к REST API vendor
• M2: Описание общих GraphQL-типов schema/types
• M3: Описание Entity schema/entities
• M4: Описание точек входа в граф schema/entrypoints
• M5: Расширение Entity прямыми связями по id
• M6: Создание DataLoaders (N+1) schema/dataLoaders
• M7: Создание резолверов Реляций schema/relations
• M8: Прикручивание QueryCost (DoS)
• M9: Авторизация

Types & fields are different ☝️

• GraphQL types
  • Entities
  • Common types
• GraphQL fields (FieldConfigs)
  • Entrypoints
  • Relations
  • DataLoaders

Repo: https://github.com/nodkz/wrike-graphql

Live demo: https://graphql-wrike.herokuapp.com

Voyager: https://graphql-wrike.herokuapp.com/voyager

Docker: https://hub.docker.com/r/nodkz/wrike-graphql

Сперва пишем SDK

Берём пакеты: axios + debug

• упрощает написание запросов
• отладка запросов

Воссоздаём все REST API endpoints

• 22 entity
• 87 методов

И не забываем про примитивную типизацию ☝️

Примитивная типизация нужна для того, чтобы отлавливать будущие изменения в REST API

Для каждого эндпоинта

• даём уникальные имена всем функциям ☝️
• типизируем входящие аргументы
• прописываем HTTP-метод

Смотрим src/vendor

Грубая оценка M1

find ./src/vendor -name '*.ts' | xargs wc -l

• 93 files
• 2275 LoC
• ⏱ 30 часов (~20 min на эндпоинт)

Эх, был бы какой-нить OpenAPI,
то можно было бы:

• сгенерировать этот самый vendor
• избавиться от мук изменений REST API в будущем

Описываем часто-используемые
"конечные типы" (Leaf types, common types),
которые ни от кого не зависят

"Конечные типы" (Leaf types)

• Скаляры
• Enum
• Output и Input (структуры)

Для описания Типов я использую

graphql-compose

Что такое graphql-compose?

• Это прокаченная тулза на NodeJS для написания
  GraphQL-схем с кучей сахара
• Это type registry, с возможностью редактирования и клонирования типов для написания генераторов
  GraphQL-схем.
• Это и schema-first и code-first в одном флаконе

Смотрим schema/types

Грубая оценка M2

• 24 Scalars
• 35 Enums
• 7 Output types
• 14 Input types
• ~ ⏱ 10 часов

Что такое Entity?

Это бизнес сущность с ID

К примеру, таблица в БД

В Api Wrike 22 entity

А всего 134 GraphQL-типа

20% entity типов M3 и 80% "обслуживающих" типов M2
Вильфредо в шоке

Entity описывают

• поля из которого состоит объект
• связи с другими entity
• "любят" вызывать проблемы hoisting'а

Hoisting problem – это когда
модули импортируют друг друга,
используют переменные друг друга,
но одна из них еще не инициализирована.

module1.ts

import { TaskTC } from './module2'; FolderTC.addFields({  tasks: {    type: () => TaskTC.List,    description: 'List of Tasks',  },});

module2.ts

import { FolderTC } from './module1'; TaskTC.addFields({  folder: {    type: () => FolderTC,    description: 'Folder where task',  },});

Смотрим schema/entities

Грубая оценка M3

• 22 Entity
• 1196 LoC
• ~ ⏱ 10 часов

Это время без учёта общих типов (M2)
и связей между Entity (M5,M7).

Пример создания схемы из JSON ответа
(быстро, дёшево, сердито):

https://youtu.be/ar7-HXBYfnk?t=1788

Наблюдение:

• Когда создавал тип Task по ответу из JSON
  • то упустил кучу специфичных полей (CustomFields, Recurrent, Dependencies)
  • потерял документацию

Описываем входные точки

• query
• mutation
• subscription

За 5 лет я перепробовал кучу подходов в построении схем

https://github.com/nodkz/conf-talks/tree/master/articles/graphql/schema-build-ways

https://youtu.be/RmGxUfmksck

И сейчас использую
graphql-compose-modules ☝️

Подход начала 2020 года

Сканирует папку и строит схему

И AST в нём, чтоб его трансформировать

А ещё – это удобный способ работы со схемой:

• удобно смотреть схему через файлы
• лёгкий рефакторинг схемы
• удобный код ревью
• тестирование схемы по кускам

Смотрим schema/entrypoints и server.ts

По завершении этого этапа (M4)
получаем RestQL (графкуэль без связей)

Грубая оценка M4

• 41 query + 65 mutation entrypoints
• 1034 + 1454 LoC
• ~ ⏱ 40 часов

В Entity, где есть поля с ID на другие Entity...

export const TaskTC = schemaComposer.createObjectTC({  name: 'Task',  fields: {    accountId: AccountID.NonNull,    parentIds: FolderID.NonNull.List,    superParentIds: FolderID.NonNull.List,    sharedIds: ContactID.NonNull.List,    responsibleIds: ContactID.NonNull.List,    authorId: ContactID.NonNull,    followerIds: ContactID.NonNull.List,    superTaskIds: TaskID.NonNull.List,    subTaskIds: TaskID.NonNull.List,    dependencyIds: DependencyID.NonNull.List,  },});

...добавляем новые поля с резолверами:

TaskTC.addFields({  ...  // authorId: ContactID.NonNull,  author: {    type: () => ContactTC,    resolve: async (source, args, context, info) => {      // метод из папки `vendor/`      return contactFindById(source?.authorId, context);    },  },  ...});

По факту, мы делаем что-то типа
LEFT JOIN по id

Вы id не знаете. База сама вяжет две таблицы – берёт поле с одной таблицы (source) и по его значение фильтрует и вытягивает записи из другой.

С REST API пока не получите значение, следующий запрос сделать не сможете.

Добавили 51 связь, и GraphQL преобразился

Смотрим schema/entities/TaskTC.ts

Грубая оценка M5

• 51 связь
• ~ ⏱ 10 часов

Делается быстро, но чревато проблемой N+1

Что такое DataLoader?

Проблема N+1 хорошо расписана у меня в REPO: https://github.com/nodkz/conf-talks/blob/master/articles/graphql/dataloader/N+1.md

В нашем примере ДатаЛоадеры позволяют решить проблему N+1 и сократить кол-во HTTP запросов к REST API.

DataLoader – это batch loader:

• у него из разных мест запрашивают Entity по любому id
• он возвращает Promise на каждый запрос
• на nextTick группирует все id и делает 1 запрос findMany(ids)
• получает ответ и разрезолвивает промисы в шаге 2

import DataLoader from 'dataloader';import { taskFindByIds } from 'app/vendor/task/taskFindByIds'; const dl = new DataLoader(async (ids) => {  const results = await taskFindByIds({ ids });  return ids.map(    (id) => results.find((x) => x.id === id) || new Error(`Task: no result for ${id}`)  );}); const dataPromise1 = dl.load(1);const dataPromise2 = dl.load(2);const arrayDataPromise = dl.loadMany([2, 10, 15]);

Существует 3 scope, где можно создать DataLoader'ы

• Глобальный на сервер (1 раз при старте сервера)
• Глобальный на операцию (в рамках 1 http-запроса)
• Локальный на поле в запросе (для конкретного 1го поля в 1ом запросе)

Дата-лоадеры в демо wrike-graphql

• 0 глобальных на сервер (обычно жёсткие справочники)
• 8 глобальных на операцию (записи возвращаются полностью, смело можно использовать глобально в рамках запроса)
• 4 fieldNode-specific (зависят от запрошенных полей в запросе)

12 DataLoaders serves 51 direct relations ☝️

Встраивать DataLoader'ы в resolve-методы достаточно муторно, много копипасты:

const ArticleType = new GraphQLObjectType({  name: 'Article',  fields: () => ({    author: {      type: AuthorType,      resolve: (source, args, context, info) => {        // context.dataloaders был создан на уровне сервера (см сниппет кода выше)        const { dataloaders } = context;         // единожды инициализируем DataLoader для получения авторов по ids        let dl = dataloaders.get(info.fieldNodes);        if (!dl) {          dl = new DataLoader(async (ids: any) => {            // обращаемся в базу чтоб получить авторов по ids            const rows = await authorModel.findByIds(ids);            // IMPORTANT: сортируем данные из базы в том порядке, как нам передали ids            const sortedInIdsOrder = ids.map(id => rows.find(x => x.id === id));            return sortedInIdsOrder;          });          // ложим инстанс дата-лоадера в WeakMap для повторного использования          dataloaders.set(info.fieldNodes, dl);        }         // юзаем метод `load` из нашего дата-лоадера        return dl.load(source.authorId);      },    },  }),});

поэтому генерируем через resolveOneViaDL:

TaskTC.addFields({  author: {    type: () => ContactTC,-    // Старый метод с N+1 проблемой-    resolve: async (source, args, context, info) => {-      return contactFindById(source?.authorId, context);-    },+    // Новый метод через DataLoader+    resolve: resolveOneViaDL('ContactID', (s) => s.authorId),  },});

resolveOneViaDL() возвращает resolve метод для GraphQL

export function resolveOneViaDL(  entityName: DataLoaderEntityNames,  idGetter: (s, a, c, i) => string): GraphQLFieldResolver<any, any> {  return (source, args, context, info) => {    const id = idGetter(source, args, context, info);    if (!id) return null;    return getDataLoader(entityName, context, info).load(id);  };}

getDataLoader()

/** * Get DataLoader instance, global o fieldNode specific */function getDataLoader(  entityName: keyof typeof DataLoadersCfg,  context: Record<string, any>,  info: GraphQLResolveInfo) {  if (!context.dataLoaders) context.dataLoaders = new WeakMap();  const { dataLoaders } = context;   // determine proper key in Context for DataLoader  const cfg = DataLoadersCfg[entityName];  let contextKey: any;  if (cfg.kind === DataLoaderKind.FieldNode) {    // available for only current fieldNode    contextKey = info.fieldNodes;  } else {    // available for all field levels    contextKey = cfg;  }   // get or create DataLoader in GraphQL context  let dl: DataLoader<any, any> = dataLoaders.get(contextKey);  if (!dl) {    dl = cfg.init(context, info);    dataLoaders.set(contextKey, dl);  }  return dl;} /** * Mapper config EntityID name to Dataloader creator */const DataLoadersCfg = {  // Global DataLoaders  ApprovalID: { init: approvalDLG, kind: DataLoaderKind.OperationGlobal } as DLCfg,  AttachmentID: { init: attachmentDLG, kind: DataLoaderKind.OperationGlobal } as DLCfg,  CommentID: { init: commentDLG, kind: DataLoaderKind.OperationGlobal } as DLCfg,  DependencyID: { init: dependencyDLG, kind: DataLoaderKind.OperationGlobal } as DLCfg,  CustomFieldID: { init: customFieldDLG, kind: DataLoaderKind.OperationGlobal } as DLCfg,  TimelogID: { init: timelogDLG, kind: DataLoaderKind.OperationGlobal } as DLCfg,  TimelogCategoryID: { init: timelogCategoryDLG, kind: DataLoaderKind.OperationGlobal } as DLCfg,  WorkScheduleID: { init: workScheduleDLG, kind: DataLoaderKind.OperationGlobal } as DLCfg,  // FieldNodes specific loaders  AccountID: { init: accountDL, kind: DataLoaderKind.FieldNode } as DLCfg,  ContactID: { init: contactDL, kind: DataLoaderKind.FieldNode } as DLCfg,  FolderID: { init: folderDL, kind: DataLoaderKind.FieldNode } as DLCfg,  TaskID: { init: taskDL, kind: DataLoaderKind.FieldNode } as DLCfg,}; /** * Example of one dataloader creator */export function contactDL(context: any, info: GraphQLResolveInfo) {  return new DataLoader<string, any>(async (ids) => {    const results = await contactFindByIds({ ids, info }, context);    return ids.map(      (id) => results.find((x) => x.id === id) ||      new Error(`Contact: no result for ${id}`)    );  });}

Смотрим schema/dataLoaders

Грубая оценка M6

• 13 файлов
• 291 LoC
• Рефакторинг M5 на M6
• ~ ⏱ 20 часов

FieldConfig > Resolver > Relations

GraphQL FieldConfig состоит из

type,
args,
resolve,
description,
deprecationReason,
extensions

Резолвер – это генератор, который создает FieldConfig

export function getRelationContactIds(  sourceFieldName: string): ObjectTypeComposerFieldConfigDefinition<any, any> {  return {    type: () => ContactTC.NonNull.List,    resolve: resolveManyViaDL('ContactID', (s) => s[sourceFieldName]),    projection: { [sourceFieldName]: 1 },  };}

В нашем случае мы создаём Резолверы для создания Relations между Entity.

Relations-резолверы позволяют избавиться от копипасты.

Т.е. из одного резолвера вы можете сгенерировать множество FieldConfigs для разных частей вашей схемы

А ещё ваши Relations могут содержать аргументы для фильтрации и сортировки

export function getRelationTasksBySpaceId(  sourceFieldName: string): ObjectTypeComposerFieldConfigDefinition<any, any> {  return {    type: () => TaskTC.NonNull.List,    args: {      filter: TaskFilterByRelation,      sort: TaskFindManySortEnum,      limit: 'Int',      pageSize: 'Int',    },    resolve: (source, args, context, info) => {      return taskFindMany(        {          info,          filter: {            ...args.filter,            spaceId: source[sourceFieldName],          },          limit: args.limit,          pageSize: args.pageSize,          ...args.sort,        },        context      );    },    projection: { [sourceFieldName]: 1 },  };}

Представьте, что этот код вам надо переиспользовать несколько раз в вашей схеме

Резолверы позволяют генерировать FieldConfigs ☝️

В демке wrike-graphql

• рефакторим M6, превращая 12 DataLoaders в Relations
• добавляем 26 новых "обратных" Relations

А ещё надо добавить "Обратные" Relations

"Обратные" Relations – это те, которые используют доступные фильтры из REST API.

Например, к entity Contact
можно добавить поля

• tasksAuthored
• tasksResponsible

Если знать, что существует endpoint GET /tasks,
который принимает два параметра
для фильтрации тасков – authors, responsibles.

Смотрим schema/relations

Грубая оценка M7

• 14 файлов
• 1142 LoC
• Рефакторинг M6 на M7
• Поиск и добавление обратных связей с фильтрацией
• ~ ⏱ 20 часов

110 relations VS 135 relations (38 nodes)

Особой разницы не видно.

НО огромная ценность в передачи знания клиентам об этих новых 25 связях между Entity.

Т.к. в большом REST API такие связи достаточно сложно найти.

110 relations VS 135 relations (38 nodes)

Что такое QueryCost?

QueryCost считает сложность запроса, который необходимо выполнить серверу.

Считает в попугаях. Ну, или чтобы было проще понять – максимально возможное кол-во полей.

Считает, исходя из

• полученного запроса от клиента
• переданных переменных с запросом
• и простой логики перемножения аргументов на вес полей или вес детей

Операция выполняется после парсинга запроса, НО до вызова резолверов.

Если сложность запроса больше какого-то числа

• возвращаем ошибку клиенту
• запрос не выполняем (не запускаем execute)

Прикручиваем к wrike-graphql

• Берём пакет graphql-query-complexity
• Создали плагин к аполло-серверу queryCostPlugin.ts
• И создаём функции complexity в полях нашей схемы (Complexity Estimators)

Добавляем функции complexity

• ко всем точкам входа в наш граф M4 (полям Query)
• по желанию, можно добавить к мутациям
• к релейшенам M7, которые возвращают списки

Находим "проблемы" в REST API Wrike

• плохо, что не везде есть лимиты на кол-во возвращаемых элементов

Например в Folders нет лимита. И чёрт его знает, сколько там может вернуться элементов, поэтому тяжело спрогнозировать сложность вложенного запроса.

Как workaround

• если нет аргументов limit или pageSize
• то ставим extensions: { complexity: ({ childComplexity }) => childComplexity * 10 }

Делаем допущение, что в списках в среднем возвращается 10 элементов.

Смотрим

• queryCostPlugin.ts
• schema/entrypoints/query/taskFindMany.ts
• schema/relations/task.ts

Грубая оценка M8

• написали 1 плагин
• добавили 55 complexity функций
• накостылили 29 workaround'ов (где нет лимитов)
• ~ ⏱ 10 часов

Всё до безобразия просто

• Пробрасываем http-заголовки (Authorizaition, Cookie) из ApolloServer в контекст GraphQL.
• Затем этот контекст пробрасываем в axios, чтоб он мог их использовать в своих подзапросах.

Боль и печаль – пришлось отредактировать больше 220 файлов.

Пробрасывайте сразу контекст до axios клиента!

1. На ApolloServer'е кладём headers в контекст

const apolloServer = new ApolloServer({  schema,  context: ({ req }) => {    ctx.headers = req?.headers;    return ctx;  },});

2. Во всех Entrypoints (M3) пробрасываем context

export default {  type: TaskTC.NonNull.List,  args: {    ids: TaskID.NonNull.List.NonNull,  },  resolve: (source, args, context, info) => {    return taskFindByIds({ ids: args.ids, info }, context);  },};

3. Во всех DataLoaders (M6) пробрасываем context

export function taskDL(context: any, info: GraphQLResolveInfo) {  return new DataLoader<string, any>(async (ids) => {    const results = await taskFindByIds({ ids, info }, context);    return ids.map(      (id) => results.find((x) => x.id === id) || new Error(`Task: no result for ${id}`)    );  });}

4. Во всех Relations (M7) пробрасываем context

export function getRelationTaskIds(sourceFieldName: string) {  return {    type: () => TaskTC.NonNull.List,    resolve: (source, _, context, info) => {      return taskFindByIds(        { ids: source[sourceFieldName], info },        context,      );    },  };}

Грубая оценка

• отредактировали 220 файлов
• ~ ⏱ 10 часов

REST API to GraphQL methodology

• M1: Создание обёртки к REST API 30 часов
• M2: Описание общих GraphQL-типов 10 часов
• M3: Описание Entity 10 часов
• M4: Описание точек входа в граф 40 часов
• M5: Расширение Entity прямыми связями по id 10 часов
• M6: Создание DataLoaders (N+1) 20 часов
• M7: Создание резолверов Реляций 20 часов
• M8: Прикручивание QueryCost 10 часов
• M9: Авторизация 10 часов

Грубая оценка всей GraphQL прокси

• 22 entity
• 87 REST API методов
• 160 часов
• 8773 строчек кода
• 275 файлов
• 134 GraphQL-типа
• 1002 поля и аргумента
• 77 реляций (LEFT JOIN)

Итого нужно 160 часов,
чтобы переварить 22 Еntity

В среднем, на 1 entity
уходит 1 человеко-день*

* не забудьте умножить на коэффициент
способности-и-производительности вашего человека-дня

ПЛЮС

пара недель - месяц,

чтобы разобраться c самим GraphQL
и с предложенной методологией.

Будьте аккуратны со сроками!

В начале будет больно!

Дальнейшие улучшения
для wrike-graphql

Тесты

• тесты для vendor
• тесты для GraphQL entry points
• тесты для relations

Трейсинг для QA (jaeger или elastic). Чтобы в респонсе в дев режиме ещё и ссылочка приходила на готовый трейс.

Решение проблем REST API и Data Domain

• Пагинация
  • её много где нет
  • есть limit, но нет offset
• Курсорная пагинация (вынести в отдельные точки входа и резолверы)
  • nextPageToken протухает через час-два (и опять запрашивать все данные сначала)
• Сортировка есть далеко не везде

Всяко-разно

• Вычисляемые поля, подключение внешних справочников, сторонних АПИ
• ApolloFederation, GraphQLMesh для соединения с другими GraphQL-сервисами (например, связать CustomFields с GitHub API)
• Реализация Subscription (трансформация Web-hooks в WebSocket), в основном, для браузеров.

Вопросы к Паше?