Команда Stream любит создавать примеры приложений с открытым исходным кодом, чтобы продемонстрировать функциональность нашего API. Мы всегда считали, что лучше продемонстрировать возможности наших предложений на полностью функциональной платформе. В данном случае использование Stream и других отличных сервисов позволило нам создать подкаст и RSS-ридер Winds за месяцы, а не годы. Кроме того, как проект с открытым исходным кодом Winds продолжает улучшаться благодаря вкладу растущей пользовательской базы (сейчас более 14 000 пользователей и ~ 5 500 звезд!).

В этом посте мы расскажем вам, как создается Winds - самый популярный образец приложения Stream с открытым исходным кодом. Если вы не знакомы с Winds, вы можете прочитать об этом здесь. Мы начнем с подробного пошагового руководства по добавлению функции, которая требует, чтобы мы коснулись нескольких аспектов внешнего и внутреннего интерфейса приложения.

К концу этой публикации вы будете готовы добавить свои собственные функции в Winds и внести свой вклад в сообщество разработчиков ПО с открытым исходным кодом! Независимо от того, являетесь ли вы новым программистом или ветераном, мы уверены, что вы узнаете что-то новое. 😀

Обратите внимание, что в этом руководстве предполагается следующее:

  1. Вы используете macOS или понимаете, как установить различные необходимые зависимости в выбранной вами ОС. 🎁
  2. Вы понимаете JavaScript 🤔
  3. У вас есть базовое понимание React (ничего страшного, если нет, но это помогает) 💻
  4. У вас есть понимание git (мы не будем углубляться, но требуются общие знания). 🔦
  5. Вы в восторге от того, что научились программировать в соответствии с кодовой базой Winds! 💥

Приступим!

Системные зависимости 🧙‍

Как вы, возможно, знаете, для каждого приложения требуются общесистемные зависимости. Чтобы не сбиться с пути, давайте рассмотрим установку только для macOS.

1. Домашнее пиво

Для тех из вас, кто плохо знаком с кодированием, Homebrew - замечательный инструмент для управления установками системных зависимостей. С помощью одной команды вы можете установить язык кодирования по вашему выбору или использовать функции Homebrew Cask для установки полноценных приложений на свой компьютер. Если у вас не установлен Homebrew, вы можете установить его с помощью следующей команды:

Как только у вас получится все необходимое для Homebrew, мы можем перейти к следующему шагу ...

2. Node.js

Node.js широко используется в этом проекте - в основном для API и набора тестов. С учетом сказанного, давайте убедимся, что у вас установлена ​​последняя версия node. На момент написания этой статьи Node.js находится на версии v10.7.0 (и часто меняется).

Если у вас установлен Node.js, вы можете проверить версию своего узла с помощью следующей команды:

Примечание. Предположим, вы используете последнюю версию узла.

Если у вас не установлен Node.js, вы можете сделать это одним из следующих способов:

а) Домашнее пиво

OR

б) NVM (рекомендуется)

NVM или Node Version Manager - популярный инструмент с открытым исходным кодом. Он позволяет переключаться между версиями Node.js с помощью короткой команды. Все документировано здесь. Установить так же просто, как выполнить следующие действия:

Шаг 1:

Установите NVM:

Шаг 2:

Установите последнюю версию Node.js:

Совет для профессионалов: вы можете запустить команду nvm ls-remote, и она отобразит все версии, включая новые версии, в вашей консоли.

Теперь, если вы запустите узел - версия, вы должны увидеть последнюю установленную версию.

3. MongoDB

MongoDB - это наше основное хранилище данных о пользователях, RSS, подкастах и ​​многом другом. Мы используем MongoDB Atlas, размещенную версию MongoDB, созданную и поддерживаемую MongoDB.

Примечание. Команда для запуска MongoDB: brew services start MongoDB.

4. Redis

Redis важен, поскольку он служит нашей очередью заданий для обработки RSS и подкастов. Мы также используем Redis для базового кэширования элементов, которые не обновляются (например, интересов).

Примечание. Команда для запуска Redis - это просто redis-server. Полный список команд можно найти здесь.

5. Пряжа

Пряжа - это замена npm (диспетчер пакетов узлов). Мы рекомендуем yarn вместо npm, поскольку мы нашли его более надежным и в целом лучшим менеджером пакетов для зависимостей Node.js.

Глобальные зависимости пряжи 🌎

