Erstellung Ihrer nächsten CLI

Wenn Sie mit CLIs nicht vertraut sind, lassen Sie uns eine kurze Auffrischung vornehmen. CLI steht für Command-Line Interface (Befehlszeilenschnittstelle) und ist ein Werkzeug, das eine textbasierte Schnittstelle verwendet, die in der Regel innerhalb einer Terminal-ähnlichen Anwendung oder einer Shell-ähnlichen Umgebung zugänglich ist.

Regelmäßige Leser werden wissen, dass wir bereits ein CLI habenhaben, das wir als Alternative zum Dashboard. Es ermöglicht Ihnen die Verwaltung Ihres Vonage Account zu verwalten und Vonage-Produkte über die Befehlszeile zu nutzen. Wir haben dieses Tool seit etwa 4 Jahren und es wurde in Node.js. Es verwendet die commander.js Framework und ist im Laufe der Zeit um einige Funktionen erweitert worden.

Da das Tool recht umfangreich geworden ist, sind wir an die Grenzen des von uns verwendeten Frameworks gestoßen. Commander hat eine spezielle Art, mit Alias-Befehlen umzugehen, und eine harte Grenze für die Anzahl der Aliase, die ein Befehl haben kann. Zum Beispiel, nexmo app:list, nexmo apps:list, nexmo apps und nexmo al, alle Ihre Vonage Applications auflisten. Um dies mit dem Commander zu erreichen, mussten wir jedoch einigen Code duplizieren. Wir haben zwei Befehle erstellt, jeder mit einem Alias, die beide gewartet werden müssen. Das hat die Hürde für andere erhöht, etwas beizutragen. Es erhöht auch die Wahrscheinlichkeit, dass jemand (meistens ich) vergisst, das Hilfemenü für beide vor einer Veröffentlichung zu aktualisieren.

Commander eignet sich hervorragend für die Erstellung kleinerer CLIs, aber da der Umfang und die Funktionen der CLI gewachsen sind, konnte er einige unserer Anforderungen nicht mehr erfüllen. Als wir unsere Applications API aktualisiert haben, um mehrere Funktionen für dieselbe Applikation zu unterstützen, dachten wir, dass man sich nicht 9 Flags für einen Befehl merken muss. Daher haben wir die Entwicklererfahrung für die CLI verbessert, indem wir eine interaktive Eingabeaufforderung hinzugefügt haben, die die Benutzer durch den Prozess der Anwendungserstellung führt. Da Commander keinen interaktiven Modus unterstützt, haben wir auch Inquirer.js als eine Abhängigkeit.

Sie sehen wahrscheinlich, worauf ich hinaus will. Die Workarounds, die wir verwendet haben, um die Einschränkungen des Frameworks auszugleichen, haben die Wartung und Aktualisierung unserer CLI erschwert. Die Befehlszeilenschnittstelle ist etwas, das wir alle täglich benutzen, also ist sie ziemlich wichtig, und wir investieren die Zeit, um sie neu zu schreiben. Ich möchte Ihnen den Prozess vorstellen, mit dem wir an unserer nächsten CLI-Anwendung arbeiten, für den Fall, dass Sie daran interessiert sind oder eines Tages selbst ein derartiges Projekt haben.

Rückblickend

Bevor wir uns direkt in ein neues Code-Projekt stürzten, nahmen wir uns die Zeit, um eine klare Struktur zu schaffen. Wir begannen den Prozess mit einer Retrospektive für die aktuelle CLI. Wir haben ein paar Dinge über die aktuelle CLI aufgelistet: "Dinge, die wir gut machen", "Dinge, die wir besser machen sollten", und "Dinge, die wir nicht mehr tun sollten". Hier sind ein paar Beispiele für Dinge, die wir uns für all diese Rubriken ausgedacht haben.

Dinge, die wir gut machen:

• Unser CLI ist ein erstklassiges Produkt, gleichwertig mit unseren Server-SDKs.

• Die Befehlszeilenschnittstelle (CLI) bietet mehr als eine Möglichkeit, einige Dinge zu tun (wie die bereits erwähnte Anwendungsliste).

Dinge, die wir besser machen sollten:

• Interaktiver Modus für die meisten Befehle.

• Formatierer für CSV, JSON und Standardausgabe.

