Flutter命令行工具生成插件cli_gen的使用

Flutter命令行工具生成插件cli_gen的使用

cli_gen 是一个用于从普通的 Dart 类和函数生成命令行应用程序的工具。它通过注解的方式简化了 CLI 应用程序的开发和维护，提供了类型安全的参数解析、自动帮助文本生成等功能。以下是关于如何使用 cli_gen 的完整示例。

1. 安装依赖

首先，在 pubspec.yaml 文件中添加 cli_annotations 作为依赖项，并将 cli_gen 和 build_runner 作为开发依赖项：

name: dart_git
description: An implementation of the git CLI in Dart.

environment:
  sdk: ^3.0.0

dependencies:
  cli_annotations: ^0.1.0-dev.4

dev_dependencies:
  build_runner: ^2.4.8
  cli_gen: ^0.1.0-dev.4

# 可选：定义可执行文件名
executables:
  dart_git: main

2. 运行代码生成器

安装依赖后，启动 build_runner 以开始代码生成：

$ dart run build_runner watch -d

3. 定义命令运行器

创建一个 CommandRunner 类，并使用 @cliRunner 注解标注该类，继承生成的超类（通常带有 _$ 前缀）。生成的代码包含一个 CommandRunner.run() 方法，这是 CLI 应用程序的入口点，将在 main 函数中调用。

import 'package:cli_annotations/cli_annotations.dart';

part 'example.g.dart';

/// A command-line interface for version control.
@cliRunner
class GitRunner extends _$GitRunner {
  // ...
}

4. 定义命令

在 CommandRunner 类中，通过创建方法并使用 [@cliCommand](/user/cliCommand) 注解来定义命令。以下是一个简单的 merge 命令示例：

@cliRunner
class GitRunner extends _$GitRunner {
  /// Join two or more development histories together.
  [@cliCommand](/user/cliCommand)
  Future<void> merge({
    /// The name of the branch to be merged into the current branch.
    required String branch,

    /// Pass merge strategy specific option through to the merge strategy.
    MergeStrategy strategy = MergeStrategy.ort,

    /// Perform the merge and commit the result.
    bool? commit,
  }) async {
    print('Merging branch $branch');
    if (commit == true) {
      print('Committing merge');
    }
    await Future.delayed(const Duration(seconds: 1));
  }
}

enum MergeStrategy { ort, recursive, resolve, octopus, ours, subtree }

5. 定义子命令

随着应用程序的增长，您可能希望将命令分组。为此，可以创建一个 Subcommand 类，并使用 @cliSubcommand 注解标注该类，继承生成的超类。然后使用 @cliMount 注解将子命令连接到主 CommandRunner 类。

/// Commands for managing a stack of stashed changes.
///
/// Use this to save and restore changes in a working directory temporarily, allowing
/// you to switch contexts and manage your work in progress without committing to the
/// Git history.
@cliSubcommand
class StashSubcommand extends _$StashSubcommand {
  /// Save your local modifications to a new stash.
  [@cliCommand](/user/cliCommand)
  Future<void> push({
    required String message,
  }) async {
    print('Stashing changes with message: $message');
    await Future.delayed(const Duration(seconds: 1));
  }

  /// Apply the stash at the given [stashRef] to the working directory.
  [@cliCommand](/user/cliCommand)
  Future<void> apply({
    String stashRef = '0',
  }) async {
    print('Applying stash $stashRef');
    await Future.delayed(const Duration(seconds: 1));
  }
}

@cliRunner
class GitRunner extends _$GitRunner {
  @cliMount
  StashSubcommand get stash => StashSubcommand();
}

6. 运行应用程序

最后，创建一个 main 函数，调用 CommandRunner 的 run 方法：

Future<void> main(List<String> args) => GitRunner().run(args);

7. 测试应用程序

激活可执行文件（如果在 pubspec.yaml 中定义了可执行文件）并运行应用程序：

# 激活可执行文件
$ dart pub global activate . --source=path

# 运行应用程序
$ dart_git merge --help

您应该看到类似以下的帮助文本输出：

$ dart_git merge --help
Join two or more development histories together.

Usage: git-runner merge [arguments]
--branch (mandatory)
--commit
--options

Run "git-runner help" to see global options.

特性

类型安全的参数解析

cli_gen 自动将传入的字符串参数解析为正确的 Dart 类型，并在用户输入无效值时自动提示错误。支持的类型包括 String、int、double、bool、num、Uri、BigInt 和 DateTime。还可以使用集合类型 List、Set 和 Iterable。

帮助文本推断

cli_gen 会根据方法声明、文档注释和默认值自动生成帮助文本。例如：

[@cliCommand](/user/cliCommand)
Future<void> myCustomCommand({
  /// A parameter that uses a doc comment
  String someDocumentedParameter,
}) async {
  // ...
}

生成的帮助文本：

$ my-custom-command --help
Save your local modifications to a new stash.

Usage: git stash my-custom-command [arguments]
-h, --help                         Print this usage information.
    --some-documented-parameter    A parameter that uses a doc comment

Run "git help" to see global options.

位置参数

cli_gen 支持位置参数，允许用户直接传递参数而无需使用命名标志。例如：

[@cliCommand](/user/cliCommand)
Future<void> push(
  String remote,      // 位置参数
  String? branch, {   // 位置参数
  bool force = false, // 命名参数
}) async {
  /* ... */
}