Есть одна зависимость Node.js, которая должна быть локальной, и для этого мы будем использовать Yarn. Зависимость - это PM2, менеджер процессов, о котором мы поговорим чуть позже. А пока выполните следующую команду для установки PM2:

Клонировать репо 💾

Теперь у вас установлены все необходимые зависимости, так что давайте продолжим и клонируем репозиторий. Вы можете получить URL-адрес из GitHub или использовать команду ниже (просто убедитесь, что вы клонируете в каталог, который вам подходит (например, ~ / Code)).

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

Настройка сторонних сервисов 👨‍👨‍👧‍👦

Winds использует для работы несколько сторонних ресурсов. Все внешние службы будут иметь ключи / секреты API и другие значения, которые вам нужно будет сохранить для дальнейшего использования в этой публикации - я рекомендую использовать приложение Notes в macOS. В общей сложности на выполнение потребуется около 15–20 минут.

›Примечание. Все услуги, необходимые для работы Winds, бесплатны до определенного уровня (обычно это производственные числа), поэтому на данный момент не нужно беспокоиться о плате. Ни одна из рекомендуемых нами услуг не требует кредитной карты.

1. Mercury Web Parser (~ 2 минуты)

Mercury Web Parser от Postlight играет большую роль в Winds. Это гарантирует, что все статьи RSS, которые мы анализируем, лишены тегов сценариев и другого беспорядочного кода, который вводится в HTML перед рендерингом.

Чтобы подписаться на Mercury, перейдите на домашнюю страницу и нажмите Зарегистрироваться. Как только вы это сделаете, возьмите предоставленный ключ API и сохраните его в специальном месте.

Шаг 1:

Чтобы зарегистрироваться в Mercury, перейдите на домашнюю страницу и нажмите Зарегистрироваться. Как только вы это сделаете, возьмите предоставленный ключ API и сохраните его в специальном месте.

Шаг 2:

Сохраните сгенерированный ключ API.

2. Трансляция (~ 5 минут)

Stream поддерживает каналы в приложении вместе с предложениями персонализированного контента.

Шаг 1:

Перейдите на сайт Stream и нажмите кнопку Зарегистрироваться.

Шаг 2:

Щелкните «Просмотр панели мониторинга», как показано на скриншоте ниже. Или сначала поиграйте с API. 😀

Шаг 3:

Нажмите «Создать приложение» и введите данные. Обратите внимание, что имя приложения должно быть глобально уникальным - я рекомендую поставить перед ним свое имя, так как это будет тестовый проект.

Шаг 4:

Затем нам нужно настроить наши Группы каналов в Stream. Необходимые группы каналов находятся на GitHub.

  1. подкаст (плоский)
  2. rss (плоский)
  3. пользователь (плоский)
  4. временная шкала (плоская)
  5. user_episode (плоский)
  6. user_article (плоский)

Шаг 5:

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

Вы также захотите получить свой идентификатор приложения, который находится вверху страницы, и сохранить значение.

Вот и все для Stream!

3. Алголия (~ 10 минут)

Силы Алголии ищут Ветры. Это важнейшая технология для приложения, которая играет важную роль в удобстве работы пользователей.

Шаг 1:

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

Шаг 2:

Затем заполните информацию, требуемую Algolia.

Шаг 3:

Выберите свой дата-центр. Для целей данного руководства это не имеет значения; тем не менее, я собираюсь выбрать ближайшую ко мне, а именно Центральную часть США.

Шаг 4:

Выберите «Другое» в качестве типа создаваемого приложения и «Как можно скорее» в раскрывающемся списке. Затем нажмите «Готово», чтобы подвести итоги.

Шаг 5:

Следующим шагом в этом процессе является создание индекса, в котором будут размещаться все доступные для поиска данные Winds. Чтобы обойти процесс регистрации, перейдите прямо на панель управления по этой ссылке. Затем нажмите кнопку Индексы в левом столбце. После загрузки страницы нажмите кнопку Добавить новый индекс, чтобы сгенерировать индекс. Назовите это как хотите, но убедитесь, что вы можете записать имя своего индекса. Я назову свой dev_Winds.

Шаг 6:

Последний шаг в процессе - получение «имени приложения», «ключа API только для поиска» и «ключа API администратора». И то, и другое можно найти в разделе «Ключи API» в правой части страницы в разделе «Ключи API». Держите эти учетные данные под рукой для дальнейшего использования в процессе установки.

4. Сторожевой (~ 2 минуты)

