用户自定义命令指南
用户自定义命令允许您向 Spring CLI 添加自定义命令。 命令的目录结构代表了引入到 Shell 中的命令和子命令。
例如，controller\new 的目录结构在命令行界面中对应命令 controller new。
位于子命令目录中的文件是：
-
一个名为
command.yaml的文件，用于描述命令及其参数。 -
一个或多个操作文件，用于描述向项目添加代码或配置所需执行的操作。
用户自定义命令通过以下命令注册到 CLI：
command add --from <repository-url>该仓库的内容将被复制到您现有的项目中。
例如，查看 github.com/rd-1-2022/udc-spring-controller 仓库的内容。
结构
所有用户自定义命令的目录结构位于以下路径：
.spring/commands因此，对于前面提到的用户自定义命令 controller new，存放命令描述文件和操作文件的完整目录结构如下：
.spring/commands/controller/new在此目录中，您可以定义：
-
command.yaml文件描述了命令的作用以及命令的参数。 -
一个或多个定义此命令要执行的操作的操作文件。
例如，github.com/rd-1-2022/udc-spring-controller 仓库的目录内容如下：
.
├── README.adoc
└── .spring
└── commands
└── controller
└── new
├── command.yaml
├── create-controller.yaml
└── RestController.java描述命令
前面提到的 controller new 命令对应的 command.yaml 文件内容如下：
command:
description: Generate a new Spring Controller
options:
#
- name: feature
description: name of the feature package
dataType: string
defaultValue: person
inputType: text
required: true该文件包含命令的简要描述和命令行选项数组。
选项的 name 是必需的。默认 dataType 为 string。
dataType 可以是 int、integer、bool、boolean、double、float、long、short 或 string。
Spring CLI 在运行时集成了这些命令，它们在请求常规帮助和特定命令帮助时会显示出来。 以下列表展示了一个示例：
$spring help
<output truncated>
User-defined Commands
controller new: Generate a new Spring Controller以下列表展示了第二个示例：
$ spring help controller new
NAME
controller new - Generate a new Spring Controller
SYNOPSIS
controller new --feature String
OPTIONS
--feature String
name of the feature package
[Optional, default = person]操作文件
Action 文件的结构与 GitHub Action 文件类似。
Action 文件可以命名为您喜欢的任何名称。CLI 会查找扩展名为 .yaml 和 .yml 的文件。
您可以拥有任意数量的操作文件以完成特定任务。操作文件的执行顺序是先深度优先，然后按字母顺序。
以下列表展示了一个简单的示例：
actions:
- generate:
to: hello.txt
text: Hello at {{now}} on {{os-name}}.此操作会在当前工作目录中生成一个名为 hello.txt 的文件（如果该文件尚不存在）。
模板内容包含短横线分隔（kebab-case）的变量名。
user-name 和 os-name 变量来自 Java 系统属性，并自动注册到模板引擎中。
now 变量是运行命令时 new java.util.Date() 的值。
作为一个更真实的创建 Java 代码的示例，以下三个清单展示了名为 Controller.java 的操作文件的内容，以及其在仓库 github.com/rd-1-2022/udc-spring-controller 中相关的操作和模板化 Java 文件。
feature 变量是一个命令选项。
-
命令文件
command:
description: Generate a new Spring Controller
options:
#
- name: feature
description: name of the feature package
dataType: string
defaultValue: person
inputType: text-
操作文件
actions:
- generate:
to: src/main/java/{{root-package-dir}}/{{feature}}/{{capitalizeFirst feature}}Controller.java
from: RestController.javato: 字段定义了要生成的文件的位置。
如果待生成的文件已存在，则不会覆盖它，除非在与 to: 字段相同的层级上添加一个名为 overwrite: 的额外字段。
-
模板化 Java 文件
package {{root-package}}.{{feature}};
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class {{capitalizeFirst feature}}Controller {
@GetMapping("/{{feature}}")
public String greeting() {
return "Hello {{feature}}";
}
}所有命令行参数都会作为变量传递给模板引擎。在此情况下，传递的是 feature 选项。
一个有用的内置变量是root-package-dir，它是包含@SpringApplication注解的类所在的目录。
模板引擎
模板引擎是 Handlebars。 默认注册了多个 Handlebar 辅助函数。
在前面的示例中，{{capitalizeFirst feature}} 模板变量是使用 Handlebars 辅助函数的一个示例。
默认情况下，多个系统变量会暴露给模板引擎：
-
System.getProperties()可作为{{system-properties}}使用 -
System.getenv()可作为{{system-environment}}使用 -
当前时间（由
new Date().toString()定义）可作为{{now}}获取 -
java.io.tmpdir系统属性可作为{{tmp-dir}}使用 -
file.separator系统属性可作为{{file-separator}}*os.name系统属性可作为{{os-name}} -
user.name系统属性可作为{\{user.name}}使用
Spring Boot 主应用程序类所在的 Java 包名可作为{{root-package}}使用。
Spring Boot 主应用程序类所在的目录可作为{{root-package-dir}}使用。
Maven 模型还暴露了几个变量：
-
{{artifact-id}} -
{{artifact-version}} -
{{artifact-path}} -
{{project-name}} -
{{project-descriptoin}} -
{{maven-model}}- 这是 org.apache.maven.model.Model 类。 -
{{maven-properties}}- 这是一个 Java Properties 对象，其键为 POM 文件中<properties>部分各条目的值。 -
{{java-version}}- 这会在 POM 中查找名为java.version的 Maven 属性。如果其值为1.8，则会被转换为8。
创建新的用户自定义命令
一个简单的入门方法是运行以下命令：
spring command new hello create这将创建一个名为 hello 的用户自定义命令，并包含一个名为 create 的子命令。
您可以通过运行 spring command new --help 查看 spring command new 的完整选项集。
以下列表显示了输出结果：
$ spring command new --help
NAME
command new - Create a new user-defined command
SYNOPSIS
command new --commandName String --subCommandName String --path String --help
OPTIONS
--commandName String
The name of the user-defined command to create
[Optional, default = hello]
--subCommandName String
The name of the user-defined sub-command to create
[Optional, default = new]
--path String
Path to execute command in
[Optional]
--help or -h
help for command new
[Optional]运行 spring command new hello create 会生成以下目录结构和文件。
.
├── README.adoc
└── .spring
└── commands
└── hello
└── create
├── command.yaml
└── hello.yaml以下列表显示了 command.yaml 文件的内容。它包含一个名为 greeting 的命令行参数。
command:
description: Generate a new file with a hello message
options:
#
- name: greeting
description: who or what to say hello to
dataType: string
defaultValue: World
inputType: text # TEXT以下列表展示了名为 hello.yaml 的操作文件。它会生成名为 hello.txt 的文件。
actions:
- generate:
to: hello.txt
text: Hello {{greeting}} at {{now}} on {{os-name}}.运行 spring help 命令时，该命令列在 User-defined Commands 标题下。
...
User-defined Commands
hello create: Generate a new file with a hello message运行 spring hello create 命令会生成包含以下内容的 hello.txt 文件：
Hello World at Mar 9, 2023 on Linux.了解更多
操作指南描述了您在操作文件中可使用的所有选项（用于向项目添加或修改代码和配置）。