Недавно я имел удовольствие создать плагин Backstage для рендеринга GitHub Issues.
Вот небольшой обзор того, как это работает и чему я научился.
Первым делом — что! 🧐
*При всем уважении, но я предполагаю, что уважаемый читатель знает, что такое Backstage. Однако, если нет, вот ссылка на домашнюю страницу этого фантастического проекта https://backstage.io/.
Плагин, основанный на известной аннотации слагов GitHub, связанной с Сущностью, отображает список открытых проблем на GitHub. Он загружает данные из GitHub Graphql API; следовательно, требуется GitHub Authentication Provider.
Плагин предназначен для работы с четырьмя типами сущностей и ведет себя немного по-разному в зависимости от типа:
- Для Групп и Пользователей отображаются задачи из всех репозиториев, владельцем которых является Объект,
- Для API и Компонентов он отображает задачи только из одного репозитория, назначенного объекту.
Это плагин FE, который предоставляет компоненты React, адаптированные для Backstage, которые могут отображать адекватную карточку или страницу.
Приступим к делу — как! 🤓
Обзор архитектуры
Я думаю, можно с уверенностью сказать, что Backstage — это опыт разработчика, и процесс создания плагина не является исключением.
Плагин GitHub Issues был создан с помощью стандартного Backstage CLI cmd.
Из документации Backstage мы можем узнать, что:
Каждый плагин рассматривается как автономное веб-приложение и может включать практически любой тип контента.
Это важно, потому что представление о каждом плагине как об «автономном веб-приложении» дает разработчикам свободу в выборе того, как структурировать свой код. Организация файлов, которую я собираюсь описать, у меня работала хорошо, но она не единственно правильная.
С широкой точки зрения, плагин GitHub Issues делает две вещи: он извлекает данные из стороннего API, а затем отображает их. Разделение этих задач отражено в структуре кода.
В каталоге src есть три папки, каждая из которых имеет свою функцию:
- api/ — здесь инкапсулируется связь с GitHub API; эта папка содержит внутреннийAPI подключаемого модуля,
- components/ — неудивительно, что именно здесь живет логика рендеринга,
- hooks/ — это тот, который подключает React к внешнему миру, извлекает данные из API и считывает информацию об объекте рендеринга из Backstage.
Разделение миров API и React работает как хороший метод разделяй и властвуй. При создании и тестировании API нас интересуют только проблемы, связанные с эффективным запросом данных. При работе над частью рендеринга мы можем относиться к API как к черному ящику, интересуясь только контрактом, который он раскрывает. Мы можем издеваться и тестировать поведение компонента, а не детали реализации. Кроме того, эта простота имитации API пригодится при настройке локальной среды разработки при отдельном запуске плагина.
Как узнать свои проблемы 🤪
Снова Backstage потрясающий…
Он предоставляет хуки React, которые могут легко предоставить любую информацию о нужной вам сущности. С помощью useEntity мы можем получить доступ к метаданным Entity, которые отображают плагин. Метаданные содержат информацию о связанном репозитории.
В случае API или Component Entities этого достаточно. С группами и пользователями немного сложнее, потому что они могут владеть многими репозиториями GitHub. Мы используем другой хук — useApi, чтобы получить экземпляр catalogApi и найти все принадлежащие сущности с мощными метаданными.
Имея список репозиториев GitHub, следующим шагом будет проверка наличия в них открытых проблем.
GitHub Graphql API отлично подходит для этой задачи. Чтобы избежать состояния гонки при отправке слишком большого количества параллельных запросов для сущностей, владеющих несколькими репозиториями, мы можем воспользоваться фрагментом GraphQL и объединить наш запрос в один запрос.
Я решил реализовать эту оптимизацию с самого начала, потому что на момент создания плагина моей команде принадлежало более 100 репозиториев. Однако после включения плагина в производство я узнал, что некоторые из них были заархивированы и, хотя они все еще доступны в Backstage, запрос их данных приводил к ошибкам GraphQL. К счастью, мы можем легко оправиться от этого рассола — используйте успешно возвращенные данные и, что еще лучше, воспользуйтесь преимуществами Backstage errorApi, чтобы уведомить пользователя о проблеме.
gitHubIssuesApi не используется нигде, кроме плагина GHI, поэтому все его типы и сам API — internal. Кое-что, о чем стоит помнить, так как было заманчиво сделать это общедоступным, учитывая тот факт, что хук React импортирует его в другой модуль. Во время запроса на слияние меня осторожно подтолкнули в правильном направлении.
Сделаем красиво! 🤩
Последнее, что нужно сделать, это отобразить данные для пользователя. Эта задача выполняется с помощью стандартного современного React. Я предлагаю уважаемому читателю поковыряться в моем коде, если они того пожелают. Однако разработка React не является основной темой этой статьи. Я хотел бы отметить, что Backstage также предоставляет библиотеку стандартных компонентов, которые очень помогают. Вот сборник рассказов.
Они основаны на пользовательском интерфейсе материалов и позволяют нам оставаться в соответствии со стандартами дизайна пользовательского интерфейса проекта и темами поддержки. Тем не менее, чистый материальный пользовательский интерфейс поддерживается, если вам нужно создавать собственные компоненты, и отлично работает с остальной частью экосистемы Backstage FE.
Дело не только в коде. Все дело в людях! 👯♀️
Команда Backstage отличная. С ними легко связаться в Discord, и они очень помогают во время PR-обзора.
Сообщество вокруг проекта имеет свежую и вдохновляющую энергию; каждый месяц проводится сессия сообщества.
Я имел удовольствие представить плагин на одной из таких сессий, и вот запись презентации.
Представляй и оставайся в полете! Аииии!
