Guide to User-defined Commands

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

User-defined commands let you add custom commands to the Spring CLI. The directory structure for commands represents the command and sub-command that are introduced into the shell.

例如，controller\new 的目录结构在 CLI 中会转换为命令 controller new。

For example, the directory structure of controller\new translates to the command controller new in the CLI.

位于子命令目录的文件有：

The files located in the sub-command directory are:

  • A file named command.yaml that describes the command and its arguments.

  • One or more action files that describe the actions to take to add code or configuration to the project.

用户定义的命令使用以下命令向 CLI 注册：

User-defined commands are registered with the CLI by using the following command:

command add --from <repository-url>

该存储库的内容将复制到您现有的项目中。

The contents of that repository are copied into your existing project.

例如，查看 [role="bare"][role="bare"]https://github.com/rd-1-2022/udc-spring-controller 存储库的内容。

For example, look at the contents of the [role="bare"]https://github.com/rd-1-2022/udc-spring-controller repository.

Structure

所有用户定义命令的目录结构位于以下路径下：

The directory structure for all user-defined commands are under the following path:

.spring/commands

因此，对于前面提到的用户定义命令 controller new 来说，其中存放着命令描述文件和操作文件的完整目录结构为：

So, for the user defined command, controller new, mentioned previously, the full directory structure where the command description file and action files are located would be:

.spring/commands/controller/new

在此目录中，您可以定义：

Inside this directory, you can define:

  • The command.yaml file that describes what the command does and the arguments of the command.

  • One or more action files that define the actions to run for this command.

例如，[role="bare"][role="bare"]https://github.com/rd-1-2022/udc-spring-controller 存储库的目录内容如下：

For example, the directory contents of the [role="bare"]https://github.com/rd-1-2022/udc-spring-controller repository are as follows:

.
├── README.adoc
└── .spring
    └── commands
        └── controller
            └── new
                ├── command.yaml
                ├── create-controller.yaml
                └── RestController.java

Describing the Command

此前提到的 controller new 命令的 command.yaml 文件内容如下：

The contents of the command.yaml file for the controller new command mentioned previously are as follows:

command:
  description: Generate a new Spring Controller
  options:
    #
    - name: feature
      description: name of the feature package
      dataType: string
      defaultValue: person
      inputType: text
      required: true

该文件包含命令的简要说明和一系列命令行选项。

The file contains a brief description of the command and an array of command line options.

选项的 name 是必需的。默认 dataType 是 string。

The name of the options is required. The default dataType is string.

dataType 可以是 int、integer、bool、boolean、double、float、long、short 或 string。

The dataType can be int, integer, bool, boolean, double, float, long, short, or string.

Spring CLI 在运行时合并这些命令，当向其询问通用帮助以及特定命令的帮助时，它们便会出现。以下清单展示了一个示例：

Spring CLI incorporates these commands at runtime, and they appear when asking for general help and command-specific help. The following listing shows an example:

$spring help

<output truncated>

User-defined Commands
       controller new: Generate a new Spring Controller

以下清单展示了第二个示例：

The following listing show a second example:

$ 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 Files

操作文件构建方式与 GitHub 操作文件类似。

Action files are structured similarly to GitHub action files.

操作文件可以自定义命名。CLI 查找带有 .yaml 和 .yml 文件扩展名的文件。

Action files can be named anything you like. The CLI looks for files with .yaml and .yml file extensions.

可以根据自己需要创建任意数量的操作文件来完成特定任务。操作文件运行的顺序是深度优先，然后是按字母顺序。

There can be as many action files as you need to accomplish a specific task. The order in which action files are run is depth-first and then alphabetical.

以下清单展示了一个简单的示例：

The following listing shows a simple example:

actions:
  - generate:
      to: hello.txt
      text: Hello at {{now}} on {{os-name}}.

此操作在当前工作目录中生成一个名为 hello.txt 的文件（如果该文件还不存在）。模板内容包含连字符分隔的变量名。

This action generates a file called hello.txt, if it does not already exist, in the current working directory. The template contents contain kebab-case variable names.

user-name 和 os-name 变量来自 Java 系统属性，并且会自动在模板引擎中进行注册。now 变量是在运行命令时 new java.util.Date() 的值。

The user-name and os-name variables come from Java system properties and are automatically registered with the template engine. The now variable is the value of new java.util.Date() when the command was run.

作为一个更真实的创建 Java 代码的示例，以下三个清单显示了名为 Controller.java 的动作文件的目录内容及其在存储库 [role="bare"][role="bare"]https://github.com/rd-1-2022/udc-spring-controller 中的相关动作和模板化 Java 文件。feature 变量是一个命令选项。

