最新の安定バージョンについては、Spring Cli 0.9.0 を使用してください！

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

ユーザー定義コマンドを使用すると、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 にすることができます。

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 アクションファイルと同様に構造化されています。

Acitons ファイルには任意の名前を付けることができ、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 コードを作成するためのより現実的な例として、リポジトリ github.com/rd-1-2022/udc-spring-controller (英語) 内の 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

  • テンプレート化された Java ファイル

ファイル RestController.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}}";
	}
}

to: フィールドは、生成されるファイルの場所を定義します。

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

すべてのコマンドライン引数は、変数 (この場合は feature オプション) としてテンプレートエンジンに渡されます。

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

テンプレートエンジン

テンプレートエンジンは Handlebars [GitHub] (英語) です。いくつかの Handlebar ヘルパーがデフォルトで登録されています

前の例では、テンプレート変数 {{capitalizeFirst feature}} は Handlebar ヘルパーの使用例です。

いくつかのシステム変数がデフォルトでテンプレートエンジンに公開されます。

  • 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}} - これにより、java.version という名前の POM で 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.

さらに学ぶ

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