Spring Boot CLI 2.6.3 - リファレンスドキュメント

Spring Boot CLI は、Spring アプリケーションを迅速に開発する場合に使用できるコマンドラインツールです。これにより、Groovy スクリプトを実行できます。つまり、ボイラープレートコードをあまり使用せずに、使い慣れた Java のような構文を使用できます。新しいプロジェクトをブートストラップしたり、独自のコマンドを記述したりすることもできます。

1. CLI のインストール

Spring Boot CLI（コマンドラインインターフェース）は、SDKMAN!（SDK マネージャー）を使用するか、OSG ユーザーの場合は Homebrew または MacPorts を使用して手動でインストールできます。包括的なインストール手順については、「入門」セクションの getting-started.html を参照してください。

2. CLI を使用する

CLI をインストールしたら、spring と入力してコマンドラインで Enter キーを押すと、CLI を実行できます。引数なしで spring を実行すると、次のようなヘルプ画面が表示されます。

$ spring
usage: spring [--help] [--version]
       <command> [<args>]

Available commands are:

  run [options] <files> [--] [args]
    Run a spring groovy script

  _... more command help is shown here_

次の例に示すように、spring help と入力して、サポートされているコマンドの詳細を取得できます。

$ spring help run
spring run - Run a spring groovy script

usage: spring run [options] <files> [--] [args]

Option                     Description
------                     -----------
--autoconfigure [Boolean]  Add autoconfigure compiler
                             transformations (default: true)
--classpath, -cp           Additional classpath entries
--no-guess-dependencies    Do not attempt to guess dependencies
--no-guess-imports         Do not attempt to guess imports
-q, --quiet                Quiet logging
-v, --verbose              Verbose logging of dependency
                             resolution
--watch                    Watch the specified file for changes

version コマンドを使用すると、次のように、使用している Spring Boot のバージョンを簡単に確認できます。

$ spring version
Spring CLI v2.6.3

2.1. CLI を使用したアプリケーションの実行

run コマンドを使用して、Groovy ソースコードをコンパイルおよび実行できます。Spring Boot CLI は完全に自己完結型であるため、外部 Groovy をインストールする必要はありません。

次の例は、Groovy で記述された "hello world" Web アプリケーションを示しています。

hello.groovy

@RestController
class WebApplication {

    @RequestMapping("/")
    String home() {
        "Hello World!"
    }

}

アプリケーションをコンパイルして実行するには、次のコマンドを入力します。

$ spring run hello.groovy

コマンドライン引数をアプリケーションに渡すには、次の例に示すように、-- を使用してコマンドを "spring" コマンド引数から分離します。

$ spring run hello.groovy -- --server.port=9000

JVM コマンドライン引数を設定するには、次の例に示すように、JAVA_OPTS 環境変数を使用できます。

$ JAVA_OPTS=-Xmx1024m spring run hello.groovy

Microsoft Windows で JAVA_OPTS を設定するときは、set "JAVA_OPTS=-Xms256m -Xmx2048m" などの命令全体を引用符で囲んでください。これにより、値がプロセスに適切に渡されます。

2.1.1. 推定された "Grab" 依存関係

標準の Groovy には @Grab アノテーションが含まれており、サードパーティライブラリへの依存関係を宣言できます。この便利な手法により、Groovy は Maven または Gradle と同じ方法で jar をダウンロードできますが、ビルドツールを使用する必要はありません。

Spring Boot はこの手法をさらに拡張し、コードに基づいてどのライブラリを「取得」するかを推測しようとします。例: 前に示した WebApplication コードは @RestController アノテーションを使用しているため、Spring Boot は "Tomcat" と "Spring MVC" を取得します。

次の項目は「Grab ヒント」として使用されます。

項目 Grab

項目	Grab
`JdbcTemplate`, `NamedParameterJdbcTemplate`, `DataSource`	JDBC アプリケーション。
`@EnableJms`	JMS アプリケーション。
`@EnableCaching`	キャッシングの抽象化。
`@Test`	JUnit。
`@EnableRabbit`	RabbitMQ。
`Specification` を継承	Spock テスト。
`@EnableBatchProcessing`	Spring Batch.
`@MessageEndpoint` `@EnableIntegration`	Spring Integration.
`@Controller` `@RestController` `@EnableWebMvc`	Spring MVC + 組み込み Tomcat。
`@EnableWebSecurity`	Spring Security.
`@EnableTransactionManagement`	Spring トランザクション管理。

JdbcTemplate, NamedParameterJdbcTemplate, DataSource

JDBC アプリケーション。

@EnableJms

JMS アプリケーション。

@EnableCaching

キャッシングの抽象化。

@Test

JUnit。

@EnableRabbit

RabbitMQ。

Specification を継承

Spock テスト。

