使用者自定義命令指南

使用者自定義命令允許您向 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 的動作檔案及其相關的動作和模板 Java 檔案在 github.com/rd-1-2022/udc-spring-controller 儲存庫中的內容。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。預設註冊了幾個 Handlebars 輔助函式：

在前面的示例中，{{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.

瞭解更多

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

© . This site is unofficial and not affiliated with VMware.