使用者定義命令指南

使用者定義命令允許您向 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.

瞭解更多

操作指南描述了您可以在操作檔案中使用的所有可用選項（用於向專案新增或修改程式碼和配置）。