Spring Boot 3.0.6 入門 - リファレンスドキュメント

このサイトには Spring に関する数千ページ以上の膨大なドキュメントがありますが、Spring Boot やその他の Spring プロジェクトを使い始めようとしている場合は、まず、この入門セクションを読むことから始めましょう。他のバージョンはバージョン別ドキュメント一覧を参照してください。このセクションでは、Spring Boot の導入とインストール手順について説明します。次に、最初の Spring Boot アプリケーションを構築する手順を説明し、その過程でいくつかの基本原則を説明します。

1. Spring Boot の導入

Spring Boot とは、設定がほとんど不要で Spring と外部ライブラリを利用でき、規約に従うことにより Spring ベースのアプリケーションを簡単に作成できる事実上標準の Java フレームワークです。

Spring Boot を使用して、Tomcat 組み込みの java -jar で起動可能な jar ファイル、または従来の Tomcat にデプロイ可能な war ファイルを作成することができます。

主なゴールは次のとおりです。

すべての Spring 開発に、非常に高速で広くアクセス可能な入門体験を提供します。
すぐに使用でき、要件がデフォルトと異なる場合でもすぐに対応できます。
大規模なクラスのプロジェクトに共通のさまざまな非機能機能（組み込みサーバー、セキュリティ、メトリクス、ヘルスチェック、外部化された設定など）を提供します。
コード生成 (ネイティブイメージを対象としていない場合) はまったくなく、XML 構成も必要ありません。

2. システム要件

Spring Boot 3.0.6 ( バージョン別サポート期間 ) には Java 17 が必要で、Java 20 まで互換性があります。また依存関係管理メカニズムにより Spring Framework 6.0.8 ( バージョン別サポート期間 ) 以上が自動的に使用されます。

次のビルドツールのサポートがあり、デフォルトでは gradle が使用されます。

ビルドツール	バージョン
Maven	3.5+
Gradle	7.x (7.5 以降) および 8.x

ビルドツール

バージョン

Maven

3.5+

Gradle

7.x (7.5 以降) および 8.x

2.1. サーブレットコンテナー

Spring Boot は、次の埋め込みサーブレットコンテナーをサポートがあり、デフォルトでは Tomcat が使用されます。

名前	サーブレットバージョン
Tomcat 10.0	5.0
Jetty 11.0	5.1
Undertow 2.2 (Jakarta EE 9 バリアント)	5.0

Spring Boot アプリケーションを任意のサーブレット 5.0 + 互換コンテナーにデプロイすることもできます。

2.2. GraalVM ネイティブイメージ

Spring Boot アプリケーションは、GraalVM 22.3 以降を使用してネイティブイメージに変換できます。

イメージは、ネイティブビルドツール [GitHub] (英語) Gradle/Maven プラグインまたは GraalVM が提供する native-image ツールを使用して作成できます。ネイティブイメージ Paketo buildpack [GitHub] (英語) を使用してネイティブイメージを作成することもできます。

次のバージョンがサポートされています。

名前	バージョン
GraalVM コミュニティ	22.3
ネイティブビルドツール	0.9.21

名前

バージョン

GraalVM コミュニティ

22.3

ネイティブビルドツール

0.9.21

3. Spring Boot のインストール

Eclipse STS、IntelliJ IDEA、VSCode Auto Config を使用する場合、以降に示すインストール手順は不要です。Spring Initializr クイックスタートや簡単な Web 画面の作成を試してみてください。コマンドラインを使用する場合は、次のコマンドを使用して現在インストールされている Java を確認する必要があります。

$ java -version

コマンドラインで開発する場合は、以降の手順に従ってください。

3.1. Java 開発者向けのインストール手順

Spring Boot は特別なツールの統合を必要としないため、クラスパスに適切な spring-boot-*.jar ファイルを含めることで、標準 Java ライブラリと同じ方法で使用できます。また、Spring Boot アプリケーションには特別なものはないため、他の Java プログラムと同様に Spring Boot アプリケーションを実行およびデバッグできます。

