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

Постоянные читатели знают, что Nexmo уже имеет CLI, который мы используем как альтернативу Dashboard. Он позволяет вам управлять своей учетной записью Vonage и использовать продукты Vonage из командной строки. У нас есть этот инструмент около 4 лет, он написан на Node.js. Он использует фреймворк commander.js и значительно расширился по мере того, как мы добавляли функциональность с течением времени.

Поскольку инструмент стал довольно большим, мы исчерпали ограничения используемого фреймворка. В Commander есть особый способ обработки псевдонимов команд и жесткое ограничение на количество псевдонимов, которые может иметь команда. Например, nexmo app:list, nexmo apps:list, nexmo apps и nexmo al, все перечисляют ваши приложения Vonage. Но чтобы добиться этого с помощью Commander, нам пришлось продублировать некоторый код. Мы создали две команды, каждая с псевдонимом, которые необходимо поддерживать. Это увеличило барьер для людей, которые могут внести свой вклад. Это также увеличивает вероятность того, что кто-то (в основном я) забудет обновить меню справки для обоих перед выпуском.

Commander отлично подходит для создания небольших интерфейсов командной строки, но по мере того, как объем и возможности интерфейса командной строки выросли, он не смог удовлетворить некоторые из наших требований. Когда мы обновили наш API приложений для поддержки нескольких возможностей в одном приложении, мы подумали, что людям не нужно запоминать 9 флагов для команды. Поэтому мы улучшили интерфейс командной строки для разработчиков, добавив интерактивную подсказку, которая направляет людей через процесс создания приложения. Поскольку Commander не поддерживает интерактивный режим, мы также использовали Inquirer.js в качестве зависимости.

Вы, наверное, видите, к чему я клоню. Обходные пути, которые мы использовали для компенсации ограничений фреймворка, усложнили поддержку и обновление нашего интерфейса командной строки. Интерфейс командной строки - это то, что мы все используем ежедневно, поэтому он очень важен, и мы вкладываем время, чтобы его переписать. Я подумал, что поделюсь процессом, который мы используем для работы над нашим следующим приложением CLI, на случай, если вы заинтересуетесь или у вас когда-нибудь будет подобный проект.

Ретроспектива

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

Что у нас хорошо получается:

  • Наш CLI - это первоклассный продукт, не уступающий нашим Server SDK.
  • Интерфейс командной строки предлагает несколько способов выполнения некоторых действий (например, список приложений, о котором я упоминал ранее).

Что нам следует делать лучше:

  • Интерактивный режим для большинства команд.
  • Средства форматирования для CSV, JSON и стандартного вывода.
  • Поддержка автозаполнения команд.
  • Плагины поддержки.
  • Уменьшите наши зависимости.

Что нам следует прекратить делать:

  • Прекратите пороть эту старую кодовую базу. 😅

Как видите, у нас было гораздо больше вещей, перечисленных в категории «Должен быть лучше». Эта ретроспектива действительно помогла определить список требований.

Сбор требований

Затем мы составили список вариантов использования интерфейса командной строки. Мы придумали их на основе текущих вариантов использования, поддерживаемых CLI. И запросы функций, которые мы хотели реализовать. Некоторые из них были бы слишком дорогими с существующей структурой (например, с поддержкой плагинов). Мы разделили их на требования, ориентированные на пользователя, например «Пользователи должны иметь возможность перечислять свои приложения». И требования, не ориентированные на пользователя, такие как «Будет предложено несколько выходных форматов (таблицы ASCII, CSV, JSON).».

Как вы понимаете, у нас получился длинный список вариантов использования. Хотя мы надеемся реализовать все из них, мы чувствовали, что сделать это за один раз было бы контрпродуктивно и потребовало бы много времени. Итак, мы разбили их на основные функции и вещи, для которых мы должны создавать плагины. Чтобы сделать их еще более управляемыми, мы назначили для всех целевые версии. Например, большинство сценариев использования аутентификации будут реализованы в V1, а некоторые перейдут в V2. «Отправка SMS» будет одним из первых плагинов, которые мы реализуем.

Примеры команд

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

  • Именование команд должно касаться действий пользователя, а не имен наших API. т.е. nexmo number format --number=012345678 --country=GB, а не nexmo insight basic --format --number=12345678 --country=GB.
  • Имена команд - существительные в единственном числе. т.е. nexmo app или nexmo number.
  • Вторая часть команды должна быть активным глаголом. т.е. nexmo app create или nexmo number list.
  • Флаги предпочтительнее позиционных аргументов. я. е. nexmo app update --name MyBetterNamedApp.
  • У флагов могут быть сокращенные версии. т.е. nexmo app update -n MyBetterNamedApp.
  • Универсальные флаги должны включать --help, --silent, --verbose, --debug, --format, --non-interactive и --color.
  • Команды с разбивкой на страницы будут использовать --limit и --offset, независимо от механизма разбивки на страницы наших различных API.

Что дальше?

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

А пока мы работаем над улучшением нашего интерфейса командной строки, и вы можете отслеживать наш прогресс на странице https://github.com/nexmo/nexmo-cli. Если у вас есть какие-либо предложения или проблемы, не стесняйтесь поднимать их на GitHub или в нашем сообществе Slack.

Первоначально опубликовано на https://www.nexmo.com 5 июня 2020 г.