当前位置: 首页 > 工具软件 > picocli > 使用案例 >

使用Picocli创建Java命令行程序

梁新觉
2023-12-01

https://www.codenong.com/b-java-picocli-create-command-line-program/

1.简介

在本教程中,我们将使用picocli库,该库使我们可以轻松地用Java创建命令行程序。

首先,我们将创建一个Hello World命令。 然后,我们将通过部分复制gitcommand来深入了解该库的关键功能。

2.你好世界命令

让我们从简单的事情开始:Hello World命令!

首先,我们需要将依赖项添加到thepicocli项目中:

1
2
3
4
5

<dependency>
    <groupId>info.picocli</groupId>
    <artifactId>picocli</artifactId>
    <version>3.9.6</version>
</dependency>

如我们所见,我们将使用库的3.9.6版本,尽管a4.0.0版本正在构建中(当前在alpha测试中可用)。

现在已经建立了依赖关系,让我们创建我们的Hello World命令。 为此,我们将使用库中的@Command注释:

1
2
3
4
5
6

@Command(
  name ="hello",
  description ="Says hello"
)
public class HelloWorldCommand {
}

如我们所见,注释可以带有参数。 我们在这里只使用其中两个。 它们的目的是提供有关自动帮助消息的当前命令和文本的信息。

目前,使用此命令我们无能为力。 为了使其能够执行某些操作,我们需要添加一个调用便捷CommandLine.run(Runnable,String [])方法的主方法。 这需要两个参数:一个命令实例,因此必须实现Runnable接口;一个String数组,表示命令参数(选项,参数和子命令):

1
2
3
4
5
6
7
8
9
10

public class HelloWorldCommand implements Runnable {
    public static void main(String[] args) {
        CommandLine.run(new HelloWorldCommand(), args);
    }

    @Override
    public void run() {
        System.out.println("Hello World!");
    }
}

现在,当我们运行main方法时,我们将看到控制台输出" Hello World!"。

打包到jar中后,我们可以使用java命令运行Hello World命令:

1

java -cp"pathToPicocliJar;pathToCommandJar" com.baeldung.picoli.helloworld.HelloWorldCommand

毫不奇怪,它还会输出" Hello World!" 字符串到控制台。

3.具体的用例

现在,我们已经了解了基础知识,我们将深入研究picocli库。 为了做到这一点,我们将部分复制一个流行的命令:git。

当然,其目的不是实现git命令的行为,而是重现git命令的可能性-存在哪些子命令以及哪些选项可用于特殊的子命令。

首先,我们必须像对Hello World命令那样创建一个GitCommand类:

1
2
3
4
5
6
7
8
9
10
11

@Command
public class GitCommand implements Runnable {
    public static void main(String[] args) {
        CommandLine.run(new GitCommand(), args);
    }

    @Override
    public void run() {
        System.out.println("The popular git command");
    }
}

4.添加子命令

gitcommand提供了许多子命令-add,commit,remote等。 在这里,我们将重点介绍添加和提交。

因此,我们的目标是在主命令中声明这两个子命令.Picocli提供了三种实现方法。

4.1。 在类上使用@Command注释

@Command批注提供了通过subcommands参数注册子命令的可能性:

1
2
3
4
5
6

@Command(
  subcommands = {
      GitAddCommand.class,
      GitCommitCommand.class
  }
)

在本例中,我们添加了两个新类:GitAddCommand和GitCommitCommand。 两者都用@Command和ImplementRunnable进行注释。 给他们起一个名字很重要,因为picocli将使用这些名字来识别要执行的子命令:

1
2
3
4
5
6
7
8
9

@Command(
  name ="add"
)
public class GitAddCommand implements Runnable {
    @Override
    public void run() {
        System.out.println("Adding some files to the staging area");
    }
}

1
2
3
4
5
6
7
8
9

@Command(
  name ="commit"
)
public class GitCommitCommand implements Runnable {
    @Override
    public void run() {
        System.out.println("Committing files in the staging area, how wonderful?");
    }
}

因此,如果我们使用add作为参数运行main命令,则控制台将输出"将某些文件添加到暂存区"。

4.2。 在方法上使用@Command注释

声明子命令的另一种方法是创建@Command注释的方法,该方法表示GitCommand类中的那些命令:

1
2
3
4
5
6
7
8
9

@Command(name ="add")
public void addCommand() {
    System.out.println("Adding some files to the staging area");
}

@Command(name ="commit")
public void commitCommand() {
    System.out.println("Committing files in the staging area, how wonderful?");
}

这样,我们可以将业务逻辑直接实现到方法中,而无需创建单独的类来处理它。

4.3。 以编程方式添加子命令

最后,picocli为我们提供了以编程方式注册子命令的可能性。 这有点棘手,因为我们必须创建一个包装命令的CommandLine对象,然后向其中添加子命令:

1
2
3