Sentry - еще один из самых важных инструментов в нашем наборе инструментов. Sentry фиксирует ошибки, возникающие в API серверной части, что позволяет нам сразу приступить к исправлению ошибок, прежде чем пользователи даже об этом узнают.

Шаг 1:

Создать новую учетную запись здесь".

Шаг 2:

Дайте вашему проекту имя. Я называю свой «Winds», потому что мы работаем над проектом Winds. 😀

Нажмите «Создать проект», и вы будете перенаправлены.

Шаг 3:

Получите свой DSN, щелкнув ссылку в разделе «Уже настроили? Получите свой DSN ».

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

Клонирование репо 📀

Чтобы приступить к следующим шагам, вам нужно клонировать репозиторий из GitHub. Для этого вы можете использовать следующую команду:

Большой! Теперь, когда вы клонировали репо, давайте продолжим и установим необходимые зависимости с помощью yarn.

API ветров

Вам нужно перейти в каталог / api и выполнить команду yarn. Вот небольшой фрагмент, который вам поможет:

Приложение Winds

Предполагая, что вы находитесь в каталоге / api, вы можете перейти в каталог / app, чтобы выполнить установку пряжи.

Примечание. API и приложение имеют отдельные файлы package.json. Хотя это может сбивать с толку, это необходимо, чтобы мы не раздували каждый каталог - даже если они находятся в одном репозитории, каталоги развертываются как отдельные приложения.

Сборка

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

Winds Frontend

Передняя часть Winds довольно проста. Мы использовали Create React App (CRA) для начальной загрузки приложения, а затем запуска процесса разработки. Код внешнего интерфейса можно найти здесь: https://github.com/GetStream/Winds/tree/master/app

Бэкэнд Winds

Внутренний API немного сложнее внешнего интерфейса. Помимо работы на Node.js, серверная часть обрабатывает почти всю бизнес-логику - взаимодействие со сторонними службами, оркестровку рабочих для синтаксического анализа RSS, подкастов, данных Open Graph и т. Д. Бэкэнд можно просмотреть здесь: https : //github.com/GetStream/Winds/tree/master/api .

Стандарты ES6

Практически весь код, который мы используем, написан на ES6. Это позволяет нам сохранять компактность, сохраняя при этом читаемый код.

API-маршруты

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

Примечание. Маршрут заключен в функцию wrapAsync (). Эта функция фиксирует все возникающие ошибки и отправляет их в Sentry.

Контроллеры API

Контроллеры вызываются файлами маршрутов и содержат большую часть, если не всю бизнес-логику в API. Контроллеры взаимодействуют с моделями, что позволяет им общаться с базой данных.

Модели API

По сути, модели - это основная основа API. Они обеспечивают структуру внутреннего хранилища данных (MongoDB), применяя так называемые «схемы». Схемы содержат различные типы, такие как «String», «Boolean» и т. Д. Вот краткий пример нашей пользовательской схемы (я удалил некоторые вспомогательные функции, чтобы сократить пример, поэтому обязательно посмотрите код, чтобы увидеть их) :

Полный список типов схем можно найти на веб-сайте Mongoose.

Работники API

Рабочие выполняют особые задачи, которые иначе заблокировали бы процессы. Например, мы используем специальные задачи для обработки RSS-каналов, подкастов, изображений Open Graph и многого другого. Без выделенных процессов для этих задач наш API быстро остановился бы, и пользователи не могли бы своевременно получать ответное сообщение - API, скорее всего, истекло бы по таймауту.

Наши сотрудники используют Bull Queue, инфраструктуру очередей для Redis. По сути, наш API вставляет вызов Redis с помощью библиотеки Bull Node.js, а затем наши рабочие берут задание и обрабатывают его асинхронно.

Например, вот код из Контроллера Podcast.js, который добавляет подкаст после того, как пользователь добавляет его в систему (обратите внимание, как мы добавляем высокий приоритет 1):

Отсюда происходит следующее:

  1. Дирижер подхватывает задачу, которую нужно обработать.
  2. Файл podcast.js получает уведомление о том, что у него есть задание (обработать входящее задание).
  3. База данных заполнена заполненными эпизодами
  4. Пользователь уведомляется о доступности новых подкастов.

Команды интерфейса командной строки

Каталог команд содержит код для конкретных задач, связанных с Winds - это простой, но мощный интерфейс командной строки для API Winds - и он особенно полезен, когда вам нужно отлаживать RSS-каналы. Если вам интересно, начало работы и все команды перечислены здесь.