Spring Boot の jar を手動でダウンロードしてプロジェクト内に配置することもできますが、依存性管理が困難になるため、通常はサポートするビルドツール（Gradle や Maven など）を使用することをお勧めします。Eclipse STS や IntelliJ IDEA のような IDE の場合は Gradle や Maven が含まれているため、IDE 付属のデフォルトのバージョンを使用する場合は、後述の Gradle や Maven のインストール不要です。また、異なるバージョンが必要な場合でも、Spring Initializr で作成した Spring Boot プロジェクトには gradlew や mvnw が含まれているため、Gradle や Maven のインストールは必要ありません。

3.1.1. Maven のインストール

Spring Boot は Apache Maven 3.5 以上と互換性があります。Maven をまだインストールしていない場合は、maven.apache.org (英語) の手順に従ってください。

多くのオペレーティングシステムでは、Maven はパッケージマネージャーを使用してインストールできます。OSX Homebrew を使用する場合は、brew install maven を試してください。Ubuntu ユーザーは sudo apt-get install maven を実行できます。Chocolatey (英語) を使用する Windows ユーザーは、昇格した（管理者）プロンプトから choco install maven を実行できます。

Spring Boot 依存関係は org.springframework.boot グループ ID を使用します。通常、Maven POM ファイルは spring-boot-starter-parent プロジェクトから継承し、1 つ以上の “スターター” への依存関係を宣言します。Spring Boot は、実行可能な jar を作成するためのオプションの Maven プラグインも提供します。

Spring Boot と Maven の使用開始の詳細については、Maven プラグインのリファレンスガイドの入門セクション (英語) を参照してください。

3.1.2. Gradle のインストール

Spring Boot は Gradle 7.x(7.5 以降)、8.x と互換性があります。Gradle をまだインストールしていない場合は、gradle.org (英語) の指示に従ってください。

Spring Boot の依存関係は、org.springframework.boot group を使用して宣言できます。通常、プロジェクトは 1 つ以上の “スターター” への依存関係を宣言します。Spring Boot は、依存関係の宣言を簡素化し、実行可能な jar を作成するために使用できる便利な Gradle プラグインを提供します。

Gradle ラッパー

Gradle ラッパーは、プロジェクトをビルドする必要がある場合に Gradle を「取得」する優れた方法を提供します。これは、ビルドプロセスをブートストラップするためにコードと一緒にコミットする小さなスクリプトとライブラリです。詳細については、docs.gradle.org/current/userguide/gradle_wrapper.html (英語) を参照してください。

Spring Boot と Gradle の使用開始の詳細については、Gradle プラグインのリファレンスガイドの入門セクション (英語) を参照してください。

3.2. Spring Boot CLI のインストール

Spring Boot CLI (コマンドラインインターフェース) は、Spring ですばやくプロトタイプを作成するために使用できるコマンドラインツールです。

Spring Boot を操作するために CLI を使用する必要はありませんが、Eclipse STS や IntelliJ IDEA のような IDE を使用せずに Spring アプリケーションをすぐに使用できるようにする方法です。

3.2.1. 手動インストール

Spring CLI ディストリビューションは、次のいずれかの場所からダウンロードできます。

ダウンロードしたら、解凍したアーカイブの INSTALL.txt (英語) の指示に従ってください。要約すると、.zip ファイルの bin/ ディレクトリには、spring スクリプト（Windows の場合は spring.bat）があります。または、.jar ファイルで java -jar を使用できます（スクリプトは、クラスパスが正しく設定されていることを確認できます）。

3.2.2. SDKMAN! を使用したインストール

SDKMAN!（Software Development Kit Manager）は、Groovy や Spring Boot CLI など、さまざまなバイナリ SDK の複数のバージョンを管理するために使用できます。sdkman.io (英語) から SDKMAN! を取得し、次のコマンドを使用して Spring Boot をインストールします。

$ sdk install springboot
$ spring --version
Spring CLI v3.0.6

CLI の機能を開発し、ビルドしたバージョンにアクセスする場合は、次のコマンドを使用します。

$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-3.0.6-bin/spring-3.0.6/
$ sdk default springboot dev
$ spring --version
Spring CLI v3.0.6

上記の手順では、dev インスタンスと呼ばれる spring のローカルインスタンスをインストールします。ターゲットビルドの場所を指すため、Spring Boot を再構築するたびに、spring は最新の状態になります。

次のコマンドを実行して確認できます。