• Unterstützung der automatischen Befehlsvervollständigung.

• Unterstützung von Plugins.

• Reduzieren Sie unsere Abhängigkeiten.

Dinge, die wir nicht mehr tun sollten:

• Hört auf, die alte Codebasis zu verscherbeln. 😅

Sie können sehen, dass wir viel mehr Dinge in der Kategorie "sollte man besser machen" aufgelistet hatten. Diese Retrospektive war wirklich hilfreich, um eine Liste von Anforderungen zu erstellen.

Sammlung von Anforderungen

Als Nächstes stellten wir eine Liste von Anwendungsfällen zusammen, die wir für die CLI haben wollten. Diese Liste basierte auf den aktuellen Anwendungsfällen, die von der CLI unterstützt werden. Und die Funktionsanforderungen, die wir implementieren wollten. Einige davon wären mit dem bestehenden Framework zu kostspielig gewesen (z. B. die Unterstützung von Plugins). Wir teilten diese in benutzerorientierte Anforderungen auf wie "Benutzer müssen in der Lage sein, ihre Applications aufzulisten.". Und nicht-benutzerorientierte Anforderungen wie "Es werden mehrere Ausgabeformate (ASCII-Tabellen, CSV, JSON) angeboten.".

Wie Sie sich vorstellen können, hatten wir am Ende eine lange Liste von Anwendungsfällen. Wir hoffen, dass wir sie alle implementieren können, aber wir sind der Meinung, dass es kontraproduktiv wäre und viel Zeit in Anspruch nehmen würde, sie in einem Rutsch zu implementieren. Deshalb haben wir sie in Kernfunktionen und Dinge, für die wir Plugins entwickeln sollten, unterteilt. Um sie noch überschaubarer zu machen, haben wir für sie alle Zielversionen festgelegt. Zum Beispiel werden die meisten Anwendungsfälle für die Authentifizierung in V1 implementiert, einige wenige werden in V2 übernommen."Versenden einer SMS" wird eines der ersten Plugins sein, das wir implementieren.

Beispiele für Befehle

Nachdem wir die Anforderungen in überschaubare Versionen aufgeteilt hatten, stellten wir eine Reihe von Standards für die Befehlszeilenschnittstelle zusammen. Anhand von Beispielen stellen wir sicher, dass unser neues Tool den Entwicklern eine einheitliche Erfahrung bietet. Hier ist die Liste der Standards, auf die wir uns geeinigt haben:

• Bei der Benennung von Befehlen sollte es um die Aktion des Benutzers gehen, nicht um unsere API-Namen, d.h. nexmo number format --number=012345678 --country=GB und nicht nexmo insight basic --format --number=12345678 --country=GB.

• Befehlsnamen sind Singularnomen, d. h. nexmo app oder nexmo number.

• Der zweite Teil des Befehls sollte ein aktives Verb sein, d.h. nexmo app create oder nexmo number list.

• Flaggen werden gegenüber Positionsargumenten bevorzugt, d. h.. nexmo app update --name MyBetterNamedApp.

• Flaggen können Kurzversionen haben, z. B. nexmo app update -n MyBetterNamedApp.

• Universalflaggen sollten enthalten --help, --silent, --verbose, --debug, --format, --non-interactive und --color.

• Paginierte Befehle verwenden --limit und --offsetverwenden, unabhängig vom zugrunde liegenden Paginierungsmechanismus unserer verschiedenen APIs.

Was kommt als Nächstes?

Der Aufbau einer neuen CLI beginnt damit, dass man sich Gedanken über die alte CLI macht, wenn man eine hat, Anforderungen sammelt und herausfindet, welche davon für die Benutzererfahrung am wichtigsten sind. Mit einem besseren Verständnis dessen, was wir von der nächsten Iteration der CLI erwarten, haben wir damit begonnen, Frameworks für die CLI-Erstellung zu identifizieren und sie mit unseren Anforderungen zu vergleichen. Auf diesen Prozess werde ich im nächsten Blog-Beitrag näher eingehen.

Bis dahin arbeiten wir an der Verbesserung unserer CLI, und Sie können unsere Fortschritte verfolgen unter https://github.com/nexmo/nexmo-cli. Wenn Sie Vorschläge oder Probleme haben, können Sie diese gerne auf GitHub oder in unserem Community-Slack.