CLIの開発-Golang-php.cn

Developing CLIs

CLI 機能の構築は、多くの場合次のように要約されます。

新しい API エンドポイントをリリースします。
API の変更が必要な新しい CLI アクションを構築します。
リリースしたばかりの API に間違いがあったことを認識してください。
今後さらに問題が発生することなく、この機能の API を修正してください。
CLI で何を達成しようとしていたのかを思い出し、実際にそれを達成してみてください。
後藤: 間違いがあったことを認識してください。

各ステップには前のステップが必要です。おっと、ウォーターフォールプロジェクト管理を再発明してしまいました。足を引きずって機能するようになるまで、失敗を優雅に乗り越えようとして痛みに疲れ果てますが、例外的な状況になる前に、うんざりしてしまいます。そして、結果として生じるその場限りの「修正」とイボのクラスターの保守を始めさせないでください。

そこにいた、やった。滝のようなアプローチを通り過ぎて進む必要があることはわかっていました。

ここに、私たちがそこに至るまでの経緯と、その過程で役に立ったいくつかのツールを示します。

大ざっぱなスタート

私たちは、機能を理解するまでは安価で迅速な反復を行い、理解してから高価な実装と長期サポートを約束したいと考えていました。小規模なチームとして、私はこのプロセスをエンドツーエンドで行うことが多く、各部分に順番に集中したいと考えていました。私たちは、十分に自信を持って作成できるようになるまで、実装パーツを偽装したいと考えていました。

プロセスに戻りますが、機能を提案することから始まります。私たちは抽象的な表現から抜け出したいと思っていましたが、それが中途半端な実装を意味するのであればそうではありませんでした。 Github でここで説明されている Google Docs CLI スケッチアプローチに触発されて、「スケッチ」でそれを偽装しました。

残念ながら、静的スケッチでは私たちが望んでいたようなフィードバックが得られませんでした。私たちの CLI は、時間の経過とともに出力を変化させます。描画というよりはアニメーションに似ています。より高い忠実度を達成するために、基本的な入力を受け取り、適切な定型応答を出力することで応答する小さな Ruby プログラムを作成しました。

それ以来、アニメーション CLI 出力をキャプチャするさらに良い方法を見つけましたが、それを説明するには少し回り道が必要です。

テストもしますか？

CLI の具体化を開始するにあたり、エッジケースをテストして回帰を検出したいとも考えました。アイデアを探すために公開されている cobra/bubbletea ベースの CLI を調査しましたが、イライラするほどテストがほとんどありませんでした。その後、Charm の乳首テストに出会い、出発点が得られました。

Teatest はゴールデンテストに焦点を当てており、既知の良好な出力をキャプチャし、将来の出力が引き続きその出力と一致することをアサートします。これにより、アニメーション CLI 出力の高忠実度キャプチャに再び戻りました。 Teatest は、フリップブックのようなフレームベースのソリューションという素晴らしいアイデアを私たちに与えてくれました。それをもとに構築しました。

─── SigninHeader ───────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
─── SigninInput --──────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    ? What is your username?
    ? user
─── SigninInput ────────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    * Signing in to your CLI account… ⠋
─── SigninInput ────────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    * Signed in to your CLI account: user@example.com

ログイン後にコピー

この簡略化された例は、基本的な認証コマンドのゴールデン出力がどのように見えるかを示しています。水平線はフレームを示し、ラベルはアクティブなモデルを示します。これらを総合すると、行が追加、削除、または置換された場合でも、出力を忠実にキャプチャできます。

テストスイートでフラグを使用して、ゴールデン出力でファイルを更新します。それ以外の場合、出力がファイルと一致しない場合、テストは失敗します。これにより、出力の変更を常に認識し、出力がどのように見えるべきか、変更されたかどうかを理解できるため、PR レビューが容易になります。私たちはそれがとても気に入ったので、アニメーションとスタイルのアイデアの両方をキャプチャできるように、スケッチプログラムを Github スタイルの Google ドキュメントのゴールデンスタイルの出力に置き換える予定です。

これまでと将来のスケッチを手に入れて、新しい API エンドポイントの使用開始に戻りましょう。

API と CLI を一緒に設計する

API と CLI の最適な設計は緊密な統合から生まれるため、私たちは API と CLI に同時に取り組んでいます。より安価なコンテキストで設計を繰り返し、要件が固まるまで実装を待つことで、ウォーターフォールの危険を回避しながらこれを実現できます。私たちの API の場合、これは OpenAPI を使用したスケッチを意味します:

openapi: 3.1.0
info:
  contact:
    email: contact@example.com
  description: An example API.
  title: Example API
  version: 0.0.1
servers:
  - url: https://api.example.com
tags:
  - description: account operations
    name: account
paths:
  '/v0/auth/signin':
    post:
      description: Signin to CLI.
      operationId: auth_signin
      responses:
        '200':
          content:
            'application/json':
              schema:
                additionalProperties: false
                properties:
                  email:
                    description: Email address for authenticated user.
                    example: username@example.com
                    type: string
                required:
                  - email
                type: object
          description: Successful signin.
      summary: Signin to CLI.
      tags:
        - account

ログイン後にコピー

この簡略化された例は、基本的な認可コマンドのスキーマがどのようになるかを示しています。これらのファイルの作業を簡素化するために、スペクトルリンターを使用します。

スケッチを用意して、CLI を実装する際に prism をモック API サーバーとして使用します。間違いがあったことに必然的に気づいた場合は、仕様を微調整して CLI の反復に戻るだけで済みます。この高いレベルで作業することで、API と CLI を一緒に進化させ、知識が深まるまでコストのかかる実装を延期することができます。

APIの実装

私たちは、委員会を使用して実装中に誠実さを保つために、OpenAPI 仕様にも力を入れています。 assert_schema_conform はアライメントをテストし、ミドルウェアはライブの不一致を通知します。これらを組み合わせることで、リグレッションから保護しながら、レッドグリーンの実装が可能になります。

モックとプロキシを使用したテスト

最後に、テストスイートはフラグを使用してモックモードまたはプロキシモードで Prism を実行します。フラグを使用すると、1 種類のテストの作成だけに集中できますが、どちらかのモードで一部のテストをスキップすることになります。速度向上のために、フルスタックが CI で実行されない Windows および macOS 上で模擬テストを使用します。プロキシテストを使用すると、フラグを追加するだけでスタック全体に対してテストを実行できるため、必要と思われるときはいつでも簡単にエンドツーエンドのテストを実行できます。