$ sdk ls springboot

================================================================================
Available Springboot Versions
================================================================================
> + dev
* 3.0.6

================================================================================
+ - local version
* - installed
> - currently in use
================================================================================

3.2.3. OSX Homebrew のインストール

Mac で Homebrew (英語) を使用している場合、次のコマンドを使用して Spring Boot CLI をインストールできます。

$ brew tap spring-io/tap
$ brew install spring-boot

Homebrew は /usr/local/bin に spring をインストールします。

formula が表示されない場合、brew のインストールが古くなっている可能性があります。その場合は、brew update を実行して再試行してください。

3.2.4. MacPorts のインストール

Mac で MacPorts (英語) を使用している場合、次のコマンドを使用して Spring Boot CLI をインストールできます。

$ sudo port install spring-boot-cli

3.2.5. コマンドライン補完

Spring Boot CLI には、BASH [Wikipedia] および zsh [Wikipedia] シェルのコマンド補完を提供するスクリプトが含まれています。任意のシェルでスクリプト（spring とも呼ばれる）を source するか、個人またはシステム全体の bash 完了初期化に配置できます。Debian システムでは、システム全体のスクリプトは <installation location>/shell-completion/bash にあり、そのディレクトリ内のすべてのスクリプトは、新しいシェルの起動時に実行されます。例: SDKMAN! を使用してインストールした場合にスクリプトを手動で実行するには、次のコマンドを使用します。

$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
$ spring <HIT TAB HERE>
  grab  help  jar  run  test  version

Homebrew または MacPorts を使用して Spring Boot CLI をインストールすると、コマンドライン補完スクリプトがシェルに自動的に登録されます。

3.2.6. Windows Scoop のインストール

Windows で Scoop (英語) を使用している場合、次のコマンドを使用して Spring Boot CLI をインストールできます。

> scoop bucket add extras
> scoop install springboot

Scoop は ~/scoop/apps/springboot/current/bin に spring をインストールします。

アプリのマニフェストが表示されない場合は、scoop のインストールが古くなっている可能性があります。その場合は、scoop update を実行して再試行してください。

4. 初めての Spring Boot アプリケーションの開発

このセクションでは、Spring Boot の主な機能の一部を紹介する小さな "Hello World!" Web アプリケーションの開発方法を説明します。このプロジェクトの構築には、ほとんどの IDE がサポートしている Maven を使用します。

spring.io Web サイトには、Spring Boot を使用する多くの「入門」ガイドが含まれています。特定の問題を解決する必要がある場合は、まずそこを確認してください。

Eclipse STS や IntelliJ IDEA のプロジェクト作成ウィザード (Spring Initializr) の依存関係から "Spring Web" スターターを選択することにより、以下のステップをショートカットできます。これにより、新しいプロジェクト構造が生成されるため、すぐにコーディングを開始できます。詳細については、Spring Initializr を確認してください。

開始する前に、ターミナルを開いて次のコマンドを実行し、Java および Maven の有効なバージョンがインストールされていることを確認します。

$ java -version
openjdk version "17.0.4.1" 2022-08-12 LTS
OpenJDK Runtime Environment (build 17.0.4.1+1-LTS)
OpenJDK 64-Bit Server VM (build 17.0.4.1+1-LTS, mixed mode, sharing)

$ mvn -v
Apache Maven 3.8.5 (3599d3414f046de2324203b78ddcf9b5e4388aa0)
Maven home: usr/Users/developer/tools/maven/3.8.5
Java version: 17.0.4.1, vendor: BellSoft, runtime: /Users/developer/sdkman/candidates/java/17.0.4.1-librca

このサンプルは、独自のディレクトリに作成する必要があります。以降の手順では、適切なディレクトリを作成し、それが現在のディレクトリであると想定しています。

4.1. POM の作成

まず、Maven pom.xml ファイルを作成する必要があります。pom.xml は、プロジェクトのビルドに使用されるレシピです。お気に入りのテキストエディターを開き、次を追加します。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>myproject</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.0.6</version>
    </parent>

    <!-- Additional lines to be added here... -->

</project>

上記のリストは、機能するビルドを提供します。mvn package を実行してテストできます（現時点では、「jar は空になります。含めるコンテンツは含まれていません！」という警告は無視できます）。

