4. 命令
在本节中，我们将介绍实际的命令注册并保留命令选项 和执行以供稍后在文档中执行。您可以在 命令注册 中找到更多详细信息。
4.1. 注册
有两种不同的方法可以定义命令：通过注释模型和 通过编程模型。在 Comments 模型中，定义方法 ，并使用特定注释对类和方法进行注释。 在编程模型中，使用一种更底层的方法，定义命令 注册（作为 Bean 或通过动态注册到命令目录）。
4.1.1. 标注模型
当您使用标准 API 时，bean 上的方法将转换为可执行命令，前提是：
-
Bean 类带有
@ShellComponent注解。（这用于限制 bean 的集合 被考虑的。 -
该方法带有
@ShellMethod注解。
|
这 您可以使用 |
@ShellComponent
static class MyCommands {
@ShellMethod
public void mycommand() {
}
}
的唯一 required 属性@ShellMethodannotation 是其value属性，该属性应具有
一个简短的一句话描述，说明命令的作用。这样，您的用户就可以
无需离开 shell 即可获得有关命令的一致帮助（请参阅帮助）。
| 命令的描述应该简短 — 不超过一两句话。为了更好 consistency，它应该以大写字母开头，以句点结尾。 |
默认情况下，您无需指定命令的键（即应使用的单词）
在 shell 中调用它）。方法的名称用作 command 键，将 camelCase 名称转换为
虚线、GNU 样式、名称（例如sayHello()成为say-hello).
但是，您可以使用key注解的属性：
@ShellMethod(value = "Add numbers.", key = "sum")
public int add(int a, int b) {
return a + b;
}
这key属性接受多个值。
如果为单个方法设置多个键，则命令将使用这些不同的别名注册。 |
| Command 键几乎可以包含任何字符，包括空格。不过，在想出名字时， 请记住，一致性通常受到用户的赞赏。也就是说，您应该避免将虚线名称与 带空格的名称和其他不一致。 |
4.2. 组织命令
当你的 shell 开始提供大量功能时，你最终可能会遇到
使用大量命令，这可能会让您的用户感到困惑。通过键入help,
他们会看到一个令人生畏的命令列表，按字母顺序排列，
这可能并不总是显示可用命令的最佳方式。
为了减少这种可能的混淆， Spring Shell 提供了将命令分组在一起的能力。
具有合理的默认值。然后，相关命令将位于同一组中（例如User Management Commands)
并一起显示在帮助屏幕和其他地方。
默认情况下，命令根据它们在其中实现的类进行分组。
将 camelCase 类名转换为单独的单词（因此URLRelatedCommands成为URL Related Commands).
这是一个明智的默认值，因为相关命令通常已经在类中了。
，因为他们需要使用相同的协作对象。
但是，如果此行为不适合您，则可以将组替换为 命令，按优先级顺序排列：
-
指定
group()在@ShellMethod注解。 -
放置
@ShellCommandGroup在定义命令的类上。这适用 该类中定义的所有命令的组（除非被覆盖，如前所述）。 -
放置
@ShellCommandGroup在包上（通过package-info.java) 其中定义了命令。这适用于 package 中（除非在方法或类级别被覆盖，如前所述）。
下面的清单显示了一个示例：
public class UserCommands {
@ShellMethod(value = "This command ends up in the 'User Commands' group")
public void foo() {}
@ShellMethod(value = "This command ends up in the 'Other Commands' group",
group = "Other Commands")
public void bar() {}
}
...
@ShellCommandGroup("Other Commands")
public class SomeCommands {
@ShellMethod(value = "This one is in 'Other Commands'")
public void wizz() {}
@ShellMethod(value = "And this one is 'Yet Another Group'",
group = "Yet Another Group")
public void last() {}
}
4.3. 动态命令可用性
由于应用程序的内部状态，注册的命令并不总是有意义。
例如，可能有一个download命令，但只有在用户使用了connect在远程
服务器。现在，如果用户尝试使用download命令，shell 应该解释
命令存在，但当时不可用。
Spring Shell 允许你这样做，甚至允许你提供
命令不可用。
命令有三种可能的方式来指示可用性。
它们都使用一个 no-arg 方法，该方法返回一个Availability.
请考虑以下示例：
@ShellComponent
public class MyCommands {
private boolean connected;
@ShellMethod("Connect to the server.")
public void connect(String user, String password) {
[...]
connected = true;
}
@ShellMethod("Download the nuclear codes.")
public void download() {
[...]
}
public Availability downloadAvailability() {
return connected
? Availability.available()
: Availability.unavailable("you are not connected");
}
}
这connectmethod 连接到服务器（省略细节），从而更改状态
的命令中connectedboolean 值。
这download命令标记为不可用，直到用户已连接，这要归功于
与名称完全相同的方法downloadcommand 方法替换为Availabilitysuffix 在其名称中。
该方法返回Availability，使用两种工厂方法之一构造。
如果该命令不可用，则必须提供解释。
现在，如果用户尝试在未连接的情况下调用命令，则情况如下：
shell:>download
Command 'download' exists but is not currently available because you are not connected.
Details of the error have been omitted. You can use the stacktrace command to print the full stacktrace.集成帮助中还使用了有关当前不可用命令的信息。请参阅帮助。
|
如果将命令不可用时提供的原因附加到 “Because” 之后，则应该读起来很不错。 您不应以大写字母开头或添加最后一个句点 |
如果在命令方法名称后命名 availability 方法不适合您，您可以
可以使用@ShellMethodAvailability注解：
@ShellMethod("Download the nuclear codes.")
@ShellMethodAvailability("availabilityCheck") (1)
public void download() {
[...]
}
public Availability availabilityCheck() { (1)
return connected
? Availability.available()
: Availability.unavailable("you are not connected");
}
| 1 | 名称必须匹配 |
最后，通常情况下，同一类中的多个命令共享相同的内部状态，因此，
应全部作为一个组可用或不可用。不必粘贴@ShellMethodAvailability在所有命令方法上，Spring Shell 都允许您翻转事物并将@ShellMethodAvailabilty注解，指定它控制的命令的名称：
@ShellMethod("Download the nuclear codes.")
public void download() {
[...]
}
@ShellMethod("Disconnect from the server.")
public void disconnect() {
[...]
}
@ShellMethodAvailability({"download", "disconnect"})
public Availability availabilityCheck() {
return connected
? Availability.available()
: Availability.unavailable("you are not connected");
}
|
的 |
| Spring Shell 对如何编写命令和如何组织类没有施加很多约束。 但是，将相关命令放在同一个类中通常是一种很好的做法，并且可用性指示符 可以从中受益。 |
4.4. 退出代码
许多命令行应用程序（如果适用）会返回运行环境的退出代码
可用于区分命令是否已成功执行。在spring-shell这主要与命令在非交互模式下运行时（即一个命令）有关
总是使用spring-shell.
退出代码的默认行为如下：
-
命令选项解析中的错误将导致代码为
2 -
任何一般错误都会导致结果代码为
1 -
显然，在任何其他情况下，结果代码都是
0
每CommandRegistration可以在 Exception 和退出代码之间定义自己的映射。
本质上，我们被Spring Boot关于退出代码，简单地
融入其中。
假设下面有一个异常 show ，它将从命令中抛出：
static class MyException extends RuntimeException {
private final int code;
MyException(String msg, int code) {
super(msg);
this.code = code;
}
public int getCode() {
return code;
}
}
可以在Throwable和退出代码。您还可以
只需配置一个类以退出代码，这只是配置中的语法糖。
CommandRegistration.builder()
.withExitCode()
.map(MyException.class, 3)
.map(t -> {
if (t instanceof MyException) {
return ((MyException) t).getCode();
}
return 0;
})
.and()
.build();
| 无法使用基于注释的配置自定义退出代码 |