As a more realistic example to create Java code, the following three listings show the contents of the action file named Controller.java and its related action and templated Java files in the repository [role="bare"]https://github.com/rd-1-2022/udc-spring-controller. The feature variable is a command option.

  • Command File

command:
  description: Generate a new Spring Controller
  options:
    #
    - name: feature
      description: name of the feature package
      dataType: string
      defaultValue: person
      inputType: text

  • Action File

actions:
  - generate:
      to: src/main/java/{{root-package-dir}}/{{feature}}/{{capitalizeFirst feature}}Controller.java
      from: RestController.java

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

The to: field defines the location of the file to be generated.

如果待生成文件已经存在，则不会覆盖它，除非在与 to: 字段同一级添加了一个名为 overwrite: 的其他字段。

If the file to generate already exists, it is not overwritten unless an additional field named overwrite: is added at the same level as the to: field.

  • Templated Java File

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 选项。

All command-line arguments are passed to the template engine as variables. In this case, the feature option is passed.

一个有用的内置变量是 root-package-dir，它是包含 @SpringApplication 注解的类的目录。

One useful built-in variable is root-package-dir, which is the directory where the class containing the @SpringApplication annotation is located.

Template Engine

模板引擎为 Handlebars。默认情况下，已注册多个 Handlebars 助手。

The template engine is Handlebars. Several Handlebar helpers are registered by default

在前面的示例中，{{capitalizeFirst feature}} 模板变量是使用 Handlebars 辅助功能的示例。

In the previous example, the {{capitalizeFirst feature}} template variable is an example of using a Handlebars helper.

默认情况下，会向模板引擎公开几个系统变量：

By default, several system variables are exposed to the template engine:

  • System.getProperties() is available as {{system-properties}}

  • System.getenv() is available as {{system-environment}}

  • The current time (defined by new Date().toString()) is available as {{now}}

  • The java.io.tmpdir system property is available as {{tmp-dir}}

  • The file.separator system property is available as {{file-separator}}* The os.name system property is available as {{os-name}}

  • The user.name system property is available as {{user.name}}

驻留 Spring Boot 主应用程序类的 Java 包名称作为 {{root-package}} 提供。

The Java package name where the Spring Boot main application class resides is available as {{root-package}}.

驻留 Spring Boot 主应用程序类的目录作为 {{root-package-dir}} 提供。

The directory where the Spring Boot main application class resides is available as {{root-package-dir}}.

Maven 模型还公开了几个变量：

The Maven model also exposes several variables:

  • {{artifact-id}}

  • {{artifact-version}}

  • {{artifact-path}}

  • {{project-name}}

  • {{project-descriptoin}}

  • {{maven-model} - This is the org.apache.maven.model.Model class.

  • {{maven-properties}} - This is a Java properties object that has, as keys, the values of each entry in the POM’s <properties> section.

  • {{java-version}} - This looks for a Maven Property named java.version in the POM. If the value is 1.8, it is converted to a value of 8.

Creating a New User-defined Command

一个简单的入门方法是运行以下命令：

A simple way to get started is to run the following command:

spring command new hello create

这会创建一个名为 hello 的用户定义命令，其中包含一个名为 create 的子命令。

This creates a user-defined command named hello with a sub-command named create.

可以通过运行 spring command new --help 来查看 spring command new 的完整选项集。以下清单显示输出：

You can view the full set of options for spring command new by running spring command new --help. The following listing shows the output is:

$ 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 会生成以下目录结构和文件。

Running spring command new hello create generates the following directory structure and files.

.
├── README.adoc
└── .spring
    └── commands
        └── hello
            └── create
                ├── command.yaml
                └── hello.yaml

以下清单显示 command.yaml 文件的内容。它包含一个名为 greeting 的命令行参数。

The following listing shows the contents of the command.yaml file. It contains one command line argument, named 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 的文件

The following listing shows the action file named hello.yaml. It generates the file named hello.txt

actions:
  - generate:
      to: hello.txt
      text: Hello {{greeting}} at {{now}} on {{os-name}}.

当您运行 spring help 命令时，该命令会列在 自定义命令 标题下。

The command is listed under the User-defined Commands heading when you run the spring help command.

...
User-defined Commands
       hello create: Generate a new file with a hello message

运行 spring hello create 命令会生成 hello.txt 文件，其中包含以下内容：

Running the spring hello create command generates the hello.txt file with the following contents:

Hello World at Mar 9, 2023 on Linux.

Learning more

Action Guide 描述了可在动作文件中（添加或修改项目中的代码和配置）使用的所有可用选项。

The Action Guide describes all the options available for you to use in action files (to add or modify code and configuration to a project).