Construire votre prochain CLI

Si vous n'êtes pas familier avec les CLI, faisons un petit rappel. CLI est l'abréviation de Command-Line Interface (interface de ligne de commande). Il s'agit d'un outil qui utilise une interface textuelle, généralement accessible dans une application de type Terminal ou dans un environnement de type shell.

Les lecteurs réguliers savent que nous disposons déjà d'un CLIque nous utilisons comme alternative au tableau de bord. Il vous permet de gérer votre Account Vonage et d'utiliser les produits Vonage à partir de la ligne de commande. Nous avons cet outil depuis environ 4 ans, et il est écrit en Node.js. Il utilise le fichier commander.js et s'est beaucoup développé au fur et à mesure que nous avons ajouté des fonctionnalités.

L'outil étant devenu assez volumineux, nous avons atteint les limites du cadre que nous utilisons. Numbers a une façon spécifique de gérer les commandes alias et une limite stricte sur le nombre d'alias qu'une commande peut avoir. Par exemple, nexmo app:list, nexmo apps:list, nexmo apps et nexmo alet , listent toutes vos Applications Vonage. Mais pour y parvenir avec Commander, nous avons dû dupliquer du code. Nous avons créé deux commandes, chacune avec un alias, qui doivent toutes deux être maintenues. Cela a augmenté les obstacles à la contribution des gens. Cela augmente également le risque que quelqu'un (surtout moi) oublie de mettre à jour le menu d'aide pour les deux commandes avant la sortie d'une version.

Commander est parfait pour construire des CLIs plus petits, mais au fur et à mesure que le CLI s'est développé en termes de portée et de fonctionnalités, il n'a pas pu répondre à certaines de nos exigences. Lorsque nous avons mis à jour notre API Applications Applications pour prendre en charge plusieurs capacités sur la même application, nous avons pensé que les gens ne devraient pas avoir à se souvenir de 9 drapeaux pour une commande. Nous avons donc amélioré l'expérience des développeurs en ajoutant une invite interactive qui les guide tout au long du processus de création d'une application. Parce que Commander ne supporte pas le mode interactif, nous avons également intégré Inquirer.js comme dépendance.

Vous voyez probablement où je veux en venir. Les solutions de contournement que nous avons utilisées pour compenser les limitations du framework ont rendu plus difficile la maintenance et la mise à jour de notre CLI. Le CLI est quelque chose que nous utilisons tous quotidiennement, il est donc essentiel, et nous investissons du temps pour le réécrire. J'ai pensé partager le processus que nous utilisons pour travailler sur notre prochaine application CLI, au cas où vous seriez intéressés ou auriez un jour un projet comme celui-ci.

Rétrospective

Avant de nous lancer directement dans un nouveau projet de code, nous avons pris le temps de nous assurer que nous disposions d'une structure claire. Nous avons démarré le processus par une rétrospective de l'ITC actuel. Nous avons dressé une liste de certains aspects de l'actuelle CLI : "[...]les choses que nous faisons bien", "les choses que nous devrions améliorer", et "choses que nous devrions cesser de faire". Voici quelques exemples de choses que nous avons trouvées pour toutes ces rubriques.

Les choses que nous faisons bien :

• Notre CLI est un produit de première classe, au même titre que nos SDK serveur.

• L'interface de programmation offre plus d'une façon de faire certaines choses (comme le listing d'Applications dont j'ai parlé plus haut).

Les choses que nous devrions améliorer :

• Mode interactif pour la plupart des commandes.

• Formateurs pour CSV, JSON et sortie standard.

• Prise en charge de l'autocomplétion des commandes.

• Prise en charge des plugins.

• Réduire nos dépendances.

Les choses que nous devrions cesser de faire :

• Arrêtez d'utiliser ce vieux code. 😅

Vous pouvez constater que nous avions beaucoup plus de choses listées dans la catégorie "devrait mieux faire". Cette rétrospective a été très utile pour identifier une liste d'exigences.

Collecte des besoins

Ensuite, nous avons dressé une liste des cas d'utilisation que nous souhaitions pour l'ITC. Nous les avons élaborés en nous basant sur les cas d'utilisation actuels pris en charge par l'ITC. Et les demandes de fonctionnalités que nous voulions mettre en œuvre. Certaines d'entre elles auraient été trop coûteuses avec le cadre existant (par exemple, la prise en charge des plugins). Nous avons divisé ces demandes en exigences orientées vers l'utilisateur, telles que "Les utilisateurs doivent être en mesure de lister leurs Applications.". Et des exigences non liées à l'utilisateur, comme "Plusieurs formats de sortie (tableaux ASCII, CSV, JSON) seront proposés.".

Comme vous pouvez l'imaginer, nous avons abouti à une longue liste de cas d'utilisation. Bien que nous espérions tous les mettre en œuvre, nous avons estimé que le faire en une seule fois serait contre-productif et prendrait beaucoup de temps. C'est pourquoi nous les avons divisés en fonctionnalités principales et en éléments pour lesquels nous devrions créer des plugins. Pour les rendre encore plus faciles à gérer, nous avons assigné des versions cibles pour chacun d'entre eux. Par exemple, la plupart des cas d'utilisation de l'authentification seront mis en œuvre dans la V1, et quelques-uns passeront à la V2. "Envoi d'un SMS"sera l'un des premiers plugins que nous mettrons en œuvre.

Exemples de commandes

Après avoir décomposé les exigences en versions gérables, nous avons élaboré un ensemble de normes pour l'interface de programmation. Nous utilisons des exemples pour nous assurer que nous construisons une expérience de développement très cohérente dans notre nouvel outil. Voici la liste des normes que nous avons retenues :

• La dénomination des commandes doit se rapporter à l'action de l'utilisateur, et non aux noms de nos API. nexmo number format --number=012345678 --country=GB plutôt que nexmo insight basic --format --number=12345678 --country=GB.

• Les noms de commande sont des noms singuliers, c'est-à-dire nexmo app ou nexmo number.

• La deuxième partie de la commande doit être un verbe actif, c'est-à-dire nexmo app create ou nexmo number list.

• Les drapeaux sont préférés aux arguments positionnels, c'est-à-dire nexmo app update --name MyBetterNamedApp.

• Les drapeaux peuvent avoir des versions abrégées, c'est-à-dire nexmo app update -n MyBetterNamedApp.

• Les drapeaux universels doivent comprendre --help, --silent, --verbose, --debug, --format, --non-interactive et --color.

• Les commandes paginées utilisent --limit et --offsetquel que soit le mécanisme de pagination sous-jacent de nos différentes API.

Quelle est la prochaine étape ?

La construction d'une nouvelle CLI commence par une réflexion sur l'ancienne, si vous en avez une, par le recueil des exigences et par la détermination de celles qui sont les plus importantes pour l'expérience de l'utilisateur. Avec une meilleure compréhension de ce que nous attendions de la prochaine itération du CLI, nous avons commencé à identifier des cadres de construction de CLI et à les comparer à nos exigences. Je couvrirai ce processus plus en détail dans le prochain billet de blog.

D'ici là, nous travaillons à l'amélioration de notre CLI, et vous pouvez suivre nos progrès à l'adresse suivante https://github.com/nexmo/nexmo-cli. Si vous avez des suggestions ou des problèmes, n'hésitez pas à les soulever dans GitHub ou dans notre communauté slack.