@EnableBatchProcessing

Spring Batch.

@MessageEndpoint @EnableIntegration

Spring Integration.

@Controller @RestController @EnableWebMvc

Spring MVC + 組み込み Tomcat。

@EnableWebSecurity

Spring Security.

@EnableTransactionManagement

Spring トランザクション管理。

Spring Boot CLI ソースコードの CompilerAutoConfiguration [GitHub] (英語) のサブクラスを参照して、カスタマイズがどのように適用されるかを正確に理解しましょう。

2.1.2. 推定された "Grab" 座標

Spring Boot は、グループまたはバージョンなしで依存関係を指定できるようにすることにより、Groovy の標準 @Grab サポートを継承します（例: @Grab('freemarker')）。これにより、Spring Boot のデフォルトの依存関係メタデータを参照して、アーティファクトのグループとバージョンを推測します。

デフォルトのメタデータは、使用する CLI のバージョンに関連付けられています。CLI の新しいバージョンに移動したときにのみ変更され、依存関係のバージョンが変更されるタイミングを制御できます。デフォルトのメタデータに含まれる依存関係とそのバージョンを示す表は、付録にあります。

2.1.3. デフォルトのインポート文

Groovy コードのサイズを縮小するために、いくつかの import ステートメントが自動的に含まれています。前の例で、完全修飾名や import ステートメントを使用せずに @Component、@RestController、@RequestMapping を参照していることに注目してください。

多くの Spring アノテーションは、import ステートメントを使用せずに機能します。インポートを追加する前に、アプリケーションを実行して何が失敗するかを確認してください。

2.1.4. 自動メインメソッド

同等の Java アプリケーションとは異なり、public static void main(String[] args) メソッドを Groovy スクリプトに含める必要はありません。SpringApplication が自動的に作成され、コンパイルされたコードが source として機能します。

2.1.5. カスタム依存関係管理

デフォルトでは、@Grab 依存関係を解決するときに、CLI は spring-boot-dependencies で宣言された依存関係管理を使用します。デフォルトの依存関係管理をオーバーライドする追加の依存関係管理は、@DependencyManagementBom アノテーションを使用して構成できます。アノテーションの値は、1 つ以上の Maven BOM の座標（groupId:artifactId:version）を指定する必要があります。

例: 次の宣言を検討してください。

@DependencyManagementBom("com.example.custom-bom:1.0.0")

上記の宣言は、com/example/custom-versions/1.0.0/ の Maven リポジトリで custom-bom-1.0.0.pom をピックアップします。

複数の BOM を指定すると、次の例に示すように、宣言した順序で適用されます。

@DependencyManagementBom([
    "com.example.custom-bom:1.0.0",
    "com.example.another-bom:1.0.0"])

上記の例は、another-bom の依存関係管理が custom-bom の依存関係管理をオーバーライドすることを示しています。

@Grab を使用できる場所であれば、どこでも @DependencyManagementBom を使用できます。ただし、依存関係管理の一貫した順序を確保するために、@DependencyManagementBom をアプリケーションで最大 1 回使用できます。

2.2. 複数のソースファイルを持つアプリケーション

ファイル入力を受け付けるすべてのコマンドで「シェルグロビング」を使用できます。これにより、次の例に示すように、単一のディレクトリから複数のファイルを使用できます。

$ spring run *.groovy

2.3. アプリケーションのパッケージ化

次の例に示すように、jar コマンドを使用して、アプリケーションを自己完結型の実行可能 jar ファイルにパッケージ化できます。

$ spring jar my-app.jar *.groovy

結果の jar には、アプリケーションとアプリケーションのすべての依存関係をコンパイルして生成されたクラスが含まれているため、java -jar を使用して実行できます。jar ファイルには、アプリケーションのクラスパスからのエントリも含まれています。--include および --exclude を使用して、jar への明示的なパスを追加および削除できます。どちらもカンマ区切りで、どちらも "+" と "-" の形式のプレフィックスを受け入れて、デフォルトから削除する必要があることを示します。デフォルトのインクルードは次のとおりです。

