Dart CLI アプリケーションの構築

目次

• プロジェクト設定とアーキテクチャ
• 引数解析とコマンドルーティング
• 実行とエラーハンドリング
• CLI アプリケーションのテスト
• コンパイルと配布
• ワークフロー
• 例

プロジェクト設定とアーキテクチャ

標準的なディレクトリ構造を確保するために、公式の Dart テンプレートを使用して新しい CLI プロジェクトを初期化します。

• dart create -t cli <project_name> を実行して、基本的な引数解析を含むコンソールアプリケーションをスキャフォールドします。
• 実行可能なエントリーポイント (main() を含むファイル) は bin/ ディレクトリにのみ配置します。
• 内部実装ロジックは lib/src/ に配置し、lib/<project_name>.dart を通じてパブリック API を公開します。
• CI 環境でフォーマットを強制するために、dart format . --set-exit-if-changed を実行します。フォーマット違反が存在する場合、終了コード 1 を返します。

引数解析とコマンドルーティング

args パッケージをインポートして、コマンドライン引数、フラグ、サブコマンドを管理します。

• シンプルなスクリプトを構築する場合: ArgParser を直接使用してフラグ (addFlag) とオプション (addOption) を定義します。
• 複雑な複数コマンド CLI (例: git) を構築する場合: CommandRunner を実装し、各サブコマンドに対して Command を拡張します。
• グローバル引数は CommandRunner.argParser に、コマンド固有の引数は個別の Command.argParser に定義します。
• UsageException をキャッチして、無効な引数を優雅に処理し、自動生成されたヘルプテキストを表示します。
• ヘルプテキストの正確性を検証する: ヘルプテキストがツール実行に必要なすべての情報を提供していることを確認します。ヘルプテキストがコンパイル済み実行可能ファイル名を参照し、ユーザーが PATH に追加して実行する必要がある場合、ヘルプテキストまたは説明に方法を明確に記載します。

実行とエラーハンドリング

堅牢で本番環境対応の CLI ツールを構築するために、io と stack_trace パッケージを活用します。

• io パッケージの ExitCode enum を使用して標準的な POSIX 終了コードを返します (例: ExitCode.success.code、ExitCode.usage.code)。
• 複数の非同期リスナーが標準入力への順序付きアクセスが必要な場合は、io パッケージから sharedStdIn を使用します。
• stack_trace パッケージの Chain.capture() でアプリケーション実行をラップして、非同期スタックチェーンを追跡します。
• Trace.terse または Chain.terse を使用してスタックトレースをフォーマットし、ノイズの多いコアライブラリフレームを除去して、ユーザーに読みやすいエラーを提示します。
• 例外を飲み込まない: 回復が可能でない限り、低レベルのロジックやストレージクラスで例外を飲み込みません。バブルアップするか再スローして、高レベルのコマンドが操作の失敗を認識できるようにします。
• 早期失敗と非ゼロ終了コード: 操作の失敗は stderr への説明的なエラーメッセージと適切な非ゼロ終了コード (例: exit(1) の使用またはキャッチされた UsageException の後 64 終了コードのトリガー) を結果とします。

CLI アプリケーションのテスト

[!IMPORTANT] すべての新しいコマンドと重要な機能は、自動化されたテストでカバーする必要があります。 手動検証はロジックのテストには不十分です。ただし、インターフェースが直感的で正しいことを確認するために、ヘルプテキストとユーザー経験 (UX) の手動検証は依然として必要です。

test_process と test_descriptor を使用して、CLI の高忠実度統合テストを作成します。

• test_descriptor (d.dir、d.file) を使用して期待されるファイルシステム状態を定義します。
• 実行前に await d.Descriptor.create() を使用してモックファイルシステムを作成します。
• TestProcess.start('dart', ['run', 'bin/cli.dart', ...args]) を使用して CLI プロセスを生成します。
• StreamQueue マッチャー (例: emitsThrough、emits) を使用して標準出力とエラーストリームを検証します。
• await process.shouldExit(0) を使用して最終的な終了コードをアサートします。
• await d.Descriptor.validate() を使用してファイルシステムの変更を検証します。

コンパイルと配布

配布要件に基づいて適切なコンパイル対象を選択します。

• 開発中にローカルでテストする場合: dart run bin/cli.dart を使用します。これは JIT コンパイラを使用して高速な反復処理を行います。
• コードアセットと動的ライブラリをバンドルする場合: dart build cli を使用します。これはビルドフックを実行し、build/cli/_/bundle/ に出力されます。
• スタンドアロンのネイティブ実行可能ファイルを配布する場合: dart compile exe bin/cli.dart -o <output_path> を使用します。これは Dart ランタイムとマシンコードを 1 つのファイルにバンドルします。
• ディスク領域が厳密に制限された複数のアプリを配布する場合: dart compile aot-snapshot bin/cli.dart を使用します。結果の .aot ファイルを dartaotruntime を使用して実行します。