CommandLine commandLine = new CommandLine(new GitCommand());
commandLine.addSubcommand("add", new GitAddCommand());
commandLine.addSubcommand("commit", new GitCommitCommand());

在那之后,我们仍然必须运行命令,但是不能再使用CommandLine.run()方法了。 现在,我们必须在新创建的CommandLine对象上调用theparseWithHandler()方法:

1

commandLine.parseWithHandler(new RunLast(), args);

我们应该注意RunLast类的使用,该类告诉picocli运行最特定的子命令。 picocli还提供了其他两个命令处理程序:RunFirst和RunAll。 前者运行最高命令,而后者运行所有命令。

使用便捷方法CommandLine.run()时,默认情况下使用RunLast处理程序。

5.使用@Option注释管理选项

5.1。 无参数期权

现在让我们看看如何在命令中添加一些选项。 确实,我们想告诉ouradd命令它应该添加所有修改过的文件。 为此,我们将在@GitAddCommand类中添加一个@Option注释字段:

1
2
3
4
5
6
7
8
9
10
11

@Option(names = {"-A","--all"})
private boolean allFiles;

@Override
public void run() {
    if (allFiles) {
        System.out.println("Adding all files to the staging area");
    } else {
        System.out.println("Adding some files to the staging area");
    }
}

如我们所见,注释采用了一个名称参数,该参数给出了选项的不同名称。 因此,使用-A或–all调用add命令会将allFiles字段设置为true。 因此,如果我们运行带有该选项的命令,控制台将显示"将所有文件添加到暂存区"。

5.2。 带参数的选项

如我们所见,对于不带参数的选项,它们的存在或不存在总是被评估为布尔值。

但是,可以注册带有参数的选项。 我们只需声明我们的字段为其他类型即可完成此操作。 让我们向我们的commit命令添加一个消息选项:

1
2
3
4
5
6
7
8
9
10

@Option(names = {"-m","--message"})
private String message;

@Override
public void run() {
    System.out.println("Committing files in the staging area, how wonderful?");
    if (message != null) {
        System.out.println("The commit message is" + message);
    }
}

毫不奇怪,当给定message选项时,该命令将在控制台上显示提交消息。 在本文的后面,我们将介绍库处理的类型以及如何处理其他类型。

5.3。 具有多个参数的选项

但是现在,如果我们希望我们的命令接受多条消息,就像真正的git commit命令那样,该怎么办? 不用担心,让我们将字段设为数组或Collection,我们已经完成很多工作:

1
2
3
4
5
6
7
8
9
10
11
12
13

@Option(names = {"-m","--message"})
private String[] messages;

@Override
public void run() {
    System.out.println("Committing files in the staging area, how wonderful?");
    if (messages != null) {
        System.out.println("The commit message is");
        for (String message : messages) {
            System.out.println(message);
        }
    }
}

现在,我们可以多次使用message选项:

1

commit -m"My commit is great" -m"My commit is beautiful"

但是,我们可能也只想给该选项一次,并用正则表达式定界符分隔不同的参数。 因此,我们可以使用@Option注释的split参数:

1
2

@Option(names = {"-m","--message"}, split =",")
private String[] messages;

现在,我们可以通过-m"我的承诺很棒","我的承诺很棒"来达到与上述相同的结果。

5.4。 必选选项

有时,我们可能有一个必需的选项。 必需的参数(默认为false)允许我们执行以下操作:

1
2

@Option(names = {"-m","--message"}, required = true)
private String[] messages;

现在,如果不指定message选项,就无法调用commit命令。 如果我们尝试这样做,picocli将输出错误:

1
2
3

Missing required option '--message=<messages>'
Usage: git commit -m=<messages> [-m=<messages>]...
  -m, --message=<messages>

6.管理位置参数

6.1。 捕获位置参数

现在,让我们关注我们的add命令,因为它还不是很强大。 我们只能决定添加所有文件,但是如果我们想添加特定文件,该怎么办?

我们可以使用另一种方法来执行此操作,但此处更好的选择是使用位置参数。 实际上,位置参数旨在捕获占据特定位置的命令参数,这些参数既不是子命令也不是选项。

在我们的示例中,这将使我们能够执行以下操作:

1

add file1 file2

为了捕获位置参数,我们将使用@Parameters批注:

1
2
3
4
5
6
7
8
9
10
11
12
13

@Parameters
private List<Path> files;

@Override
public void run() {
    if (allFiles) {
        System.out.println("Adding all files to the staging area");
    }

    if (files != null) {
        files.forEach(path -> System.out.println("Adding" + path +" to the staging area"));
    }
}

现在,我们前面的命令将输出:

1
2

Adding file1 to the staging area
Adding file2 to the staging area

6.2。 捕获位置参数的子集

由于注释的index参数,可以更精确地捕获要捕获的位置参数。 索引从零开始。 因此,如果我们定义:

1

@Parameters(index="2..*")

从第三个到最后,这将捕获与选项或子命令不匹配的参数。

索引可以是一个范围或单个数字,代表一个位置。

