用户定义命令指南

用户定义命令允许您向 Spring CLI 添加自定义命令。命令的目录结构代表了引入到 shell 中的命令和子命令。

例如，目录结构 `controller\new` 在 CLI 中转化为命令 `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]

操作文件

操作文件的结构类似于 GitHub 操作文件。

操作文件可以随意命名。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.java

`to:` 字段定义要生成文件的位置。

如果待生成文件已存在，则不会覆盖，除非在与 `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 helper

在前面的示例中，模板变量 `{{capitalizeFirst feature}}` 是使用 Handlebars helper 的一个示例。

默认情况下，几个系统变量暴露给模板引擎

  • `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.

了解更多

操作指南 描述了您可以在操作文件中使用的所有可用选项（用于向项目添加或修改代码和配置）。