Пример вывода при запуске winds rss« https://techcrunch.com/feed/ :»

API тесты

Тесты написаны с использованием Mocha и Chai. Вы можете запустить набор тестов в любое время (никогда не помешает найти что-то, что нужно исправить). В настоящее время охват имеют только Workers и API - и мы все еще работаем над достижением 100% отметки; тем не менее, скоро появится интерфейс с шутками!

Ветры ENV 🌪️

Есть два места, где для запуска приложения требуется файл .env (dotenv): /app/.env, а также / api / tests (при условии, что вы буду писать тесты). Чтобы приложение работало, вам нужно создать файл .env внутри / app.

Вот шаблонный файл .env, который поможет вам начать работу:

Примечание. Существуют встроенные примечания, которые помогут вам настроить файл .env.

Запуск PM2 🏃

PM2 - это диспетчер процессов, и мы широко используем его для Winds. Это чрезвычайно мощный инструмент, и мы большие поклонники этого проекта, а также его сопровождающие. Они быстро реагируют, если возникает ошибка, и, что наиболее важно, она очень работает для того, что нам нужно делать.

Node.js спроектирован как однопоточный. У этого есть свои плюсы и минусы - это очень быстро, но привязано к одной операции ввода-вывода в данный момент. Под капотом PM2 использует модуль кластера Node.js, чтобы дочерние процессы масштабируемого приложения могли автоматически совместно использовать порты сервера. Кластерный режим позволяет масштабировать сетевые приложения Node.js на всех доступных ЦП без каких-либо изменений кода. Это значительно увеличивает производительность и надежность используемого приложения в зависимости от количества доступных процессоров.

Я бы порекомендовал изучить команды для PM2, если вы собираетесь разрабатывать на Winds или если вы планируете использовать PM2 для своего собственного приложения. Честно говоря, лучшая функция - это встроенная команда watch - она ​​автоматически отслеживает изменения и при необходимости перезагружает приложение. Вот несколько команд, которые я использую ежедневно:

  1. pm2 start process_dev.json ( запускает процессы с помощью команд, заданных в файле process_dev.json)
  2. pm2 list ( список всех запущенных процессов)
  3. pm2 перезапустить все ( перезапускает все запущенные процессы, управляемые pm2)
  4. pm2 log ( отслеживает журналы, которые выдаются различными процессами)

Примечание: используйте ctrl + c, чтобы выйти из журналов отслеживания.

Приступим

Вы зашли так далеко. Поздравляю! Все зависимости установлены, репозиторий клонирован, ваш .env настроен ... мы готовы к работе!

Создать новую ветку

Внутри вашего рабочего каталога создайте новую ветку под названием «функция». Вот код, если вам нужно:

Запустить MongoDB

Теперь, когда у вас есть клонированный код на вашу машину, давайте продолжим и запустим MongoDB. Вы можете использовать следующую команду в отдельном терминале.

Примечание. Если вы ищете достойный графический интерфейс для MongoDB, обратите внимание на Compass. Вы можете скачать его здесь или запустить brew cask install mongodb-compass.

Запустить Redis

Как и в случае с MongoDB, давайте продолжим и запустим Redis. Для этого мне нравится использовать встроенную команду (из вашей командной строки):

После запуска вы должны увидеть логотип Redis в терминале (как показано выше).

Запустите Winds API и рабочие

MongoDB работает вместе с Redis. Пришло время запустить Winds. Перейдите в базовый корень каталога Winds и выполните следующую команду:

После запуска приложения вы должны увидеть следующее:

Давайте запустим интерфейс Winds

В Winds мы предоставляем два способа запуска пользовательского интерфейса приложения:

Первый метод запускает приложение внутри оболочки Electron:

Второй вариант запускает приложение в браузере Chrome, что значительно упрощает отладку:

Не стесняйтесь выбирать то, что вам нравится! Я буду использовать версию браузера, так как в ней легче ориентироваться в DOM и, кажется, она загружается быстрее.

Ву! Вы успешно настроили и запустили Winds на своем компьютере! 🎉

Добавление новой функции 🔔

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

Прежде чем продолжить разработку, создайте учетную запись, выбрав 3 или более интересов и следуя инструкциям.

Пустое состояние

Не беспокойтесь, когда вы войдете в систему. Вы увидите довольно пустой экран, поскольку мы еще не добавили никакого содержания.