7.关于类型转换的一句话

正如我们在本教程前面所看到的,picocli本身可以处理一些类型转换。 例如,它将多个值映射到数组或集合,但也可以将参数映射到特定类型,例如当我们将路径类用于add命令时。

实际上,picocli带有许多预处理的类型。 这意味着我们可以直接使用这些类型,而不必考虑自己转换它们。

但是,我们可能需要将命令参数映射到已处理类型以外的其他类型。 对我们来说幸运的是,这要归功于ITypeConverter接口和CommandLine#registerConverter方法,该方法将类型与转换器相关联。

假设我们想将config子命令添加到我们的git命令中,但是我们不希望用户更改不存在的配置元素。 因此,我们决定将这些元素映射到一个枚举:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

public enum ConfigElement {
    USERNAME("user.name"),
    EMAIL("user.email");

    private final String value;

    ConfigElement(String value) {
        this.value = value;
    }

    public String value() {
        return value;
    }

    public static ConfigElement from(String value) {
        return Arrays.stream(values())
          .filter(element -> element.value.equals(value))
          .findFirst()
          .orElseThrow(() -> new IllegalArgumentException("The argument"
          + value +" doesn't match any ConfigElement"));
    }
}

另外,在我们新创建的GitConfigCommand类中,让我们添加两个位置参数:

1
2
3
4
5
6
7
8
9
10

@Parameters(index ="0")
private ConfigElement element;

@Parameters(index ="1")
private String value;

@Override
public void run() {
    System.out.println("Setting" + element.value() +" to" + value);
}

这样,我们确保用户将无法更改不存在的配置元素。

最后,我们必须注册我们的转换器。 美妙的是,如果使用Java 8或更高版本,我们甚至不必创建实现ITypeConverter接口的类。 我们可以将lambda或方法引用传递给registerConverter()方法:

1
2
3
4

CommandLine commandLine = new CommandLine(new GitCommand());
commandLine.registerConverter(ConfigElement.class, ConfigElement::from);

commandLine.parseWithHandler(new RunLast(), args);

这发生在GitCommandmain()方法中。 请注意,我们必须放开convenienceCommandLine.run()方法。

与未处理的配置元素一起使用时,该命令将显示帮助消息以及一条信息,告诉我们无法将参数转换为ConfigElement:

1
2
3
4
5
6

Invalid value for positional parameter at index 0 (<element>):
cannot convert 'user.phone' to ConfigElement
(java.lang.IllegalArgumentException: The argument user.phone doesn't match any ConfigElement)
Usage: git config <element> <value>
      <element>
      <value>

8.与Spring Boot集成

最后,让我们看看如何将所有这些内容进行弹奏!

确实,我们可能正在Spring Boot环境中工作,并希望从我们的命令行程序中受益。 为了做到这一点,我们必须创建一个实现了CommandLineRunner接口的SpringBootApplication:

1
2
3
4
5
6
7
8
9
10

@SpringBootApplication
public class Application implements CommandLineRunner {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    @Override
    public void run(String... args) {
    }
}

另外,让我们用Spring @Component注释注释所有命令和子命令,并自动装配应用程序中的所有内容:

1
2
3
4
5
6
7
8
9
10
11
12

private GitCommand gitCommand;
private GitAddCommand addCommand;
private GitCommitCommand commitCommand;
private GitConfigCommand configCommand;

public Application(GitCommand gitCommand, GitAddCommand addCommand,
  GitCommitCommand commitCommand, GitConfigCommand configCommand) {
    this.gitCommand = gitCommand;
    this.addCommand = addCommand;
    this.commitCommand = commitCommand;
    this.configCommand = configCommand;
}

注意,我们必须自动装配每个子命令。 不幸的是,这是因为到目前为止,picocli在以声明方式(带有批注)进行声明时仍无法从Spring上下文中检索子命令。 因此,我们必须以编程方式自己进行连接:

1
2
3
4
5
6
7
8
9

@Override
public void run(String... args) {
    CommandLine commandLine = new CommandLine(gitCommand);
    commandLine.addSubcommand("add", addCommand);
    commandLine.addSubcommand("commit", commitCommand);
    commandLine.addSubcommand("config", configCommand);

    commandLine.parseWithHandler(new CommandLine.RunLast(), args);
}

现在,我们的命令行程序对Spring组件来说就像一个魅力。 因此,我们可以创建一些服务类并在命令中使用它们,而letSpring负责依赖注入。

9.结论

在本文中,我们已经了解了picoclilibrary的一些关键功能。 我们已经学习了如何创建新命令并向其中添加一些子命令。 我们已经看到了许多处理选项和位置参数的方法。 另外,我们还学习了如何实现自己的类型转换器以使命令强类型化。 最后,我们已经了解了如何将Spring Boot引入命令。

当然,还有很多事情可以发现。 该库提供了完整的文档。

至于本文的完整代码,可以在我们的GitHub上找到。

 类似资料: