spring shell 基础使用

简介

Spring Shell 是 Spring 生态系统中用于构建交互式命令行应用（CLI）的框架，基于Spring Boot的自动配置和依赖注入机制，简化了命令行工具的开发。Spring Shell 提供注解驱动的命令开发模型，支持类 Bash 的交互体验，包括：

命令自动补全（Tab 键触发）
历史命令记录（支持上下键切换）
内置帮助系统（help 命令查看所有命令）
参数校验与类型转换（集成 Bean Validation）

安装

xml 复制代码

<!--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的版本号（我尝试无输出）

范例

使用注解式创建命令

java 复制代码

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 "登录成功";
        else
        	return "用户名或密码错误";
    }

    @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("命令不可用");
    }
}

使用编程式创建命令

java 复制代码

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 {
    @Bean
    public 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 还有诸多功能，后面抽空再接着写