spring shell 基础使用
spring shell 基础使用
简介
Spring Shell 是 Spring 生态系统中用于构建交互式命令行应用（CLI）的框架，基于Spring Boot的自动配置和依赖注入机制，简化了命令行工具的开发。Spring Shell 提供注解驱动的命令开发模型，支持类 Bash 的交互体验，包括：
- 命令自动补全（Tab 键触发）
- 历史命令记录（支持上下键切换）
- 内置帮助系统（help 命令查看所有命令）
- 参数校验与类型转换（集成 Bean Validation）
安装
<!--pom.xml引入-->
<dependency><groupId>org.springframework.shell</groupId><artifactId>spring-shell-starter</artifactId>
</dependency>
接口
CommandExceptionResolver异常处理接口
全类名：org.springframework.shell.command.CommandExceptionResolver
描述：Spring Shell中用于统一处理命令执行过程中抛出的异常的核心接口。它允许开发者自定义异常处理逻辑，包括错误消息格式化、退出码（Exit Code）设置等，从而提升命令行应用的健壮性和用户体验
方法
- public CommandHandlingResult resolve(Exception ex)【强制重写】
CommandRegistration编程式定义命令
全类名：org.springframework.shell.command.CommandRegistration
描述：用于编程式定义命令的核心类，相比注解式（@ShellMethod）提供了更细粒度的控制能力。注意：同一命令不要重复注册。更推荐使用此方法定义命令。
方法
- Builder builder()：返回builder实例
- Builder group(String group)：命令所属“命令组”
- Builder hidden(boolean hidden)：是否隐藏命令，true-隐藏；“隐藏命令”主要用于动态控制命令的可见性与可用性，而非完全禁用或删除命令。该命令仍然可以手动执行，但在help列表中会被隐藏。
- Builder description(String description)：自定义命令描述
- Builder command(String… commands)：自定义命令
- AliasSpec withAlias()：自定义命令别名
- AliasSpec command(String… commands)：自定义命令别名，可指定多个别名
- OptionSpec withOption()：自定义命令参数
- OptionSpec longNames(String… names)：参数长名，如：–name这种全名称参数，编码时不用写–
- OptionSpec shortNames(String… names)：参数短名，如：-n这种缩写参数，编码时不用写-
- OptionSpec description(String description)：参数描述
- OptionSpec required()：参数是否必需，不必需不用加此方法
- OptionSpec type(Type type)：定义参数类型
- Builder and()：条件连接
- TargetSpec withTarget()：命令执行内容的具体实现
- TargetSpec function(Function<CommandContext, ?> function)：方法型
- TargetSpec method(Object bean, Method method)：绑定型
- TargetSpec consumer(Consumer consumer)：消费型
- ExitCodeSpec withExitCode()：自定义退出码
- ExitCodeSpec map(Class<? extends Throwable> e, int code)：指定异常和退出码映射
- CommandRegistration build()：构建命令
ExitCodeGenerator自定义退出码接口
全类名：org.springframework.boot.ExitCodeGenerator
描述：定制命令执行后的退出码（Exit Code），尤其在非交互式（如脚本调用）场景下，通过退出码向调用方传递命令执行状态（成功、失败或特定错误）；如果已通过命令专属退出码映射（使用 CommandRegistration.withExitCode().map()）配置了异常与退出码的绑定，无需额外编写自定义异常类来实现ExitCodeGenerator接口。
方法
- int getExitCode()：定义退出码【强制实现】
类
Availability动态控制命令可用性
全类名：org.springframework.shell.Availability
描述：Availability 是 Spring Shell 框架中用于动态控制命令可用性的核心类。它通过封装命令的可用状态及原因，实现了基于应用内部状态（如用户登录、资源初始化等）的命令启停机制。
注解
@ShellCommandGroup命令分组
全类名：org.springframework.shell.standard.ShellCommandGroup
描述：对命令进行逻辑分组的注解。当应用包含大量命令时（如文件操作、系统管理、网络工具等），@ShellCommandGroup可将功能相关的命令归入同一逻辑组。例如：文件操作命令（ls, touch, rm）归入 File Commands；系统信息命令（sysinfo, memory）归入 System Commands；帮助系统（help 命令）会按分组展示命令，避免杂乱无章的列表
作用范围：TYPE
属性
- String value() default INHERIT_AND_INFER：组名，该值将应用于拥有类或包中的所有命令
@ShellComponent 命令组件
全类名：org.springframework.shell.standard.ShellComponent
描述：标记类为Spring Shell的组件，使其被Spring扫描并注册为命令源
作用范围：TYPE
属性
- String value() default “”;
@ShellMethodAvailability动态控制命令可用性
全类名：org.springframework.shell.standard.ShellMethodAvailability
描述：动态控制命令可用性的核心注解
作用范围：METHOD
属性
- String[] value() default “*”：绑定动态控制方法；支持绑定多个“动态控制”方法
@ExceptionResolver异常处理（v3.0.0已废弃）
全类名：
描述：
@ShellMethod 命令
全类名：org.springframework.shell.standard.ShellMethod
描述：标记方法为命令，以方法名为命令，也可设置命令别名
作用范围：METHOD
属性
- String[] key() default {} 命令别名（支持多个），一旦定义则以key中值为命令，而不是以方法名为命令
- String value() default “” 命令描述（必填）
- String prefix() default “–” 参数前缀（默认–）
- String group() default “” 命令分组（覆盖类分组）
- InteractionMode interactionMode() default InteractionMode.ALL 交互模式
@ShellOption 命令参数
全类名：org.springframework.shell.standard.ShellOption
描述：将方法参数标记为命令参数
作用范围：PARAMETER
属性
- String[] value() default {} 参数别名（短/长格式），如value = {“-n”, “–name”}
- int arity() default ARITY_USE_HEURISTICS：参数值数量（支持数组/集合），如：arity = 3 接收三个值
- String defaultValue() default NONE：默认值（支持 SpEL 表达式），如：defaultValue = “World”
- String help() default “”：参数帮助文本，help = “用户姓名”
- Class<? extends ValueProvider> valueProvider() default NoValueProvider.class：
- boolean optOut() default false：
内置命令
不能自定义如下命令，这些命令由spring shell默认提供
- help：帮助，列出所有分组及每个分组的命令（非隐藏命令）
- clear：清屏，清空当前终端屏幕内容（类似 Linux 的 clear 命令），Ctrl + L 也可触发清屏操作
- exit：退出，退出Spring Shell应用程序；exit和quit互为别名，效果相同
- stacktrace：显示上一次命令执行错误的完整堆栈跟踪信息（默认仅显示简略错误信息）
- script：从文件批量读取并执行命令，如：script /path/to/file（需绝对路径）
- history：命令历史，显示当前会话中执行过的命令历史记录
- completion：启用Tab 键自动补全命令名称和参数（需终端支持）
- version：查看版本，显示当前Spring Shell的版本号（我尝试无输出）
范例
使用注解式创建命令
import org.jline.reader.LineReader;
import org.jline.reader.LineReaderBuilder;
import org.jline.terminal.Terminal;
import org.springframework.shell.Availability;
import org.springframework.shell.standard.*;import java.util.Arrays;
import java.util.List;@ShellComponent
@ShellCommandGroup("ca")
public class DemoCommand {private boolean available = false;private final Terminal terminal;public HelloCommand(Terminal terminal) {this.terminal = terminal;}@ShellMethod(key = {"login"},value = "登录")public String hello() {LineReader reader = LineReaderBuilder.builder().terminal(terminal).build();String name = reader.readLine("请输入用户名:");String password = reader.readLine("请输入密码:",'*');if(name.equal("admin") && password.equal("123456"))return "登录成功";elsereturn "用户名或密码错误";}@ShellMethod(key = {"addition","add"},value = "计算数据之和")@ShellMethodAvailability("isAvailable")public Integer addition(@ShellOption(help = "计算参数",value = {"--Parameters","-p"}) String parameters) {List<Integer> list = Arrays.stream(parameters.split(",")).toList().stream().map(Integer::parseInt).toList();int sum = 0;for (int parameter : list) {sum += parameter;}return sum;}public Availability isAvailable() {return available?Availability.available():Availability.unavailable("命令不可用");}
}
使用编程式创建命令
import cn.sshell.springshelltrain.command.HelloCommand;
import cn.sshell.springshelltrain.exception.CustomExceptionResolver;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.shell.command.CommandExceptionResolver;
import org.springframework.shell.command.CommandRegistration;@Configuration
public class CommandConfig {@Beanpublic CommandRegistration subCommand() {return CommandRegistration.builder().hidden(false)//不隐藏此命令.group("ca")//命令组.description("数据相减")//命令描述.command("sub")//命令名称.withAlias().command("subtract")//命令别名.and().withOption().longNames("a").description("计算参数").required().type(Integer.class)//命令参数.and().withOption().longNames("b").description("计算参数").required().type(Integer.class)//命令参数.and().withTarget().function(ctx -> {//获取命令参数Integer a = (Integer) ctx.getOptionValue("a");Integer b = (Integer) ctx.getOptionValue("b");System.out.println(a+"减去"+b);return a-b;//返回结果}).and().withExitCode()//设置退出码.map(IllegalArgumentException.class, 1).map(TypeNotPresentException.class,2).and().build();//构建命令}
}
spring shell还有诸多功能，后面抽空再接着写