提到命令行程序，很多人的第一反应是 Python 脚本或者 Go 编译出来的单个二进制文件。其实在 Java 生态里，Spring Shell 提供了一套相当优雅的方案：把一个普通方法通过注解变成可执行的命令，参数解析、类型转换、Tab 补全都由框架包办。再借助 Spring Boot 的自动装配和依赖注入能力，一个 CLI 工具也能拥有和 Web 应用一样的分层架构。这篇文章就从整合原理讲到落地实践，把关键步骤和容易踩的坑都过一遍。
一、为什么选 Spring Shell，先搞清楚启动模型的差异
Spring Boot 默认的启动方式是启动一个 Servlet 容器或者响应式服务器，监听端口等待请求。而命令行应用的生命周期完全不同：进程启动、读取用户输入、执行命令、然后可能退出。两者整合时最核心的问题，就是让 Spring Boot 的 ApplicationContext 以非 Web 方式运行，并把控制权交给 Spring Shell 的交互循环。
好在 Spring Boot 天生支持这种模式。当 classpath 下没有 Web 相关依赖时，ApplicationContext 会自动降级为非 Web 上下文，应用启动完成后 main 方法自然返回。Spring Shell 2.x 之后全面拥抱 Spring Boot，提供了专门的 starter，引入依赖后它会通过自动装配注册 ShellRunner，接管标准输入输出流，进入 REPL 循环（Read-Eval-Print Loop）。也就是说，整合工作在依赖层面基本就完成了，剩下的是如何优雅地编写命令。
需要注意版本匹配。Spring Shell 2.x 对应 Spring Boot 2.x 系列，Spring Shell 3.x 则要求 Spring Boot 3.x 和 JDK 17。混用版本会直接抛出 ClassNotFoundException 或者 Bean 定义缺失的异常，这是新手最常遇到的问题之一。
二、搭建工程并编写第一个命令
先建一个普通的 Spring Boot 工程，在 pom.xml 中引入 spring-shell-starter，同时建议把 spring-boot-starter-web 排除掉，避免应用启动多余的端口监听：
<dependency>
<groupId>org.springframework.shell</groupId>
<artifactId>spring-shell-starter</artifactId>
<version>3.2.0</version>
</dependency>接下来编写命令类。Spring Shell 的核心注解是 @ShellComponent 和 @ShellMethod，前者标记该类会被扫描为命令提供者，后者把一个普通方法注册为命令。看一个完整示例：
import org.springframework.shell.standard.ShellComponent;
import org.springframework.shell.standard.ShellMethod;
import org.springframework.shell.standard.ShellOption;
@ShellComponent
public class GreetCommands {
@ShellMethod(value = "向指定用户打招呼", key = "greet")
public String greet(
@ShellOption(defaultValue = "world") String name) {
return "Hello, " + name + "!";
}
}启动应用后会看到 shell 提示符，输入 greet 或 greet --name 张三 即可执行。几个细节值得说明：key 属性用于自定义命令名，不指定时方法名就是命令名；@ShellOption 的 defaultValue 让参数可以省略；参数默认按顺序绑定，但推荐使用 --name 显式传参，可读性更好。此外 Spring Shell 内置了 help、clear、exit 等命令，直接输入 help 可以查看所有已注册的命令和用法说明，完全不需要自己写帮助文档。
命令方法完全可以注入任何 Spring Bean。比如你有一个配置好的 RestTemplate、JdbcTemplate 或者业务 Service，直接 @Autowired 进来就能用，这是 Spring Shell 相比手写 BufferedReader 循环最大的优势，命令层薄、业务逻辑全部复用既有代码。
三、进阶用法：参数校验、自定义提示符与生命周期控制
真实项目里的 CLI 工具离不开输入校验和交互体验优化。Spring Shell 对 JSR-303 校验注解做了原生支持，在方法参数上加 @NotNull、@Size 等注解，非法输入会被拦截并给出友好提示：
@ShellComponent
public class UserCommands {
@ShellMethod("创建用户")
public String createUser(
@ShellOption @Size(min = 2, max = 20) String username,
@ShellOption(defaultValue = "false") boolean admin) {
return "用户 " + username + " 创建成功，管理员标志：" + admin;
}
}想让提示符更有辨识度，可以实现 Provider<PromptProvider> 接口来自定义。自定义异常处理则可以实现 CommandNotFoundResolver，把未知命令映射到提示信息而不是冷冰冰的堆栈。这些扩展点都是标准的 Spring Bean，注册进容器即可生效。
退出控制也是一个高频需求。默认情况下应用启动后会一直等待输入，输入 exit 退出。如果希望程序执行完任务后自动退出，比如做成批处理脚本调用，可以在 application.properties 中设置 spring.shell.interactive.enabled=false，然后通过命令行参数 spring.shell.run.script 或直接用 ApplicationRunner 执行一段逻辑后调用 System.exit。交互模式与脚本模式的切换，让同一个 jar 既能当 REPL 工具用，也能当一次性任务脚本用，非常灵活。
四、打包发布与常见问题排查
打包直接用 spring-boot-maven-plugin 生成可执行 jar 即可。为了方便使用，可以写一个简单的启动脚本：
#!/bin/bash java -jar my-cli-tool.jar "$@"
使用过程中有几个坑提前说清楚。第一，如果 classpath 里混入了 web 依赖，应用会启动 Tomcat 导致行为异常，用 mvn dependency:tree 检查并排除。第二，命令中文乱码通常是 JVM 编码问题，启动时加上 -Dfile.encoding=UTF-8 即可解决。第三，多个命令类中如果出现相同的 key，启动时会直接报重复命令冲突，命名时建议采用 模块:动作 的风格，比如 user:create、user:delete，既避免冲突又自带分组效果，help 输出时同组命令会归拢在一起展示。
最后一点经验：命令方法应该保持轻量，耗时操作放到后台线程执行或者给出进度提示，因为命令是在 REPL 主线程同步执行的，一个长命令会阻塞整个交互会话。把输入校验、输出格式化、错误处理都封装好之后，一个工程化的命令行工具就成型了，后续新增功能只需要添加新的 @ShellComponent，维护成本非常低。
Spring BootSpring Shell命令行应用修改时间：2026-09-08 13:39:01