Предотвратить критические изменения. Найдите сломанные операции. Получите покрытие схемы. Проверьте устаревшее использование и введите дубликаты. Все как часть вашего процесса CI
За почти три года работы с GraphQL я и Гильдия представили решения, которые изменили то, как мы пишем наши проекты сегодня.
Чтобы использовать GraphQL в наших приложениях Angular, мы создали Angular Apollo. Для автоматизации и повышения безопасности типов мы открыли исходный код Генератор кода GraphQL. Самым последним из них были Модули GraphQL, которые помогли нам разделить сервер на более мелкие, многоразовые, функциональные части. Все это было разработано на основе опыта и с огромным успехом использовалось нашими клиентами.
Сегодня я рад представить еще одну часть нашего технологического стека, которую мы называем
Инспектор GraphQL!
Инспектор GraphQL - это инструмент, основная цель которого - убедиться, что ваш GraphQL API и все его клиенты хорошо разработаны.
Ключевая особенность
- Находит критические, опасные и безопасные изменения при изменении GraphQL API
- Приложение Github + действие Github (скоро интеграция с Bitbucket)
- Интерфейс командной строки
- Полностью бесплатный и с открытым исходным кодом - разместите свой собственный GraphQL Inspector
- Покрытие схемы - просмотр неиспользуемых частей схемы на основе всех фрагментов и операций ваших клиентов.
- Проверяет операции по схеме GraphQL - вы замечаете ошибки еще до выполнения!
- Находит повторяющиеся или похожие типы
Используйте это в Github
Мы предлагаем GraphQL Inspector как приложение Github, которое вы можете установить в любом из ваших репозиториев одним щелчком мыши. Это самый простой способ начать использовать Inspector.
Инспектор как часть вашего рабочего процесса
Чтобы использовать GraphQL Inspector, вам необходимо убедиться, что вы записали всю схему GraphQL в файл, чтобы Inspector мог ее увидеть. Здесь хорошо подходят хуки Git. Всякий раз, когда появляется новая фиксация, файл будет обновлен.
Затем вы настраиваете GraphQL Inspector в package.json:
Подробнее об этом можно прочитать в главе Приложение Github на нашем сайте.
Теперь, когда кто-то отправляет Pull Request, GraphQL Inspector будет сравнивать схемы и отказывать, если есть критические изменения.
Действия Github
Я знаю, что действия Github еще не являются общедоступными, но если вам повезет, вы можете использовать их для размещения своего собственного GraphQL Inspector, который развертывается и работает при каждой фиксации или запросе на перенос. Поскольку действие временно выполняется с помощью Docker, вы не будете использовать какие-либо облачные службы или другие платные ресурсы.
На данный момент Actions - не самая приятная вещь, но, поскольку она бесплатна и очень проста в настройке, мы настоятельно рекомендуем воспользоваться ею, если вы не хотите использовать размещенный у нас GraphQL Inspector.
Мы не храним никаких данных, код имеет открытый исходный код и развертывается с помощью Netlify Functions.
Поскольку мы твердо верим в открытый исходный код, вы также можете установить и запустить собственный экземпляр GraphQL Inspector.
Интеграция с Bitbucket
GraphQL Inspector пока не поддерживает Bitbucket, но он стоит на первом месте в нашей дорожной карте, и мы начинаем над этим работать. Если вам это нужно, напишите или прокомментируйте открытый вопрос.
Предотвращение критических изменений
Инспектор GraphQL сравнивает старую и новую схему GraphQL, чтобы предупредить вас о критических изменениях. Он также отслеживает другие изменения, опасные для реализации и полностью безопасные.
Таким образом, у вас будет четкое представление о том, как разрабатывается ваша схема.
Покрытие схемы
Идея заключается в том, чтобы увидеть, какая часть вашей схемы используется, сколько раз и какой операцией. Это применимо только к документам, которые можно анализировать статически.
Inspector может извлекать каждый фрагмент или операцию из файлов TypeScript и JavaScript. Он поддерживает любой тип буквального тега шаблона, а также .graphql файлы.
Подтвердите документы и найдите устаревшие варианты использования
Чтобы узнать, что ваша операция или фрагмент не работают, вам нужно запустить приложение и выполнить запрос или мутацию. Благодаря GraphQL Inspector вы можете легко проверить наличие ошибок или устаревшего использования в любой момент.
Я рекомендую сделать это как часть вашего CI или даже git-хуков.
Найдите дубликаты
Еще одна интересная особенность Inspector позволяет находить похожие типы и, возможно, даже дубликаты. Это не то, что все могут захотеть использовать, но мы сочли это действительно полезным, когда мы переносили несколько отдельных API GraphQL в монорепозиторий и объединяли их на одном сервере в Air France - KLM. Больше об этом мог бы сказать Март Ганзевлес, отец этой особой функции, и это был его первый проект с открытым исходным кодом. Потрясающая работа Mart!
Настольное приложение
Мы собираемся работать над настольной версией GraphQL Inspector, чтобы еще больше улучшить весь опыт. Представьте, что вы исследуете все в хорошо сделанном и интерактивном приложении. Вы можете нажимать на вещи, чтобы увидеть их в деталях, просто потрясающе!
Другие особенности
- Запускает сервер GraphQL с поддельными данными с помощью одной команды
- Записывает результат интроспекции схемы GraphQL в файл
Как он сравнивается с другими инструментами
Apollo Engine
GraphQL Inspector пытается решить немного другой вариант использования. Основная идея Apollo Engine - получить представление о том, как сервер GraphQL ведет себя в производственной среде.
Он также поддерживает сравнение схем, но главное отличие состоит в том, что мы не храним ваши данные, а для отслеживания изменений мы просто используем Git. Каждое изменение доступно в истории git, поэтому рабочий процесс прост и вам уже знаком.
Поэтому преимущество Apollo в том, что он учитывает производственные данные, а не только ваш код. Но если это важно для вас, вы можете собрать эти данные со своих серверов GraphQL сегодня, хранить их где угодно, и мы можем добавить функцию для добавления этих данных в один из наших отчетов.
GraphQL Doctor
GraphQL Doctor и наш инструмент имеют общую только функцию сравнения схем, но Inspector отслеживает также изменения, которые можно безопасно вносить. Основная цель Doctor - работать внутри Github и не допустить взлома API. Мы хотели бы сотрудничать с ними, убедиться, что мы действительно охватили все их варианты использования и, возможно, объединим их библиотеку с нашей.
Сообщество с открытым исходным кодом
В Гильдии мы любим open-source, благодаря этому возможна вся наша карьера. Мы также узнали друг друга через Open-Source :)
Вот почему я призываю вас помочь нам разработать GraphQL Inspector, и давайте создадим его вместе.
Небольшой фрагмент кода, исправление ошибки, улучшение документации или даже простейшее предложение считается вкладом!
Ссылки
- Сайт и документация
- Посетите репозиторий на Github
- Доступен интерфейс командной строки -
$ yarn global add @graphql-inspector/cli - Оформить заказ Приложение Github
- См. Пример приложения, использующего GraphQL Inspector.
Подпишитесь на нас в GitHub и Medium, мы планируем опубликовать еще много сообщений в ближайшие пару недель о том, что мы узнали с помощью GraphQL в последние годы.