public/**, resources/**, static/**, templates/**, META-INF/**, *

デフォルトの除外は次のとおりです。

.*, repository/**, build/**, target/**, **/*.jar, **/*.groovy

詳細については、コマンドラインで spring help jar と入力してください。

2.4. 新しいプロジェクトを初期化する

init コマンドを使用すると、次の例に示すように、シェルを移動せずに start.spring.io を使用して新しいプロジェクトを作成できます。

$ spring init --dependencies=web,data-jpa my-project
Using service at https://start.spring.io
Project extracted to '/Users/developer/example/my-project'

上記の例では、spring-boot-starter-web と spring-boot-starter-data-jpa を使用する Maven ベースのプロジェクトで my-project ディレクトリを作成します。次の例に示すように、--list フラグを使用して、サービスの機能をリストできます。

$ spring init --list
=======================================
Capabilities of https://start.spring.io
=======================================

Available dependencies:
-----------------------
actuator - Actuator: Production ready features to help you monitor and manage your application
...
web - Web: Support for full-stack web development, including Tomcat and spring-webmvc
websocket - Websocket: Support for WebSocket development
ws - WS: Support for Spring Web Services

Available project types:
------------------------
gradle-build -  Gradle Config [format:build, build:gradle]
gradle-project -  Gradle Project [format:project, build:gradle]
maven-build -  Maven POM [format:build, build:maven]
maven-project -  Maven Project [format:project, build:maven] (default)

...

init コマンドは多くのオプションをサポートしています。詳細については、help の出力を参照してください。たとえば、次のコマンドは、Java 8 および war パッケージングを使用する Gradle プロジェクトを作成します。

$ spring init --build=gradle --java-version=1.8 --dependencies=websocket --packaging=war sample-app.zip
Using service at https://start.spring.io
Content saved to 'sample-app.zip'

2.5. 組み込みシェルの使用

Spring Boot には、BASH および zsh シェル用のコマンドライン補完スクリプトが含まれています。これらのシェルのいずれも使用しない場合（おそらく Windows ユーザー）、次の例に示すように、shell コマンドを使用して統合シェルを起動できます。

$ spring shell
Spring Boot (v2.6.3)
Hit TAB to complete. Type \'help' and hit RETURN for help, and \'exit' to quit.

組み込みシェル内から、他のコマンドを直接実行できます。

$ version
Spring CLI v2.6.3

埋め込みシェルは、ANSI カラー出力と tab 補完をサポートしています。ネイティブコマンドを実行する必要がある場合は、! プレフィックスを使用できます。組み込みシェルを終了するには、ctrl-c を押します。

2.6. CLI への拡張機能の追加

install コマンドを使用して、CLI に拡張機能を追加できます。このコマンドは、次の例に示すように、形式 group:artifact:version の 1 つ以上のアーティファクト座標のセットを取ります。

$ spring install com.example:spring-boot-cli-extension:1.0.0.RELEASE

指定した座標によって識別されるアーティファクトのインストールに加えて、すべてのアーティファクトの依存関係もインストールされます。

依存関係をアンインストールするには、uninstall コマンドを使用します。install コマンドと同様に、次の例に示すように、group:artifact:version の形式の 1 つ以上のアーティファクト座標のセットを取ります。

$ spring uninstall com.example:spring-boot-cli-extension:1.0.0.RELEASE

指定した座標とその依存関係によって識別されるアーティファクトをアンインストールします。

追加の依存関係をすべてアンインストールするには、次の例に示すように、--all オプションを使用できます。

$ spring uninstall --all

3. Groovy Beans DSL を使用したアプリケーションの開発

Spring Framework 4.0 は、beans{} "DSL" （Grails (英語) から借用）をネイティブでサポートしており、同じ形式を使用して Groovy アプリケーションスクリプトに Bean 定義を埋め込むことができます。これは、次の例に示すように、ミドルウェア宣言などの外部機能を含めるのに適した方法です。

@Configuration(proxyBeanMethods = false)
class Application implements CommandLineRunner {

    @Autowired
    SharedService service

    @Override
    void run(String... args) {
        println service.message
    }

}

import my.company.SharedService

beans {
    service(SharedService) {
        message = "Hello World"
    }
}

最上位にある限り、同じファイル内で beans{} とクラス宣言を混在させることができます。または、必要に応じて、Bean DSL を別のファイルに置くことができます。

4. settings.xml を使用した CLI の構成

Spring Boot CLI は、Maven の依存関係解決エンジンである Maven リゾルバーを使用して依存関係を解決します。CLI は、~/.m2/settings.xml にある Maven 構成を使用して、Maven リゾルバーを構成します。次の構成設定は、CLI によって尊重されます。

オフライン
ミラーリング
サーバー
プロキシ
プロファイル
- アクティベーション
- リポジトリ
アクティブなプロファイル

詳細については、Maven の設定ドキュメント [Apache] (英語) を参照してください。

5. 次のステップ

GitHub リポジトリには、Spring Boot CLI を試すために使用できる groovy スクリプトのサンプル [GitHub] (英語) がいくつかあります。ソースコード [GitHub] (英語) 全体に Javadoc も豊富にあります。

CLI ツールの限界に達した場合は、おそらく、アプリケーションを完全な Gradle または Maven ビルドの「Groovy プロジェクト」に変換することを検討してください。次のセクションでは、Spring Boot の "ビルドツールプラグイン" について説明します。これは、Gradle または Maven で使用できます。