Это легко решить с помощью импорта файла OPML 😀. Щелкните здесь, чтобы загрузить файл OPML, затем следуйте инструкциям ниже, чтобы импортировать его в Winds.

Нажмите «Создать» ›« Новый OPML », и появится диалоговое окно:

Когда появится диалоговое окно, перетащите загруженный файл OPML в зону перетаскивания.

Щелкните «Добавить RSS». Перезагрузите страницу, и вы должны увидеть список статей!

Если вам интересно, почему разделы «Интересное на Winds» и «Discover» пусты, то это по двум причинам:

  1. Featured on Winds требует, чтобы флаг базы данных MongoDB был установлен в значение true. Например, в RSS-канале или подкасте должно быть написано «Featured: true».
  2. Функция рекомендации Discover основана на нашем машинном обучении. Машинное обучение требует времени, поскольку оно учится на вашем взаимодействии с контентом. Чем больше вы взаимодействуете со своим контентом, тем лучше.

Примечание. Для этого руководства не обязательно запускать эти два компонента. Но если вы хотите поэкспериментировать, я бы предложил перейти в MongoDB Compass и установить для ключа RSS-канала логическое значение true.

Начиная код

Как уже упоминалось, мы собираемся добавить социальную кнопку в интерфейс. Для этого упражнения мы добавим его в RSS-каналы верхнего уровня.

Сначала щелкните заголовок раздела RSS:

Затем взгляните на каждый элемент. Заметили, что у них отсутствует логотип Twitter? Мы собираемся это добавить.

Совет для профессионалов. Самый простой способ найти то, что вы ищете, - это найти имя класса, а затем выполнить поиск в своем редакторе.

Для этого компонента мы будем искать два класса - «far fa-bookmark». Вы можете найти это в своем редакторе или просто зайти в «app / src / components / ArticleListItem.js» - строка номер 57.

Во-первых, нам нужно включить модуль под названием is-electronics. Этот модуль гарантирует, что мы показываем только значок (и используем функции) в веб-среде. Пакет уже установлен, вам просто нужно добавить его к импорту вверху файла, например:

Между следующими ‹span› в строке 59 и строке 60 мы собираемся добавить нашу кнопку Twitter!

После добавления фрагмента кода, приведенного выше, ваш код должен выглядеть следующим образом:

Мы вызываем функцию tweet (), поэтому мы хотим убедиться, что мы ее тоже создаем. Непосредственно перед методом рендеринга создайте новый метод под названием «tweet». Вы можете скопировать и вставить следующий код:

После того, как вы поместите код на место, ваш файл должен выглядеть так:

Теперь попробуйте щелкнуть логотип Twitter в пользовательском интерфейсе. Если все прошло успешно, вы должны увидеть диалоговое окно с твитом с заголовком статьи, рядом с URL-адресом и хэштегом Winds!

Ву! Вы создали свою первую функцию на Winds - надеюсь, одну из многих! Время праздновать! 🍾🥂

Если вы все еще не совсем уверены в процессе, запустите git stash и попробуйте все сначала. Не помешает сделать что-то более одного раза 😉

Чувствуете, что у вас все рухнуло? Давайте посмотрим код! Вот несколько идей, которые могут помочь вам начать работу:

  • Кнопки "Нравится" на Facebook
  • Поддержка закладок
  • Темный режим для поддержки macOS Mojave
  • Нравится (наш API уже поддерживает их)
  • Общая очистка CSS
  • Общая очистка JavaScript
  • Тестовое покрытие для API и Workers

Примечание. Мы также нанимаем разработчика на полный рабочий день (по контракту), чтобы он присоединился к команде, которая будет работать над Winds. Думаешь, у тебя есть все, что нужно? Напишите мне здесь со своим профилем в LinkedIn и любыми примерами кодирования, над которыми вы работали как единственный участник.

Заключительные мысли 🤔

Winds - самое популярное приложение такого типа с открытым исходным кодом, и мы очень рады. Бесплатные настольные приложения доступны для macOS, Linux и Windows, а также доступна веб-версия. Приложение имеет несколько функциональных возможностей, в частности каналы и персонализированные рекомендации по содержанию, все из которых основаны на Stream, лидере в области новостных лент на основе API, потоков активности и персонализации как услуги.

Спасибо, что остались и узнали немного о Winds! Надеемся в ближайшее время увидеть от вас PR!

Удачного кодирования!