<details> <summary>クロスコンパイルターゲット (Linux のみ)</summary>

Dart は macOS、Windows、または Linux ホストから Linux へのクロスコンパイルをサポートしています。 dart compile exe または dart compile aot-snapshot で --target-os と --target-arch フラグを使用します。

• --target-os=linux (現在のところ Linux のみクロスコンパイルターゲットとしてサポートされています)
• --target-arch=arm64 (64 ビット ARM)
• --target-arch=x64 (x86-64)
• --target-arch=arm (32 ビット ARM)
• --target-arch=riscv64 (64 ビット RISC-V)

例: dart compile exe --target-os=linux --target-arch=arm64 bin/cli.dart

</details>

ワークフロー

タスク進捗: 新しい CLI コマンドの実装

• lib/src/commands/ に Command を拡張する新しいクラスを作成します。
• name と description プロパティを定義します。
• コンストラクタで argParser.addFlag() または argParser.addOption() を使用してコマンド固有のフラグを登録します。
• コアロジックを使用して run() メソッドを実装します。
• bin/cli.dart の CommandRunner インスタンスで addCommand() を使用して新しいコマンドを登録します。
• test/ ディレクトリで test_process または標準テストを使用して新しいコマンドのテストを作成します。
• バリデーター実行 -> dart run bin/cli.dart help <command_name> を実行してヘルプテキスト生成を検証します。
• 最終的な UX を検証: dart compile exe を使用してアプリケーションをコンパイルし、結果の実行可能ファイルを実行してターゲットユーザー経験 (例: ./bin/cli <command>) を検証します。

タスク進捗: ネイティブ実行可能ファイルのコンパイルとリリース

• バリデーター実行 -> dart format . --set-exit-if-changed を実行してコードフォーマットを確認します。
• バリデーター実行 -> dart analyze を実行して静的解析エラーがないことを確認します。
• バリデーター実行 -> dart test を実行してすべての統合テストに合格します。
• ホスト OS 向けにコンパイル: dart compile exe bin/cli.dart -o build/cli-host
• Linux 向けにコンパイル (ホストが macOS/Windows の場合): dart compile exe --target-os=linux --target-arch=x64 bin/cli.dart -o build/cli-linux-x64

例

例: CommandRunner 実装

import 'dart:io';
import 'package:args/command_runner.dart';
import 'package:stack_trace/stack_trace.dart';

class CommitCommand extends Command {
  @override
  final String name = 'commit';
  @override
  final String description = 'Record changes to the repository.';

  CommitCommand() {
    argParser.addFlag('all', abbr: 'a', help: 'Commit all changed files.');
  }

  @override
  Future<void> run() async {
    final commitAll = argResults?['all'] as bool? ?? false;
    print('Committing... (All: $commitAll)');
  }
}

void main(List<String> args) {
  Chain.capture(() async {
    final runner = CommandRunner('dgit', 'Distributed version control.')
      ..addCommand(CommitCommand());

    await runner.run(args);
  }, onError: (error, chain) {
    if (error is UsageException) {
      stderr.writeln(error.message);
      stderr.writeln(error.usage);
      exit(64); // ExitCode.usage.code
    } else {
      stderr.writeln('Fatal error: $error');
      stderr.writeln(chain.terse);
      exit(1);
    }
  });
}

例: サブプロセスによる統合テスト

import 'package:test/test.dart';
import 'package:test_process/test_process.dart';
import 'package:test_descriptor/test_descriptor.dart' as d;

void main() {
  test('CLI formats output correctly and modifies filesystem', () async {
    // 1. Setup mock filesystem
    await d.dir('project', [
      d.file('config.json', '{"key": "value"}')
    ]).create();

    // 2. Spawn the CLI process
    final process = await TestProcess.start(
      'dart',
      ['run', 'bin/cli.dart', 'process', '--path', '${d.sandbox}/project']
    );

    // 3. Validate stdout stream
    await expectLater(process.stdout, emitsThrough('Processing complete.'));

    // 4. Validate exit code
    await process.shouldExit(0);

    // 5. Validate filesystem mutations
    await d.dir('project', [
      d.file('config.json', '{"key": "value"}'),
      d.file('output.log', 'Success')
    ]).validate();
  });
}