この時点で、プロジェクトを IDE にインポートできます（ほとんどの最新の Java IDE には Maven の組み込みサポートが含まれています）。簡単にするために、この例では引き続きプレーンテキストエディターを使用します。

4.2. クラスパスの依存関係を追加する

Spring Boot には、クラスパスに jar を追加できるいくつかの「スターター」が用意されています。スモークテスト用アプリケーションは、POM の parent セクションにある spring-boot-starter-parent を使用します。spring-boot-starter-parent は、有用な Maven デフォルトを提供する特別なスタータです。また、dependency-management セクションも用意されているため、特別な依存関係の version タグを省略できます。

その他の「スターター」は、特定のタイプのアプリケーションを開発するときに必要になる可能性のある依存関係を提供します。Web アプリケーションを開発しているため、spring-boot-starter-web 依存関係を追加します。その前に、次のコマンドを実行して、現在あるものを確認できます。

$ mvn dependency:tree

[INFO] com.example:myproject:jar:0.0.1-SNAPSHOT

mvn dependency:tree コマンドは、プロジェクトの依存関係のツリー表現を出力します。spring-boot-starter-parent 自体には依存関係がないことがわかります。必要な依存関係を追加するには、pom.xml を編集し、parent セクションのすぐ下に spring-boot-starter-web 依存関係を追加します。

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

mvn dependency:tree を再度実行すると、Tomcat Web サーバーや Spring Boot 自体を含む、多くの追加の依存関係があることがわかります。

4.3. コードの作成

アプリケーションを完成させるには、単一の Java ファイルを作成する必要があります。デフォルトでは、Maven は src/main/java からソースをコンパイルするため、そのディレクトリ構造を作成してから、src/main/java/MyApplication.java という名前のファイルを追加して、次のコードを含める必要があります。

Java

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@SpringBootApplication
public class MyApplication {

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

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

}

Kotlin

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@SpringBootApplication
class MyApplication {

    @RequestMapping("/")
    fun home() = "Hello World!"

}

fun main(args: Array<String>) {
    runApplication<MyApplication>(*args)
}

ここには多くのコードはありませんが、非常に多くのことが行われています。次のいくつかのセクションで重要な部分を順に説明します。

4.3.1. @RestController および @RequestMapping アノテーション

MyApplication クラスの最初のアノテーションは @RestController です。これはステレオタイプアノテーションとして知られています。コードを読んでいる人や、クラスが特定のロールを果たす Spring のヒントを提供します。この場合、クラスは Web @Controller であるため、Spring は受信 Web リクエストを処理するときにそれを考慮します。

@RequestMapping アノテーションは、「ルーティング」情報を提供します。/ パスを持つ HTTP リクエストは home メソッドにマッピングする必要があることを Spring に伝えます。@RestController アノテーションは、結果の文字列を呼び出し元に直接返すように Spring に指示します。

@RestController および @RequestMapping アノテーションは Spring MVC アノテーションです (Spring Boot に固有ではありません)。詳細については、Spring リファレンスドキュメントの MVC セクションを参照してください。

4.3.2. @SpringBootApplication アノテーション

2 番目のクラスレベルのアノテーションは @SpringBootApplication です。このアノテーションはメタアノテーションと呼ばれ @SpringBootConfiguration、@EnableAutoConfiguration、@ComponentScan を組み合わせたものです。

その中で、ここで最も注目するアノテーションは @EnableAutoConfiguration です。@EnableAutoConfiguration は、追加した jar 依存関係に基づいて、Spring を構成する方法を「推測」するように Spring Boot に指示します。spring-boot-starter-web には Tomcat と Spring MVC が含まれているため、自動構成は Web アプリケーションを開発していると仮定し、それに応じて Spring をセットアップします。

スターターと自動構成

自動構成は「スターター」とうまく機能するように設計されていますが、2 つの概念は直接結びついていません。スターター以外の jar 依存関係を自由に選択できます。Spring Boot は、アプリケーションを自動構成するために最善を尽くしています。

4.3.3. "main" メソッド

