График Язык схемы отлично! Это, безусловно, лучший способ сообщить о сервисе GraphQL. Неудивительно, что все документы теперь используют ее!
Язык схемы
Представьте, что вы строите приложение для блога (с GraphQL), имеющим «статьи» и «комментарии». Вы можете начать думать о своей схеме API, основываясь на том, что вы планируете для своего пользовательского интерфейса. Например, главная страница, вероятно, будет иметь список статей и элемент в этом списке может отображать заголовок, субтитров, имя автора, дату публикации, длину (в чтении минут), а также изображение. Упрощенная версия самой среды, если вы можете:
Мы можем использовать язык схемы для планирования того, что вам нужно до сих пор для этой главной страницы. Базовая схема может выглядеть как:
type Query {
articleList: [Article!]!
}
type Article {
id: ID!
title: String!
subTitle: String
featuredImageUrl: String
readingMinutes: Int!
publishedAt: String!
author: Author!
}
type Author {
name: String!
}
Когда пользователь навигается к статье, они увидят детали этой статьи. Нам понадобится API для поддержки способа извлечения объекта статьи по его идентификатору. Скажем, статья также может иметь богатые элементы пользовательского интерфейса, такие как заголовки и кодовые фрагменты. Нам нужно будет поддерживать язык форматирования форматирования насыщенного текста, такими как rackdown. Мы можем заставить API вернуть контент статьи в Markdown или HTML через полевой аргумент ( Формат : HTML). Давайте также планируем отображать счетчик «любит» в этом представлении.
Поместите все эти идеи на бумагу! Язык схемы является наиболее лаконичным структурированным способом, чтобы описать их:
type Query {
# ...
article(id: String!): Article!
}
enum ContentFormat {
HTML
MARKDOWN
}
type Article {
# ...
content(format: ContentFormat): String!
likes: Int!
}
Вид UI в одной статье также отобразит список комментариев, имеющихся в статье. Давайте удержим просмотр комментариев просмотра просмотра и планируйте его, чтобы иметь текстовый контент и поля имени автора:
type Article {
# ...
commentList: [Comment!]!
}
type Comment {
id: ID!
content: String!
author: Author!
}
Давайте сосредоточимся на этих функциях. Это хорошая отправная точка, которая нетривиальна. Чтобы предложить эти возможности, нам нужно будет реализовать пользовательскую решающую логику для вычисленных полей, таких как Содержание (формат: HTML) и чтение для чтения Отказ Нам также нужно будет реализовать 1-1 и 1-много отношения БД.
Вы заметили, как я придумал все описание схемы, просто думая с точки зрения UI. Как это круто? Вы можете дать этот простой текст языка схемы в интерфейсные разработчики в вашей команде, и они могут начать строить аппаратное приложение! Им не нужно ждать реализации вашего сервера. Они могут даже использовать некоторые из великолепных инструментов, чтобы иметь сервер Mock GraphQL, который разрешает эти типы со случайными тестовыми данными.
Создание схемы GraphQL
Когда вы готовы начать реализацию вашего сервиса GraphQL, у вас есть 2 основных варианта (в JavaScript) сегодня:
- Вы можете «построить» неизарезуемую схему, использующую полный текст языка схемы, который мы имеем, а затем прикрепите набор функций Resolver, чтобы сделать этот исполняемый файл схемы. Вы можете сделать это с Graphql.js сам или с Apollo Server Отказ Оба поддерживают этот метод, который обычно известен как «схема-первая» или «SDL-первая». Я ссылаюсь на это здесь как « Full-Schema-String Method |». Вы можете использовать объекты JavaScript, созданные от различных классов конструктора, которые доступны в API graphql.js (например
- graphqlschema
,graphqlobjecttype,graphqluniontypeи многие другие). В этом подходе вы не используете текст языка схемы вообще. Вы просто создаете объекты. Этот метод обычно известен как «Код-Первый» или «Резольверы - сначала», но я не думаю, что эти имена справедливо представляют это. Я буду ссылаться на это здесь, как «| Объектный метод ».
Оба подхода имеют преимущества и недостатки.
Язык схемы – это отличный язык программирования-языка – агностический способ описания схемы GraphQL. Это читаемый человеком формат, с которым легко работать. Народные люди в вашей команде будут абсолютно любить это. Это позволяет им участвовать в дизайне API и, что более важно, начните использовать издевательную версию сразу. Текст языка схемы может служить ранней версией документации API.
Тем не менее, полностью полагаясь на полноценный язык схемы для создания схемы GraphQL, имеет несколько недостатков. Вам придется приложить некоторые усилия, чтобы сделать код модуляризованным и прозрачным, и вы должны полагаться на узоры и инструменты кодирования, чтобы сохранить текст языка схемы, в соответствии с деревом резольвентов (карта AKA Resolvers). Это разрешимые проблемы.
Самая большая проблема, которую я вижу с методом полной схемы-строки, заключается в том, что вы теряете гибкость в вашем коде. У вас нет объектов, связанных с типами. У вас просто есть строки! И хотя эти строки делают ваши типы более читаемыми, во многих случаях вам понадобится гибкость над читаемостью.
Способ на основе объектов является гибким и проще продлится и управлять. Это не страдает от каких-либо из упомянутых проблем. Вы есть быть модульным с этим, потому что ваша схема – это куча объектов. Вам также не нужно объединять модули вместе, потому что эти объекты разработаны и должны работать как дерево.
Единственная проблема, которую я вижу с методом на объект, заключается в том, что вы должны иметь дело с большим количеством кода вокруг того, что важно управлять в ваших модулях (типов и резольверов). Многие разработчики считают, что «шум», и вы не можете их винить. Мы будем работать через пример, чтобы увидеть это.
Если вы создаете небольшой объем и четко определенный сервис GraphQL, используя метод полной схемы-строки, вероятно, в порядке. Однако в более крупных и более гибких проектах я думаю, что более гибкий и более мощный объектный метод – это путь.
Для сравнения 2 метода я реализовал исполняемую схему для пример блога, который мы начали с использованием обоих них. Я пропустил какой-то код для краткости, но сохранил, что имеет значение для сравнения.
Метод полной схемы-строки
Начнем с текста языка схемы, который определяет 3 основных пользовательских типа ( Статья , Комментарий и Автор ). Поля под главным Запрос Тип есть Статья и Articlelist который будет напрямую разрешать объекты из базы данных. Однако, поскольку схема GraphQL, мы планировали, имеет пользовательские функции вокруг объекта статьи, и поскольку у нас есть отношения, которые нам нужно решить, нам понадобится пользовательские резользеры для 3 основных типов Custom GraphQL.
Вот несколько скриншотов для кода, который я написал, чтобы представлять метод полной схемы. Я использовал сервер APOLLO здесь, но это также возможно с Vanilla Graphql.js (и немного более Code).
Это мило! Мы можем увидеть типы в схеме в одном месте. Понятно, где начинается схема. Мы можем модулировать код по типу/функции.
Это снова действительно здорово! Резольверы являются совместно с типовыми, которые они реализуются. Там нет шума. Этот файл прекрасно содержит, что имеет значение в очень читаемом формате. Я люблю это!
Так что же самое нисходящее здесь?
Если вы используете этот метод, то все ваши типы должны быть записаны в этом определенном способе, который опирается на текст языка схемы. У вас меньше гибкости. Вы не можете использовать конструкторов для создания некоторые Типы, когда вам нужно. Вы заблокированы к этому строковым подходу.
Если вы в порядке с этим, то игнорируйте остальную часть этой статьи. Просто используйте этот метод. Это намного чище, чем альтернатива.
Объектный метод
Давайте теперь посмотрим на объектный подход. Вот отправная точка исполняемой схемы, построенной с использованием этого метода:
Нам не нужно отдельный Резольверы объект. Резольверы являются частью самого объекта схемы. Это облегчает их поддерживать. Этот код также легче программно расширить и анализировать!
Это также намного больше кода, который труднее читать и причинять! Подождите, пока не увидите остальную часть кода. Я не мог взять Статья Введите скриншот на экране ноутбука. Я должен был использовать более крупный экран.
Неудивительно, что метод полной схемы – популярен! Конечно, есть много «шума», чтобы иметь дело с здесь. Типы не ясны на первый взгляд. Пользовательские резольверы смешиваются в одном большом объекте конфигурации.
Моя любимая часть – это когда вам нужно создать ненутренний список ненужных элементов, таких как [Статья!]! Отказ Вы видели, что я должен был написать?
Новый graphqlnonnull (новый graphqllist (новый graphqlnonnull))),
Однако, хотя это действительно гораздо больше кода, который сложнее понять, он все еще лучший вариант, чем иметь одну большую строку (или несколько струн, объединенных в один), и один большой объект root Resolvers (или несколько объектов резольверов в одном). Лучше, чем иметь все зависимости вашего приложения, управляемого в одной единственной точке входа.
В модуляризации вашего кода есть много мощности, используя объекты (которые могут зависеть друг от друга). Это очиститель таким образом, и он также облегчает писать тесты и проверки. Вы получаете более полезные сообщения об ошибках при отладке проблем. Современные редакторы могут обеспечить более полезные советы в целом. Самое главное, у вас есть гораздо больше гибкости, чтобы сделать что-либо с этими объектами. Сама конструкторов Graphql.js также использует объекты JavaScript. Есть так много, что вы можете сделать с ними.
Но шум тоже реальна.
Объектный метод без шума
Я придерживаюсь методом на основе объекта, но я уверен, что для реализации JavaScript GraphQL есть лучший API, который может дать нам некоторую мощность метода полносхемы.
Было бы неплохо, если мы сможем написать Статья Введите логику точно так, как мы сделали в методе полносхемы, но таким образом, чтобы генерировать гибкий Graphqlobjecttype что мы можем подключить к объектному схеме?
Что-то типа:
Разве это не будет идеальным? Мы получаем преимущества метода полной схемы для этого типа, но без блокировки! Другие типы в системе могут быть сохранены по-разному. Возможно, другие типы будут динамически построены с использованием другой логики производителя!
Все, что нам нужно, чтобы это произошло волшебное типемакерметод принимать части, которые имеют значение и преобразуйте их в полную Graphqlobjecttype для Статья Отказ
типемакерметод нужно будет разбирать строку в AST, используйте это, чтобы построить Graphqlobjecttype Затем объединить набор пользовательских функций Resolver с Поля Конфигурация, которая будет проанализирована из Typedef нить.
Мне нравится вызов, поэтому я немного глубже, чтобы увидеть, как трудно было бы реализовать типемакерметод Отказ Я знал, что не могу использовать graphql.buildschema Функция, потому что она только анализирует одну полную строку схемы, чтобы сделать неисполняемый объект схемы. Мне нужна нужна часть нижней уровне, которая анализирует строку, которая имеет ровно один тип, а затем прикрепляет к нему пользовательские резольверы. Поэтому я начал читать исходный код graphql.js, чтобы искать подсказки. Несколько чашек кофе спустя, я нашел ответы (в 2 местах):
Это основной метод, используемый в buildschema Чтобы построить один тип из узла определения типа (который мы можем легко получить, разбросая Typedef String).
И:
Вот как легко продлить тип объекта и прикрепить любую логику, необходимую в Поля и интерфейсы !
Все, что мне нужно было сделать, это поставить несколько штук вместе, и мечта может быть правдой.
я сделал .
Дамы и господа. Я представляю вам волшебный «типемакерерметод» (который я назвал ObjectType ):
Вот и все (в своей основной форме)! Это займет Typedef Строка, которая определяет один тип GraphQL, объект резольверов и карта зависимостей (для этого типа), и она вернет Graphqlobjecttype Готов к подключению к вашей объектной схеме, как если бы она была определена нормально с конструктором объекта.
Теперь вы можете использовать метод на основе объектов, но у вас есть возможность определить некоторые типы, используя подход, аналогичный методу полнох схемы. У вас есть сила.
Что вы думаете об этом подходе? Я хотел бы услышать ваши отзывы!
Первоначально опубликовано в https://jscomplete.com 9 июня 2019 года.