使用者定義命令指南

使用者定義命令可讓您將自訂命令新增至 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 程式碼的更實際範例，以下三個清單顯示儲存庫 github.com/rd-1-2022/udc-spring-controller 中名為 `Controller.java` 的動作檔案及其相關動作和範本化 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 輔助程式

在先前的範例中，`{{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.

了解更多

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