アプリケーションの最後の部分は main メソッドです。これは、アプリケーションのエントリポイントに関する Java の規則に従う標準のメソッドです。メインのメソッドは run を呼び出して Spring Boot の SpringApplication クラスに委譲します。SpringApplication はアプリケーションをブートストラップし、Spring を起動します。これにより、自動構成された Tomcat Web サーバーが起動します。MyApplication.class を引数として run メソッドに渡し、SpringApplication がプライマリ Spring コンポーネントであることを通知する必要があります。args 配列も渡され、コマンドライン引数が公開されます。

4.4. サンプルの実行

この時点で、アプリケーションは動作するはずです。spring-boot-starter-parent POM を使用したため、アプリケーションを開始するために使用できる有用な run ゴールがあります。ルートプロジェクトディレクトリから mvn spring-boot:run と入力して、アプリケーションを起動します。次のような出力が表示されます。

$ mvn spring-boot:run

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v3.0.6)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 0.906 seconds (process running for 6.514)

Web ブラウザーを localhost:8080 で開くと、次の出力が表示されるはずです。

Hello World!

アプリケーションを正常に終了するには、ctrl-c を押します。

4.5. 実行可能 Jar の作成

実例を実行できる完全に自己完結型の実行可能 jar ファイルを作成することで、この例を終了します。実行可能 jar（ "fat jar" と呼ばれることもあります）は、コードの実行に必要なすべての jar 依存関係とともに、コンパイルされたクラスを含むアーカイブです。

実行可能 jar および Java

Java は、ネストされた jar ファイル（jar 内に含まれる jar ファイル）をロードする標準的な方法を提供しません。自己完結タイプのアプリケーションを配布しようとしている場合、これは問題になる可能性があります。

この問題を解決するために、多くの開発者は "uber" jar を使用します。uber jar は、すべてのアプリケーションの依存関係からのすべてのクラスを単一のアーカイブにパッケージ化します。このアプローチの問題は、アプリケーションにどのライブラリが含まれているかを確認しにくくなることです。また、複数の jar で同じファイル名（ただし、異なるコンテンツ）が使用されている場合、問題が発生する可能性があります。

Spring Boot は異なるアプローチを採用しており、実際に jar を直接ネストできます。

実行可能な jar を作成するには、spring-boot-maven-plugin を pom.xml に追加する必要があります。これを行うには、dependencies セクションのすぐ下に次の行を挿入します。

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

spring-boot-starter-parent POM には、repackage ゴールをバインドする <executions> 構成が含まれています。親 POM を使用しない場合、この構成を自分で宣言する必要があります。詳細については、プラグインのドキュメント (英語) を参照してください。

次のように、pom.xml を保存し、コマンドラインから mvn package を実行します。

$ mvn package

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building myproject 0.0.1-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] .... ..
[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ myproject ---
[INFO] Building jar: /Users/developer/example/spring-boot-example/target/myproject-0.0.1-SNAPSHOT.jar
[INFO]
[INFO] --- spring-boot-maven-plugin:3.0.6:repackage (default) @ myproject ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

target ディレクトリを見ると、myproject-0.0.1-SNAPSHOT.jar が表示されているはずです。ファイルのサイズは約 10 MB でなければなりません。内部を覗きたい場合は、次のように jar tvf を使用できます。

$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar

また、myproject-0.0.1-SNAPSHOT.jar.original という名前のはるかに小さいファイルが target ディレクトリに表示されるはずです。これは、Spring Boot によって再パッケージ化される前に Maven が作成した元の jar ファイルです。

そのアプリケーションを実行するには、次のように java -jar コマンドを使用します。

$ java -jar target/myproject-0.0.1-SNAPSHOT.jar

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v3.0.6)
....... . . .
....... . . . (log output here)
....... . . .
........ Started MyApplication in 2.536 seconds (process running for 2.864)

前と同様に、アプリケーションを終了するには、ctrl-c を押します。

5. 次のステップ

このセクションでは、Spring Boot の基本をいくつか説明し、独自のアプリケーションを作成するための方法を紹介しました。特定の目的を解決したい場合は、入門ガイドを見てみましょう。また、Spring Boot に特化した "使い方" リファレンスドキュメントも用意されています。

それ以外の場合、次の論理的ステップ using.html に進みましょう。急いでいる場合は Spring Boot の機能を先に読んでしまうのも良いでしょう。