ユーザー定義コマンドのガイド

ユーザー定義コマンドを使用すると、Spring CLI にカスタムコマンドを追加できます。コマンドのディレクトリ構造は、シェルに導入されるコマンドとサブコマンドを表します。

例: controller\new のディレクトリ構造は、CLI ではコマンド controller new に変換されます。

サブコマンドディレクトリにあるファイルは次のとおりです。

  • コマンドとその引数を説明する command.yaml という名前のファイル。

  • コードまたは構成をプロジェクトに追加するために実行するアクションを記述した 1 つ以上のアクションファイル。

ユーザー定義コマンドは、次のコマンドを使用して CLI に登録します。

command add --from <repository-url>

そのリポジトリの内容が既存のプロジェクトにコピーされます。

例: github.com/rd-1-2022/udc-spring-controller (英語) リポジトリの内容を確認します。

構造

すべてのユーザー定義コマンドのディレクトリ構造は、次のパスにあります。

.spring/commands

前述のユーザー定義コマンド controller new の場合、コマンド記述ファイルとアクションファイルが配置される完全なディレクトリ構造は次のようになります。

.spring/commands/controller/new

このディレクトリ内で次を定義できます。

  • コマンドの動作とコマンドの引数を説明する command.yaml ファイル。

  • このコマンドに対して実行するアクションを定義する 1 つ以上のアクションファイル。

例: 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

次のリストは 2 番目の例を示しています。

$ 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 というファイルが現在の作業ディレクトリに生成されます (存在しない場合)。テンプレートの内容にはケバブケースの変数名が含まれています。

user-name 変数と os-name 変数は Java システムプロパティから取得され、テンプレートエンジンに自動的に登録されます。now 変数は、コマンドが実行されたときの new java.util.Date() の値です。

Java コードを作成するためのより現実的な例として、次の 3 つのリストは、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: フィールドは、生成されるファイルの場所を定義します。

生成するファイルがすでに存在する場合、overwrite: という名前の追加フィールドが to: フィールドと同じレベルに追加されない限り、そのファイルは上書きされません。

  • テンプレート化された 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 オプションが渡されます。

便利な組み込み変数の 1 つは root-package-dir です。これは、@SpringApplication アノテーションを含むクラスが配置されるディレクトリです。

テンプレートエンジン

テンプレートエンジンは Handlebars [GitHub] (英語) です。いくつかの 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}} - これは、POM の <properties> セクションの各エントリの値をキーとして持つ Java プロパティオブジェクトです。

  • {{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 という名前のコマンドライン引数が 1 つ含まれています。

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.

さらに学ぶ

アクションガイドでは、アクションファイルで使用できるすべてのオプション (コードと構成をプロジェクトに追加または変更するため) について説明します。