このセクションでは、Spring Bootの詳細について説明します。ここでは、使用およびカスタマイズしたい主な機能について学習できます。まだ読んでいない場合は、「getting-started.html」セクションと「using-spring-boot.html」セクションを読んで、基本を十分に理解しましょう。

1. SpringApplication

SpringApplication クラスは、main() メソッドから開始されるSpringアプリケーションをブートストラップする便利な方法を提供します。多くの場合、次の例に示すように、静的 SpringApplication.run メソッドに委譲できます。

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

アプリケーションが起動すると、次のような出力が表示されるはずです。

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::   v2.2.4.RELEASE

2019-04-31 13:09:54.117  INFO 56603 --- [           main] o.s.b.s.app.SampleApplication            : Starting SampleApplication v0.1.0 on mycomputer with PID 56603 (/apps/myapp.jar started by pwebb)
2019-04-31 13:09:54.166  INFO 56603 --- [           main] ationConfigServletWebServerApplicationContext : Refreshing org.springframework.boot.web.ser[email protected](英語)  6e5a8246: startup date [Wed Jul 31 00:08:16 PDT 2013]; root of context hierarchy
2019-04-01 13:09:56.912  INFO 41370 --- [           main] .t.TomcatServletWebServerFactory : Server initialized with port: 8080
2019-04-01 13:09:57.501  INFO 41370 --- [           main] o.s.b.s.app.SampleApplication            : Started SampleApplication in 2.992 seconds (JVM running for 3.658)

デフォルトでは、INFO ロギングメッセージが表示されます。これには、アプリケーションを起動したユーザーなど、関連するスタートアップの詳細が含まれます。 INFO以外のログレベルが必要な場合は、ログレベルの説明に従って設定できます。アプリケーションバージョンは、メインアプリケーションクラスのパッケージの実装バージョンを使用して決定されます。 spring.main.log-startup-infofalseに設定することにより、始動情報のロギングをオフにできます。これにより、アプリケーションのアクティブなプロファイルのログもオフになります。

起動時に追加のログを追加するには、SpringApplicationのサブクラスで logStartupInfo(boolean) をオーバーライドできます。

1.1. 起動失敗

アプリケーションの起動に失敗した場合、登録された FailureAnalyzers は、専用のエラーメッセージと、問題を修正するための具体的なアクションを提供する機会を得ます。たとえば、ポート 8080 でWebアプリケーションを起動し、そのポートが既に使用されている場合、次のようなメッセージが表示されます。

***************************
APPLICATION FAILED TO START
***************************

Description:

Embedded servlet container failed to start. Port 8080 was already in use.

Action:

Identify and stop the process that's listening on port 8080 or configure this application to listen on another port.
Spring Bootは、多数の FailureAnalyzer 実装を提供します。独自の実装を追加 できます。

障害アナライザーが例外を処理できない場合でも、完全な状態レポートを表示して、問題の原因をよりよく理解できます。これを行うには、debug プロパティを有効にするか、org.springframework.boot.autoconfigure.logging.ConditionEvaluationReportLoggingListenerDEBUG ロギングを有効にする必要があります。

たとえば、java -jarを使用してアプリケーションを実行している場合、次のように debug プロパティを有効にできます。

$ java -jar myproject-0.0.1-SNAPSHOT.jar --debug

1.2. 遅延初期化

SpringApplication を使用すると、アプリケーションを遅延的に初期化できます。遅延初期化が有効な場合、Beanはアプリケーションの起動時ではなく、必要に応じて作成されます。その結果、遅延初期化を有効にすると、アプリケーションの起動にかかる時間を短縮できます。Webアプリケーションでは、遅延初期化を有効にすると、HTTPリクエストを受信するまで多くのWeb関連Beanが初期化されなくなります。

遅延初期化の欠点は、アプリケーションの問題の発見を遅らせる可能性があることです。誤って構成されたBeanが遅延初期化された場合、起動時に障害は発生せず、Beanが初期化されたときにのみ問題が明らかになります。また、JVMに、起動時に初期化されるBeanだけでなく、アプリケーションのすべてのBeanを収容するのに十分なメモリがあることを確認する必要があります。これらの理由により、遅延初期化はデフォルトでは有効になっていないため、遅延初期化を有効にする前にJVMのヒープサイズの微調整を行うことをお勧めします。

遅延初期化は、SpringApplicationBuilderlazyInitialization メソッドまたは SpringApplicationsetLazyInitialization メソッドを使用して、プログラムで有効にできます。または、次の例に示すように、spring.main.lazy-initialization プロパティを使用して有効にできます。

spring.main.lazy-initialization=true
残りのアプリケーションで遅延初期化を使用しているときに特定のBeanの遅延初期化を無効にする場合は、@Lazy(false) アノテーションを使用して遅延属性を明示的にfalseに設定できます。

1.3. バナーのカスタマイズ

起動時に出力されるバナーを変更するには、banner.txt ファイルをクラスパスに追加するか、spring.banner.location プロパティをそのようなファイルの場所に設定します。ファイルにUTF-8以外のエンコードが含まれている場合は、spring.banner.charsetを設定できます。テキストファイルに加えて、banner.gif, banner.jpgまたは banner.png イメージファイルをクラスパスに追加したり、spring.banner.image.location プロパティを設定したりすることもできます。イメージはASCIIアート表現に変換され、テキストバナーの上に出力されます。

banner.txt ファイル内では、次のプレースホルダーのいずれかを使用できます。

表 1: バナー変数
変数説明

${application.version}

MANIFEST.MFで宣言されているアプリケーションのバージョン番号。例: Implementation-Version: 1.01.0として出力されます。

${application.formatted-version}

MANIFEST.MF で宣言され、表示用にフォーマットされたアプリケーションのバージョン番号(括弧で囲まれ、接頭部が v)。たとえば、(v1.0)

${spring-boot.version}

使用しているSpring Bootバージョン。たとえば、2.2.4.RELEASE

${spring-boot.formatted-version}

使用するSpring Bootバージョン。表示用にフォーマットされています(括弧で囲まれ、接頭部が v)。たとえば、(v2.2.4.RELEASE)

${Ansi.NAME} (または ${AnsiColor.NAME}, ${AnsiBackground.NAME}, ${AnsiStyle.NAME} )

ここで、NAME はANSIエスケープコードの名前です。詳細については、 AnsiPropertySource (GitHub) を参照してください。

${application.title}

MANIFEST.MFで宣言されているアプリケーションのタイトル。たとえば、Implementation-Title: MyAppMyAppとして出力されます。

SpringApplication.setBanner(…​) メソッドは、プログラムでバナーを生成する場合に使用できます。 org.springframework.boot.Banner インターフェースを使用して、独自の printBanner() メソッドを実装します。

spring.main.banner-mode プロパティを使用して、バナーを System.outconsole)に出力するか、構成されたロガーに送信する(log)か、まったく生成しない(off)かを決定することもできます。

印刷されたバナーは、springBootBannerという名前でシングルトンBeanとして登録されます。

1.4. SpringApplicationのカスタマイズ

SpringApplication のデフォルトが好みに合わない場合は、代わりにローカルインスタンスを作成してカスタマイズできます。例:バナーをオフにするには、次のように記述できます。

public static void main(String[] args) {
    SpringApplication app = new SpringApplication(MySpringConfiguration.class);
    app.setBannerMode(Banner.Mode.OFF);
    app.run(args);
}
SpringApplication に渡されるコンストラクター引数は、Spring Beanの構成ソースです。ほとんどの場合、これらは @Configuration クラスへの参照ですが、XML構成またはスキャンする必要があるパッケージへの参照にすることもできます。

application.properties ファイルを使用して SpringApplication を構成することもできます。詳細については、外部化された構成を参照してください。

構成オプションの完全なリストについては、 SpringApplication Javadocを参照してください。

1.5. Fluent Builder API

ApplicationContext 階層(親/子関係を持つ複数のコンテキスト)を構築する必要がある場合、または「流れるような」ビルダーAPIを使用する場合は、SpringApplicationBuilderを使用できます。

SpringApplicationBuilder を使用すると、チェーンで複数のメソッド呼び出しを行うことができ、次の例に示すように、階層を作成できる parent および child メソッドが含まれます。

new SpringApplicationBuilder()
        .sources(Parent.class)
        .child(Application.class)
        .bannerMode(Banner.Mode.OFF)
        .run(args);
ApplicationContext 階層を作成する場合、いくつかの制限があります。例:Webコンポーネントは子コンテキスト内に含まれている必要があり、同じ Environment が親コンテキストと子コンテキストの両方に使用されます。詳細については、 SpringApplicationBuilder Javadocを参照してください。

1.6. アプリケーションイベントとリスナー

ContextRefreshedEvent (Javadoc) などの通常のSpring Frameworkイベントに加えて、SpringApplication は追加のアプリケーションイベントを送信します。

ApplicationContext が作成される前に実際にトリガーされるイベントもあるため、それらのリスナーを @Beanとして登録することはできません。SpringApplication.addListeners(…​) メソッドまたは SpringApplicationBuilder.listeners(…​) メソッドで登録できます。

アプリケーションの作成方法に関係なく、これらのリスナーを自動的に登録する場合は、次の例に示すように、META-INF/spring.factories ファイルをプロジェクトに追加し、org.springframework.context.ApplicationListener キーを使用してリスナーを参照できます。

org.springframework.context.ApplicationListener=com.example.project.MyListener

アプリケーションが実行されると、アプリケーションイベントは次の順序で送信されます。

  1. ApplicationStartingEvent は実行の開始時に送信されますが、リスナーと初期化子の登録を除き、処理の前に送信されます。

  2. ApplicationEnvironmentPreparedEvent は、コンテキストで使用される Environment がわかっているが、コンテキストが作成される前に送信されます。

  3. ApplicationContextInitializedEvent は、ApplicationContext が準備され、ApplicationContextInitializersが呼び出されましたが、Bean定義がロードされる前に送信されます。

  4. ApplicationPreparedEvent は、リフレッシュが開始される直前、ただしBean定義がロードされた後に送信されます。

  5. ApplicationStartedEvent は、コンテキストがリフレッシュされた後、アプリケーションとコマンドラインランナーが呼び出される前に送信されます。

  6. ApplicationReadyEvent は、アプリケーションおよびコマンドラインランナーが呼び出された後に送信されます。アプリケーションがリクエストを処理する準備ができていることを示します。

  7. 起動時に例外がある場合、ApplicationFailedEvent が送信されます。

上記のリストには、SpringApplicationに関連付けられている SpringApplicationEventのみが含まれています。これらに加えて、次のイベントも ApplicationPreparedEvent の後、ApplicationStartedEventの前に公開されます。

  1. ApplicationContext がリフレッシュされると、ContextRefreshedEvent が送信されます。

  2. WebServer の準備が整うと、WebServerInitializedEvent が送信されます。 ServletWebServerInitializedEventReactiveWebServerInitializedEvent は、それぞれサーブレットとリアクティブバリアントです。

多くの場合、アプリケーションイベントを使用する必要はありませんが、それらが存在することを知っておくと便利です。内部的に、Spring Bootはイベントを使用してさまざまなタスクを処理します。

アプリケーションイベントは、Spring Frameworkのイベント発行メカニズムを使用して送信されます。このメカニズムの一部により、子コンテキストでリスナーに発行されたイベントは、すべての祖先コンテキストでリスナーにも発行されます。この結果、アプリケーションが SpringApplication インスタンスの階層を使用している場合、リスナーは同じタイプのアプリケーションイベントの複数のインスタンスを受け取る場合があります。

リスナーがそのコンテキストのイベントと子孫コンテキストのイベントを区別できるようにするには、アプリケーションコンテキストの注入を要求し、注入されたコンテキストをイベントのコンテキストと比較する必要があります。コンテキストは、ApplicationContextAware を実装するか、リスナーがBeanの場合は @Autowiredを使用して注入できます。

1.7. Web環境

SpringApplication は、ユーザーに代わって正しいタイプの ApplicationContext を作成しようとします。 WebApplicationType を決定するために使用されるアルゴリズムは非常に単純です。

  • Spring MVCが存在する場合、AnnotationConfigServletWebServerApplicationContext が使用されます

  • Spring MVCが存在せず、Spring WebFluxが存在する場合、AnnotationConfigReactiveWebServerApplicationContext が使用されます

  • それ以外の場合、AnnotationConfigApplicationContext が使用されます

これは、同じアプリケーションでSpring MVCとSpring WebFluxの新しい WebClient を使用している場合、デフォルトでSpring MVCが使用されることを意味します。 setWebApplicationType(WebApplicationType)を呼び出すことで簡単にオーバーライドできます。

setApplicationContextClass(…​)を呼び出すことで使用される ApplicationContext タイプを完全に制御することもできます。

JUnitテスト内で SpringApplication を使用する場合、setWebApplicationType(WebApplicationType.NONE) を呼び出すことが望ましい場合がよくあります。

1.8. アプリケーション引数へのアクセス

SpringApplication.run(…​)に渡されたアプリケーション引数にアクセスする必要がある場合は、org.springframework.boot.ApplicationArguments Beanを注入できます。 ApplicationArguments インターフェースは、次の例に示すように、未加工の String[] 引数と解析された option および non-option 引数の両方へのアクセスを提供します。

import org.springframework.boot.*;
import org.springframework.beans.factory.annotation.*;
import org.springframework.stereotype.*;

@Component
public class MyBean {

    @Autowired
    public MyBean(ApplicationArguments args) {
        boolean debug = args.containsOption("debug");
        List<String> files = args.getNonOptionArgs();
        // if run with "--debug logfile.txt" debug=true, files=["logfile.txt"]
    }

}
Spring Bootは、CommandLinePropertySource をSpring Environmentに登録します。これにより、@Value アノテーションを使用して、単一のアプリケーション引数を注入することもできます。

1.9. ApplicationRunnerまたはCommandLineRunnerの使用

SpringApplication の起動後に特定のコードを実行する必要がある場合は、ApplicationRunner または CommandLineRunner インターフェースを実装できます。両方のインターフェースは同じように機能し、SpringApplication.run(…​) が完了する直前に呼び出される単一の run メソッドを提供します。

CommandLineRunner インターフェースは、単純な文字列配列としてアプリケーション引数へのアクセスを提供しますが、ApplicationRunner は前述の ApplicationArguments インターフェースを使用します。次の例は、run メソッドを使用した CommandLineRunner を示しています。

import org.springframework.boot.*;
import org.springframework.stereotype.*;

@Component
public class MyBean implements CommandLineRunner {

    public void run(String... args) {
        // Do something...
    }

}

特定の順序で呼び出す必要がある複数の CommandLineRunner または ApplicationRunner Beanが定義されている場合、org.springframework.core.Ordered インターフェースをさらに実装するか、org.springframework.core.annotation.Order アノテーションを使用できます。

1.10. アプリケーション終了

SpringApplication はシャットダウンフックをJVMに登録して、ApplicationContext が終了時に正常に閉じるようにします。すべての標準Springライフサイクルコールバック( DisposableBean インターフェースや @PreDestroy アノテーションなど)を使用できます。

さらに、Beanは、SpringApplication.exit() が呼び出されたときに特定の終了コードを返したい場合、org.springframework.boot.ExitCodeGenerator インターフェースを実装できます。次の例に示すように、この終了コードを System.exit() に渡して、ステータスコードとして返すことができます。

@SpringBootApplication
public class ExitCodeApplication {

    @Bean
    public ExitCodeGenerator exitCodeGenerator() {
        return () -> 42;
    }

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

}

また、ExitCodeGenerator インターフェースは例外によって実装される場合があります。このような例外が発生すると、Spring Bootは、実装された getExitCode() メソッドによって提供される終了コードを返します。

1.11. 管理機能

spring.application.admin.enabled プロパティを指定することにより、アプリケーションの管理関連機能を有効にすることができます。これにより、プラットフォーム MBeanServer SpringApplicationAdminMXBean (GitHub) が公開されます。この機能を使用して、Spring Bootアプリケーションをリモートで管理できます。この機能は、サービスラッパーの実装にも役立ちます。

アプリケーションが実行されているHTTPポートを知りたい場合は、local.server.portのキーを持つプロパティを取得します。

2. 外部化された構成

Spring Bootでは、構成を外部化できるため、異なる環境で同じアプリケーションコードを使用できます。プロパティファイル、YAMLファイル、環境変数、およびコマンドライン引数を使用して、構成を外部化できます。プロパティ値は、@Value アノテーションを使用してBeanに直接注入したり、Springの Environment 抽象化を通じてアクセスしたり、@ConfigurationPropertiesを通じて構造化オブジェクトにバインドしたりできます

Spring Bootは、値を適切にオーバーライドできるように設計された、非常に特殊な PropertySource 順序を使用します。プロパティは次の順序で考慮されます。

  1. devtoolsがアクティブな場合、$HOME/.config/spring-boot フォルダー内のDevtoolsグローバル設定プロパティ

  2. テストに関する @TestPropertySource (Javadoc) アノテーション。

  3. テストのproperties 属性。 @SpringBootTest (Javadoc) およびアプリケーションの特定のスライスをテストするためのテストアノテーションで利用可能。

  4. コマンドライン引数。

  5. SPRING_APPLICATION_JSON のプロパティ(環境変数またはシステムプロパティに埋め込まれたインラインJSON)。

  6. ServletConfig 初期化パラメーター。

  7. ServletContext 初期化パラメーター。

  8. java:comp/envからのJNDI属性。

  9. Javaシステムプロパティ(System.getProperties())。

  10. OS環境変数。

  11. random.*のみにプロパティを持つ RandomValuePropertySource

  12. パッケージ化されたjar以外のプロファイル固有のアプリケーションプロパティapplication-{profile}.properties およびYAMLバリアント)。

  13. jar(application-{profile}.properties およびYAMLバリアント)内にパッケージ化されたプロファイル固有のアプリケーションプロパティ

  14. パッケージ化されたjar以外のアプリケーションプロパティ(application.properties およびYAMLバリアント)。

  15. jar内にパッケージ化されたアプリケーションプロパティ(application.properties およびYAMLバリアント)。

  16. @Configuration クラスの @PropertySource (Javadoc) アノテーション。このようなプロパティソースは、アプリケーションコンテキストがリフレッシュされるまで Environment に追加されないことに注意してください。これは、リフレッシュが始まる前に読み込まれる logging.*spring.main.* などの特定のプロパティを設定するには遅すぎます。

  17. デフォルトのプロパティ( SpringApplication.setDefaultPropertiesの設定により指定されます)。

具体例を提供するために、次の例に示すように、name プロパティを使用する @Component を開発するとします。

import org.springframework.stereotype.*;
import org.springframework.beans.factory.annotation.*;

@Component
public class MyBean {

    @Value("${name}")
    private String name;

    // ...

}

アプリケーションのクラスパス(たとえば、jar内)に、nameの適切なデフォルトのプロパティ値を提供する application.properties ファイルを含めることができます。新しい環境で実行する場合、nameをオーバーライドするjarの外部で application.properties ファイルを提供できます。1回限りのテストでは、特定のコマンドラインスイッチ(たとえば java -jar app.jar --name="Spring")で起動できます。

SPRING_APPLICATION_JSON プロパティは、環境変数を使用してコマンドラインで指定できます。例:UN*Xシェルで次の行を使用できます。

$ SPRING_APPLICATION_JSON='{"acme":{"name":"test"}}' java -jar myapp.jar

上記の例では、Spring Environmentacme.name=test になります。次の例に示すように、Systemプロパティで spring.application.json としてJSONを提供することもできます。

$ java -Dspring.application.json='{"name":"test"}' -jar myapp.jar

次の例に示すように、コマンドライン引数を使用してJSONを提供することもできます。

$ java -jar myapp.jar --spring.application.json='{"name":"test"}'

次のように、JSONをJNDI変数として提供することもできます: java:comp/env/spring.application.json

2.1. ランダム値の構成

RandomValuePropertySource は、ランダムな値を挿入するのに便利です(たとえば、シークレットやテストケースに)。次の例に示すように、整数、long、uuid、または文字列を生成できます。

my.secret=${random.value}
my.number=${random.int}
my.bignumber=${random.long}
my.uuid=${random.uuid}
my.number.less.than.ten=${random.int(10)}
my.number.in.range=${random.int[1024,65536]}

random.int* 構文は OPEN value (,max) CLOSE です。OPEN,CLOSE は任意の文字で、value,max は整数です。 max が指定されている場合、value が最小値で、max が最大値(排他的)です。

2.2. コマンドラインプロパティへのアクセス

デフォルトでは、SpringApplication はすべてのコマンドラインオプション引数(つまり、--server.port=9000などの --で始まる引数)を property に変換し、Spring Environmentに追加します。前述のように、コマンドラインプロパティは常に他のプロパティソースよりも優先されます。

コマンドラインプロパティを Environmentに追加したくない場合は、SpringApplication.setAddCommandLineProperties(false)を使用して無効にすることができます。

2.3. アプリケーションプロパティファイル

SpringApplication は、次の場所にある application.properties ファイルからプロパティをロードし、Spring Environmentに追加します。

  1. 現在のディレクトリの /config サブディレクトリ

  2. 現在のディレクトリ

  3. クラスパス /config パッケージ

  4. クラスパスのルート

リストは優先順位に従って並べられます(リストの上位の場所で定義されたプロパティは、下位の場所で定義されたプロパティをオーバーライドします)。

「.properties」の代替としてYAML( '.yml' )ファイルを使用するを使用することもできます。

構成ファイル名として application.properties が気に入らない場合は、spring.config.name 環境プロパティを指定して別のファイル名に切り替えることができます。 spring.config.location 環境プロパティ(ディレクトリの場所またはファイルパスのコンマ区切りリスト)を使用して、明示的な場所を参照することもできます。次の例は、異なるファイル名を指定する方法を示しています。

$ java -jar myproject.jar --spring.config.name=myproject

次の例は、2つの場所を指定する方法を示しています。

$ java -jar myproject.jar --spring.config.location=classpath:/default.properties,classpath:/override.properties
spring.config.name および spring.config.location は、どのファイルをロードする必要があるかを判断するために非常に早い段階で使用されます。これらは、環境プロパティ(通常、OS環境変数、システムプロパティ、またはコマンドライン引数)として定義する必要があります。

spring.config.location に(ファイルではなく)ディレクトリが含まれる場合、/ で終わる必要があります(実行時に、プロファイル固有のファイル名を含む、読み込まれる前に spring.config.name から生成された名前が付加されます)。 spring.config.location で指定されたファイルは、プロファイル固有のバリアントをサポートせずにそのまま使用され、プロファイル固有のプロパティによってオーバーライドされます。

構成の場所は逆の順序で検索されます。デフォルトでは、構成された場所は classpath:/,classpath:/config/,file:./,file:./config/です。結果の検索順序は次のとおりです。

  1. file:./config/

  2. file:./

  3. classpath:/config/

  4. classpath:/

spring.config.locationを使用してカスタム構成の場所を構成すると、デフォルトの場所が置き換えられます。例: spring.config.location が値 classpath:/custom-config/,file:./custom-config/で構成されている場合、検索順序は次のようになります。

  1. file:./custom-config/

  2. classpath:custom-config/

または、spring.config.additional-locationを使用してカスタム構成の場所を構成する場合、デフォルトの場所に加えてそれらが使用されます。デフォルトの場所の前に追加の場所が検索されます。例: classpath:/custom-config/,file:./custom-config/ の追加の場所が構成されている場合、検索順序は次のようになります。

  1. file:./custom-config/

  2. classpath:custom-config/

  3. file:./config/

  4. file:./

  5. classpath:/config/

  6. classpath:/

この検索順序により、ある構成ファイルでデフォルト値を指定し、別の構成ファイルでそれらの値を選択的にオーバーライドできます。デフォルトの場所の1つで、application.properties (または spring.config.nameで選択した他のベース名)でアプリケーションのデフォルト値を提供できます。これらのデフォルト値は、カスタムロケーションのいずれかにある別のファイルで実行時にオーバーライドできます。

システムプロパティではなく環境変数を使用する場合、ほとんどのオペレーティングシステムはピリオド区切りのキー名を許可しませんが、代わりにアンダースコアを使用できます(たとえば、spring.config.nameの代わりに SPRING_CONFIG_NAME )。
アプリケーションがコンテナーで実行される場合、環境変数またはシステムプロパティの代わりに、またはそれらと同様に、JNDIプロパティ( java:comp/env内)またはサーブレットコンテキスト初期化パラメータを使用できます。

2.4. プロファイル固有のプロパティ

application.properties ファイルに加えて、プロファイル固有のプロパティは、命名規則 application-{profile}.propertiesを使用して定義することもできます。 Environment には、アクティブなプロファイルが設定されていない場合に使用される一連のデフォルトプロファイル(デフォルトでは [default])があります。つまり、明示的にアクティブ化されるプロファイルがない場合、application-default.properties のプロパティがロードされます。

プロファイル固有のプロパティは、標準の application.propertiesと同じ場所からロードされます。プロファイル固有のファイルは、パッケージ固有のjarの内部または外部にあるかどうかにかかわらず、常に非固有のものをオーバーライドします。

複数のプロファイルが指定されている場合、後勝ち戦略が適用されます。例: spring.profiles.active プロパティで指定されたプロファイルは、SpringApplication APIで構成されたプロファイルの後に追加されるため、優先されます。

spring.config.locationでファイルを指定した場合、それらのファイルのプロファイル固有のバリアントは考慮されません。プロファイル固有のプロパティも使用する場合は、spring.config.location のディレクトリを使用します。

2.5. プロパティのプレースホルダー

application.properties の値は、使用時に既存の Environment でフィルターされるため、以前に定義された値(たとえば、システムプロパティから)を参照できます。

app.name=MyApp
app.description=${app.name} is a Spring Boot application
この手法を使用して、既存のSpring Bootプロパティの「短い」バリアントを作成することもできます。詳細については、howto.html使い方を参照してください。

2.6. 暗号化プロパティ

Spring Bootは、プロパティ値の暗号化の組み込みサポートを提供しませんが、Spring Environmentに含まれる値を変更するために必要なフックポイントを提供します。 EnvironmentPostProcessor インターフェースを使用すると、アプリケーションを開始する前に Environment を操作できます。詳細については、howto.htmlを参照してください。

資格情報とパスワードを安全に保存する方法を探している場合、Spring Cloud Vault(英語) プロジェクトはHashiCorp Vault(英語) に外部化された構成を保存するためのサポートを提供します。

2.7. プロパティの代わりにYAMLを使用する

YAML(英語) はJSONのスーパーセットであるため、階層構成データを指定するための便利な形式です。 SpringApplication クラスは、クラスパスにSnakeYAML(英語) ライブラリがある場合は常に、プロパティの代替としてYAMLを自動的にサポートします。

「スターター」を使用すると、spring-boot-starterによってSnakeYAMLが自動的に提供されます。

2.7.1. YAMLの読み込み

Spring Frameworkは、YAMLドキュメントのロードに使用できる2つの便利なクラスを提供します。 YamlPropertiesFactoryBean はYAMLを Properties としてロードし、YamlMapFactoryBean はYAMLを Mapとしてロードします。

例:次のYAMLドキュメントを検討します。

environments:
    dev:
        url: https://dev.example.com
        name: Developer Setup
    prod:
        url: https://another.example.com
        name: My Cool App

前述の例は、次のプロパティに変換されます。

environments.dev.url=https://dev.example.com
environments.dev.name=Developer Setup
environments.prod.url=https://another.example.com
environments.prod.name=My Cool App

YAMLリストは、[index] 間接参照を持つプロパティキーとして表されます。例:次のYAMLを検討します。

my:
   servers:
       - dev.example.com
       - another.example.com

前述の例は、次のプロパティに変換されます。

my.servers[0]=dev.example.com
my.servers[1]=another.example.com

Spring Bootの Binder ユーティリティ( @ConfigurationProperties の機能)を使用してそのようなプロパティにバインドするには、タイプ java.util.List (または Set)のターゲットBeanにプロパティが必要であり、setterを提供するか、可変で初期化する必要があります。値。例:次の例は、前に示したプロパティにバインドします。

@ConfigurationProperties(prefix="my")
public class Config {

    private List<String> servers = new ArrayList<String>();

    public List<String> getServers() {
        return this.servers;
    }
}

2.7.2. Spring環境でプロパティとしてYAMLを公開する

YamlPropertySourceLoader クラスを使用して、YAMLをSpring EnvironmentPropertySource として公開できます。これにより、@Value アノテーションをプレースホルダー構文とともに使用して、YAMLプロパティにアクセスできます。

2.7.3. マルチプロファイルYAMLドキュメント

次の例に示すように、spring.profiles キーを使用してドキュメントが適用されるタイミングを示すことにより、単一のファイルに複数のプロファイル固有のYAMLドキュメントを指定できます。

server:
    address: 192.168.1.100
---
spring:
    profiles: development
server:
    address: 127.0.0.1
---
spring:
    profiles: production & eu-central
server:
    address: 192.168.1.120

上記の例では、development プロファイルがアクティブな場合、server.address プロパティは 127.0.0.1です。同様に、production および eu-central プロファイルがアクティブな場合、server.address プロパティは 192.168.1.120です。 development, production および eu-central プロファイルが有効になっていない場合、プロパティの値は 192.168.1.100です。

spring.profiles には、単純なプロファイル名( productionなど)またはプロファイル式を含めることができます。プロファイル式を使用すると、production & (eu-central | eu-west)など、より複雑なプロファイルロジックを表現できます。詳細については、リファレンスガイドを参照してください。

アプリケーションコンテキストの起動時に明示的にアクティブなものがない場合、デフォルトのプロファイルがアクティブになります。そのため、次のYAMLでは、"default" プロファイルでのみ使用可能な spring.security.user.password の値を設定します。

server:
  port: 8000
---
spring:
  profiles: default
  security:
    user:
      password: weak

一方、次の例では、パスワードはプロファイルに関連付けられていないため常に設定されており、必要に応じて他のすべてのプロファイルで明示的にリセットする必要があります。

server:
  port: 8000
spring:
  security:
    user:
      password: weak

spring.profiles 要素を使用して指定されたSpringプロファイルは、! 文字を使用してオプションで無効にすることができます。単一のドキュメントに対して否定プロファイルと非否定プロファイルの両方が指定されている場合、少なくとも1つの非否定プロファイルが一致する必要があり、否定プロファイルは一致しません。

2.7.4. YAMLの欠点

YAMLファイルは、@PropertySource アノテーションを使用してロードできません。そのため、そのように値をロードする必要がある場合は、プロパティファイルを使用する必要があります。

プロファイル固有のYAMLファイルでマルチYAMLドキュメント構文を使用すると、予期しない動作が発生する可能性があります。例:ファイル内の次の構成を検討します。

application-dev.yml
server:
  port: 8000
---
spring:
  profiles: "!test"
  security:
    user:
      password: "secret"

引数 --spring.profiles.active=dev を指定してアプリケーションを実行すると、security.user.password が「secret」に設定されると予想される場合がありますが、そうではありません。

メインファイルの名前は application-dev.ymlであるため、ネストされたドキュメントはフィルターされます。すでにプロファイル固有であると見なされており、ネストされたドキュメントは無視されます。

プロファイル固有のYAMLファイルと複数のYAMLドキュメントを混在させないことをお勧めします。それらの1つだけを使用することに固執します。

2.8. タイプセーフな構成プロパティ

@Value("${property}") アノテーションを使用して構成プロパティを注入することは、特に複数のプロパティを使用している場合、またはデータが本質的に階層的である場合には、面倒な場合があります。Spring Bootは、強く型付けされたBeanがアプリケーションの構成を管理および検証できるようにするプロパティを操作する代替方法を提供します。

2.8.1. JavaBeanプロパティバインディング

次の例に示すように、標準JavaBeanプロパティを宣言するBeanをバインドすることができます。

package com.example;

import java.net.InetAddress;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("acme")
public class AcmeProperties {

    private boolean enabled;

    private InetAddress remoteAddress;

    private final Security security = new Security();

    public boolean isEnabled() { ... }

    public void setEnabled(boolean enabled) { ... }

    public InetAddress getRemoteAddress() { ... }

    public void setRemoteAddress(InetAddress remoteAddress) { ... }

    public Security getSecurity() { ... }

    public static class Security {

        private String username;

        private String password;

        private List<String> roles = new ArrayList<>(Collections.singleton("USER"));

        public String getUsername() { ... }

        public void setUsername(String username) { ... }

        public String getPassword() { ... }

        public void setPassword(String password) { ... }

        public List<String> getRoles() { ... }

        public void setRoles(List<String> roles) { ... }

    }
}

前述のPOJOは、次のプロパティを定義します。

  • acme.enabled、デフォルトでは false の値。

  • Stringから強制変換できるタイプのacme.remote-address

  • acme.security.username、プロパティの名前によって名前が決定されるネストされた「セキュリティ」オブジェクト。特に、戻り値の型はそこではまったく使用されておらず、SecurityPropertiesである可能性があります。

  • acme.security.password .

  • acme.security.roles。デフォルトは USERである String のコレクションです。

Spring Bootで利用可能な @ConfigurationProperties クラスにマッピングされるプロパティは、プロパティファイル、YAMLファイル、環境変数などを介して設定されますが、パブリックAPIですが、クラス自体のアクセサー(getter/setter)は直接使用するためのものではありません。

そのような配置はデフォルトの空のコンストラクターに依存し、getterおよびsetterは、Spring MVCのように標準のJava Beanプロパティ記述子を介して行われるため、通常必須です。setterは、次の場合に省略できます。

  • マップは、初期化されている限り、getterを必要としますが、必ずしもsetterを必要とするわけではありません。バインダーによって変更できるためです。

  • コレクションと配列には、インデックス(通常はYAMLを使用)または単一のコンマ区切り値(プロパティ)を使用してアクセスできます。後者の場合、setterは必須です。そのようなタイプには、常にsetterを追加することをお勧めします。コレクションを初期化する場合は、不変でないことを確認してください(前の例のように)。

  • ネストされたPOJOプロパティが初期化される場合(前述の例の Security フィールドのように)、setterは必要ありません。デフォルトのコンストラクターを使用して、バインダーがその場でインスタンスを作成するようにするには、setterが必要です。

Project Lombokを使用してgetterとsetterを自動的に追加する人もいます。Lombokは、オブジェクトをインスタンス化するためにコンテナーによって自動的に使用されるため、そのようなタイプの特定のコンストラクターを生成しないことを確認してください。

最後に、標準のJava Beanプロパティのみが考慮され、静的プロパティのバインドはサポートされていません。

2.8.2. コンストラクターバインディング

前のセクションの例は、次の例に示すように不変の方法で書き換えることができます。

package com.example;

import java.net.InetAddress;
import java.util.List;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.ConstructorBinding;
import org.springframework.boot.context.properties.DefaultValue;

@ConstructorBinding
@ConfigurationProperties("acme")
public class AcmeProperties {

    private final boolean enabled;

    private final InetAddress remoteAddress;

    private final Security security;

    public AcmeProperties(boolean enabled, InetAddress remoteAddress, Security security) {
        this.enabled = enabled;
        this.remoteAddress = remoteAddress;
        this.security = security;
    }

    public boolean isEnabled() { ... }

    public InetAddress getRemoteAddress() { ... }

    public Security getSecurity() { ... }

    public static class Security {

        private final String username;

        private final String password;

        private final List<String> roles;

        public Security(String username, String password,
                @DefaultValue("USER") List<String> roles) {
            this.username = username;
            this.password = password;
            this.roles = roles;
        }

        public String getUsername() { ... }

        public String getPassword() { ... }

        public List<String> getRoles() { ... }

    }

}

このセットアップでは、@ConstructorBinding アノテーションを使用して、コンストラクターバインディングを使用する必要があることを示します。これは、バインダーがバインドしたいパラメーターを持つコンストラクターを見つけることを期待することを意味します。

@ConstructorBinding クラスのネストされたメンバー(上記の例の Security など)も、コンストラクターを介してバインドされます。

@DefaultValue を使用してデフォルト値を指定でき、String 値を欠落しているプロパティのターゲットタイプに強制するために同じ変換サービスが適用されます。

コンストラクターバインディングを使用するには、@EnableConfigurationProperties または構成プロパティスキャンを使用してクラスを有効にする必要があります。通常のSpringメカニズムによって作成されたBeanでコンストラクターバインディングを使用することはできません。(たとえば @Component Bean、@Bean メソッドを介して作成されたBean、または @Importを使用してロードされたBean )
クラスに複数のコンストラクターがある場合は、バインドする必要があるコンストラクターで @ConstructorBinding を直接使用することもできます。

2.8.3. @ConfigurationPropertiesアノテーション付きタイプの有効化

Spring Bootは、@ConfigurationProperties タイプをバインドし、Beanとして登録するためのインフラストラクチャを提供します。クラスごとに構成プロパティを有効にするか、コンポーネントスキャンと同様に機能する構成プロパティスキャンを有効にすることができます。

@ConfigurationProperties アノテーションが付けられたクラスは、たとえば、独自の自動構成を開発している場合や、条件付きで有効にしたい場合など、スキャンに適さない場合があります。これらの場合、@EnableConfigurationProperties アノテーションを使用して処理するタイプのリストを指定します。これは、次の例に示すように、@Configuration クラスで実行できます。

@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(AcmeProperties.class)
public class MyConfiguration {
}

構成プロパティのスキャンを使用するには、@ConfigurationPropertiesScan アノテーションをアプリケーションに追加します。通常、@SpringBootApplication アノテーションが付けられたメインアプリケーションクラスに追加されますが、任意の @Configuration クラスに追加できます。デフォルトでは、アノテーションを宣言するクラスのパッケージからスキャンが行われます。スキャンする特定のパッケージを定義する場合は、次の例に示すように定義できます。

@SpringBootApplication
@ConfigurationPropertiesScan({ "com.example.app", "org.acme.another" })
public class MyApplication {
}

@ConfigurationProperties Beanが構成プロパティのスキャンまたは @EnableConfigurationPropertiesを使用して登録されている場合、Beanには従来の名前 <prefix>-<fqn>があります。<prefix>@ConfigurationProperties アノテーションで指定された環境キーのプレフィックスで、<fqn> はBeanの完全修飾名です。アノテーションが接頭部を提供しない場合、Beanの完全修飾名のみが使用されます。

上記の例のBean名は acme-com.example.AcmePropertiesです。

@ConfigurationProperties は環境のみを扱い、特にコンテキストから他のBeanを注入しないことをお勧めします。コーナーケースの場合、setterインジェクションを使用するか、フレームワークによって提供される *Aware インターフェースのいずれか( Environmentへのアクセスが必要な場合は EnvironmentAware など)を使用できます。それでもコンストラクターを使用して他のBeanを注入する場合は、構成プロパティBeanに @Component のアノテーションを付け、JavaBeanベースのプロパティバインディングを使用する必要があります。

2.8.4. @ConfigurationPropertiesアノテーション付きタイプの使用

このスタイルの構成は、次の例に示すように、SpringApplication 外部YAML構成で特にうまく機能します。

# application.yml

acme:
    remote-address: 192.168.1.1
    security:
        username: admin
        roles:
          - USER
          - ADMIN

# additional configuration as required

@ConfigurationProperties Beanを使用するには、次の例に示すように、他のBeanと同じ方法で注入できます。

@Service
public class MyService {

    private final AcmeProperties properties;

    @Autowired
    public MyService(AcmeProperties properties) {
        this.properties = properties;
    }

    //...

    @PostConstruct
    public void openConnection() {
        Server server = new Server(this.properties.getRemoteAddress());
        // ...
    }

}
@ConfigurationProperties を使用すると、IDEで使用できるメタデータファイルを生成して、独自のキーの自動補完を提供することもできます。詳細については、付録を参照してください。

2.8.5. サードパーティの構成

@ConfigurationProperties を使用してクラスにアノテーションを付けるだけでなく、パブリック @Bean メソッドでも使用できます。これは、コントロール外のサードパーティコンポーネントにプロパティをバインドする場合に特に役立ちます。

Environment プロパティからBeanを構成するには、次の例に示すように、@ConfigurationProperties をBean登録に追加します。

@ConfigurationProperties(prefix = "another")
@Bean
public AnotherComponent anotherComponent() {
    ...
}

another プレフィックスで定義されたJavaBeanプロパティは、前述の AcmeProperties の例と同様の方法で、その AnotherComponent Beanにマッピングされます。

2.8.6. 緩いバインディング

Spring Bootは、Environment プロパティを @ConfigurationProperties Beanにバインドするためにいくつかの緩和されたルールを使用しているため、Environment プロパティ名とBeanプロパティ名が完全に一致する必要はありません。これが役立つ一般的な例には、ダッシュで区切られた環境プロパティ(たとえば、context-pathcontextPathにバインド)、大文字の環境プロパティ(たとえば、PORTportにバインド)があります。

例として、次の @ConfigurationProperties クラスを検討してください。

@ConfigurationProperties(prefix="acme.my-project.person")
public class OwnerProperties {

    private String firstName;

    public String getFirstName() {
        return this.firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

}

上記のコードでは、次のプロパティ名をすべて使用できます。

テーブル 2: 緩いバインディング
プロパティメモ

acme.my-project.person.first-name

.properties および .yml ファイルでの使用が推奨されるケバブケース。

acme.myProject.person.firstName

標準のキャメルケースの構文。

acme.my_project.person.first_name

アンダースコア表記。.properties および .yml ファイルで使用するための代替形式です。

ACME_MYPROJECT_PERSON_FIRSTNAME

システム環境変数を使用する場合に推奨される大文字形式。

アノテーションの prefix 値はケバブの場合(小文字で、acme.my-project.personなどの -で区切られている)でなければなりません
表3: プロパティソースごとの緩いバインディングルール
プロパティソースシンプルリスト

プロパティファイル

キャメルケース、ケバブケース、またはアンダースコア表記

[ ] またはコンマ区切り値を使用した標準リスト構文

YAML ファイル

キャメルケース、ケバブケース、またはアンダースコア表記

標準のYAMLリスト構文またはコンマ区切り値

環境変数

区切り文字としてアンダースコアを使用した大文字形式。 _ はプロパティ名内では使用しないでください

アンダースコアで囲まれた数値( MY_ACME_1_OTHER = my.acme[1].otherなど)

システムプロパティ

キャメルケース、ケバブケース、またはアンダースコア表記

[ ] またはコンマ区切り値を使用した標準リスト構文

可能な場合、プロパティは my.property-name=acmeなどの小文字のケバブ形式で保存することをお勧めします。

Map プロパティにバインドするときに、key に小文字の英数字または -以外のものが含まれている場合、元の値が保持されるように括弧表記を使用する必要があります。キーが []で囲まれていない場合、英数字でも - でもない文字はすべて削除されます。例:次のプロパティを Mapにバインドすることを検討してください。

acme:
  map:
    "[/key1]": value1
    "[/key2]": value2
    /key3: value3

上記のプロパティは、/key1, /key2key3 をマップのキーとして Map にバインドします。

YAMLファイルの場合、キーを適切に解析するには、括弧を引用符で囲む必要があります。

2.8.7. 複合型のマージ

リストが複数の場所で構成されている場合、オーバーライドはリスト全体を置き換えることで機能します。

例: null である name および description 属性を持つ MyPojo オブジェクトをデフォルトと想定します。次の例は、AcmePropertiesから MyPojo オブジェクトのリストを公開します。

@ConfigurationProperties("acme")
public class AcmeProperties {

    private final List<MyPojo> list = new ArrayList<>();

    public List<MyPojo> getList() {
        return this.list;
    }

}

次の構成を検討してください。

acme:
  list:
    - name: my name
      description: my description
---
spring:
  profiles: dev
acme:
  list:
    - name: my another name

dev プロファイルがアクティブでない場合、AcmeProperties.list には、前に定義したように1つの MyPojo エントリーが含まれます。ただし、dev プロファイルが有効になっている場合、list にはまだ 1つのエントリしか含まれていません(名前が my another name で説明が null)。この構成で、2番目の MyPojo インスタンスはリストに追加されず、アイテムはマージされません。

List が複数のプロファイルで指定されている場合、最高の優先順位を持つプロファイル(およびそのプロファイルのみ)が使用されます。次の例を考えてみましょう。

acme:
  list:
    - name: my name
      description: my description
    - name: another name
      description: another description
---
spring:
  profiles: dev
acme:
  list:
    - name: my another name

上記の例で、dev プロファイルがアクティブである場合、AcmeProperties.list には1つの MyPojo エントリー(名前 my another name および説明 null)が含まれます。YAMLの場合、コンマ区切りリストとYAMLリストの両方を使用して、リストの内容を完全にオーバーライドできます。

Map プロパティの場合、複数のソースから取得したプロパティ値とバインドできます。ただし、複数のソースの同じプロパティの場合、優先度が最も高いプロパティが使用されます。次の例は、AcmePropertiesから Map<String, MyPojo> を公開します。

@ConfigurationProperties("acme")
public class AcmeProperties {

    private final Map<String, MyPojo> map = new HashMap<>();

    public Map<String, MyPojo> getMap() {
        return this.map;
    }

}

次の構成を検討してください。

acme:
  map:
    key1:
      name: my name 1
      description: my description 1
---
spring:
  profiles: dev
acme:
  map:
    key1:
      name: dev name 1
    key2:
      name: dev name 2
      description: dev description 2

dev プロファイルがアクティブでない場合、AcmeProperties.map にはキー key1 (名前 my name 1 および説明 my description 1)を持つ1つのエントリーが含まれます。ただし、dev プロファイルが有効になっている場合、map には、キー key1 (名前 dev name 1 および説明 my description 1)および key2 (名前 dev name 2 および説明 dev description 2)の2つのエントリが含まれます。

前述のマージルールは、YAMLファイルだけでなく、すべてのプロパティソースのプロパティに適用されます。

2.8.8. プロパティの変換

Spring Bootは、@ConfigurationProperties Beanにバインドするときに、外部アプリケーションプロパティを正しいタイプに強制しようとします。カスタムタイプの変換が必要な場合は、ConversionService Bean( conversionServiceという名前のBeanを使用)またはカスタムプロパティエディター( CustomEditorConfigurer Beanを使用)またはカスタム Converters@ConfigurationPropertiesBindingとしてアノテーション付けされたBean定義を使用)を提供できます。

このBeanはアプリケーションライフサイクルの非常に早い段階で要求されるため、ConversionService が使用している依存関係を必ず制限してください。通常、必要な依存関係は作成時に完全に初期化されない場合があります。構成キーの強制に不要なカスタム ConversionService の名前を変更し、@ConfigurationPropertiesBindingで修飾されたカスタムコンバーターのみに依存することができます。
期間の変換

Spring Bootは、期間を表現するための専用サポートを備えています。 java.time.Duration プロパティを公開する場合、アプリケーションプロパティで次の形式を使用できます。

  • 通常の long 表現 ( @DurationUnit が指定されていない限り、デフォルトの単位としてミリ秒を使用する)

  • java.time.Durationが使用する 標準ISO-8601形式

  • 値と単位が結合された、より読みやすい形式 (たとえば 10s は10秒を意味する)

次の例を考えてみましょう。

@ConfigurationProperties("app.system")
public class AppSystemProperties {

    @DurationUnit(ChronoUnit.SECONDS)
    private Duration sessionTimeout = Duration.ofSeconds(30);

    private Duration readTimeout = Duration.ofMillis(1000);

    public Duration getSessionTimeout() {
        return this.sessionTimeout;
    }

    public void setSessionTimeout(Duration sessionTimeout) {
        this.sessionTimeout = sessionTimeout;
    }

    public Duration getReadTimeout() {
        return this.readTimeout;
    }

    public void setReadTimeout(Duration readTimeout) {
        this.readTimeout = readTimeout;
    }

}

30秒のセッションタイムアウトを指定するには、30, PT30S30s はすべて同等です。500ミリ秒の読み取りタイムアウトは、500, PT0.5S および 500msのいずれかの形式で指定できます。

サポートされている任意のユニットを使用することもできます。これらは:

  • ns ナノ秒

  • us マイクロ秒

  • ms ミリ秒

  • s

  • m

  • h 時間

  • d

デフォルトの単位はミリ秒であり、上記のサンプルに示すように、@DurationUnit を使用してオーバーライドできます。

単に Long を使用して継続時間を表す以前のバージョンからアップグレードする場合、Durationへの切り替えとともにミリ秒単位でない場合は、ユニットを( @DurationUnitを使用して)定義するようにしてください。これにより、より豊富な形式をサポートしながら、透過的なアップグレードパスが提供されます。
データサイズの変換

Spring Frameworkには、サイズをバイト単位で表す DataSize 値タイプがあります。 DataSize プロパティを公開する場合、アプリケーションプロパティで次の形式を使用できます。

  • 通常の long 表現 ( @DataSizeUnit が指定されていない限り、デフォルトの単位としてバイトを使用)

  • 値と単位が結合された、より読みやすい形式 (たとえば 10MB は10メガバイトを意味する)

次の例を考えてみましょう。

@ConfigurationProperties("app.io")
public class AppIoProperties {

    @DataSizeUnit(DataUnit.MEGABYTES)
    private DataSize bufferSize = DataSize.ofMegabytes(2);

    private DataSize sizeThreshold = DataSize.ofBytes(512);

    public DataSize getBufferSize() {
        return this.bufferSize;
    }

    public void setBufferSize(DataSize bufferSize) {
        this.bufferSize = bufferSize;
    }

    public DataSize getSizeThreshold() {
        return this.sizeThreshold;
    }

    public void setSizeThreshold(DataSize sizeThreshold) {
        this.sizeThreshold = sizeThreshold;
    }

}

10メガバイトのバッファーサイズを指定するには、1010MB は同等です。256バイトのサイズしきい値は、256 または 256Bとして指定できます。

サポートされている任意のユニットを使用することもできます。これらは:

  • B バイト

  • KB キロバイト

  • MB メガバイト

  • GB ギガバイト

  • TB テラバイト

デフォルトの単位はバイトであり、上記のサンプルに示すように @DataSizeUnit を使用してオーバーライドできます。

単に Long を使用してサイズを表現している以前のバージョンからアップグレードする場合、DataSizeへのスイッチと一緒にバイトでない場合は、ユニットを( @DataSizeUnitを使用して)必ず定義してください。これにより、より豊富な形式をサポートしながら、透過的なアップグレードパスが提供されます。

2.8.9. @ConfigurationProperties検証

Spring Bootは、Springの @Validated アノテーションが付けられている場合、@ConfigurationProperties クラスを検証しようとします。JSR-303 javax.validation 制約アノテーションを構成クラスで直接使用できます。これを行うには、次の例に示すように、準拠するJSR-303実装がクラスパス上にあることを確認してから、フィールドに制約アノテーションを追加します。

@ConfigurationProperties(prefix="acme")
@Validated
public class AcmeProperties {

    @NotNull
    private InetAddress remoteAddress;

    // ... getters and setters

}
@Validatedを使用して構成プロパティを作成する @Bean メソッドにアノテーションを付けることにより、検証をトリガーすることもできます。

ネストされたプロパティに対して検証が常にトリガーされるようにするには、プロパティが見つからない場合でも、関連付けられたフィールドに @Validのアノテーションを付ける必要があります。次の例は、前述の AcmeProperties の例に基づいています。

@ConfigurationProperties(prefix="acme")
@Validated
public class AcmeProperties {

    @NotNull
    private InetAddress remoteAddress;

    @Valid
    private final Security security = new Security();

    // ... getters and setters

    public static class Security {

        @NotEmpty
        public String username;

        // ... getters and setters

    }

}

configurationPropertiesValidatorというBean定義を作成して、カスタムSpring Validator を追加することもできます。 @Bean メソッドは staticとして宣言する必要があります。構成プロパティバリデーターは、アプリケーションのライフサイクルの非常に早い段階で作成され、@Bean メソッドを静的として宣言すると、@Configuration クラスをインスタンス化せずにBeanを作成できます。そうすることで、早期のインスタンス化によって引き起こされる可能性のある問題を回避できます。

spring-boot-actuator モジュールには、すべての @ConfigurationProperties Beanを公開するエンドポイントが含まれています。Webブラウザーで /actuator/configprops を指すか、同等のJMXエンドポイントを使用します。詳細については、「本番対応機能」セクションを参照してください。

2.8.10. @ConfigurationProperties対@Value

@Value アノテーションはコアコンテナー機能であり、タイプセーフな構成プロパティと同じ機能を提供しません。次の表は、@ConfigurationProperties および @Valueでサポートされている機能をまとめたものです。

フィーチャー @ConfigurationProperties @Value

Relaxed binding

はい

いいえ

メタデータのサポート

はい

いいえ

SpEL 評価

いいえ

はい

独自のコンポーネントの設定キーのセットを定義する場合、@ConfigurationPropertiesアノテーションが付けられたPOJOにグループ化することをお勧めします。また、@Value は緩いバインディングをサポートしていないため、環境変数を使用して値を提供する必要がある場合には適していません。

最後に、@ValueSpEL 式を記述できますが、そのような式はアプリケーションプロパティファイルから処理されません。

3. プロファイル

Springプロファイルは、アプリケーション構成の一部を分離し、特定の環境でのみ使用可能にする方法を提供します。次の例に示すように、@Component, @Configuration または @ConfigurationProperties@Profile のマークを付けて、ロード時を制限できます。

@Configuration(proxyBeanMethods = false)
@Profile("production")
public class ProductionConfiguration {

    // ...

}
@ConfigurationProperties Beanが自動スキャンの代わりに @EnableConfigurationProperties を介して登録されている場合、@EnableConfigurationProperties アノテーションを持つ @Configuration クラスで @Profile アノテーションを指定する必要があります。 @ConfigurationProperties がスキャンされる場合、@ConfigurationProperties クラス自体で @Profile を指定できます。

spring.profiles.active Environment プロパティを使用して、アクティブなプロファイルを指定できます。この章で前述した任意の方法でプロパティを指定できます。例:次の例に示すように、application.propertiesに含めることができます。

spring.profiles.active=dev,hsqldb

次のスイッチ --spring.profiles.active=dev,hsqldbを使用して、コマンドラインで指定することもできます。

3.1. アクティブプロファイルの追加

spring.profiles.active プロパティは、他のプロパティと同じ順序付けルールに従います:最高の PropertySource が勝ちます。つまり、application.properties でアクティブなプロファイルを指定し、コマンドラインスイッチを使用して置き換えることができます。

アクティブなプロファイルを置き換えるのではなく、プロファイルに追加するプロファイル固有のプロパティがあると便利な場合があります。 spring.profiles.include プロパティを使用して、アクティブなプロファイルを無条件に追加できます。 SpringApplication エントリポイントには、追加のプロファイルを設定するためのJava APIもあります(つまり、spring.profiles.active プロパティによってアクティブ化されたプロファイルの上にあります)。SpringApplication(Javadoc) setAdditionalProfiles() メソッドを参照してください。

例:スイッチ --spring.profiles.active=prodを使用して次のプロパティを持つアプリケーションを実行すると、proddb および prodmq プロファイルもアクティブになります。

---
my.property: fromyamlfile
---
spring.profiles: prod
spring.profiles.include:
  - proddb
  - prodmq
spring.profiles プロパティをYAMLドキュメントで定義して、この特定のドキュメントがいつ構成に含まれるかを決定できることに注意してください。詳細については、howto.htmlを参照してください。

3.2. プログラムでプロファイルを設定する

アプリケーションを実行する前に SpringApplication.setAdditionalProfiles(…​) を呼び出すことにより、アクティブなプロファイルをプログラムで設定できます。Springの ConfigurableEnvironment インターフェースを使用してプロファイルをアクティブにすることもできます。

3.3. プロファイル固有の構成ファイル

application.properties (または application.yml)と @ConfigurationProperties を介して参照されるファイルの両方のプロファイル固有のバリアントは、ファイルと見なされ、ロードされます。詳細については、「プロファイル固有のプロパティ」を参照してください。

4. ロギング

Spring Bootは、すべての内部ロギングにCommons Logging(Apache) を使用しますが、基礎となるログ実装はオープンなままです。Java Utilロギング Log4J2(Apache) 、およびLogback(英語) のデフォルト構成が提供されています。いずれの場合も、ロガーはコンソール出力を使用するように事前設定されており、オプションのファイル出力も利用できます。

デフォルトでは、「スターター」を使用する場合、Logbackがロギングに使用されます。Java Util Logging、Commons Logging、Log4J、またはSLF4Jを使用する依存ライブラリがすべて正常に機能するように、適切なLogbackルーティングも含まれています。

Javaには多くのロギングフレームワークがあります。上記のリストがわかりにくい場合でも心配しないでください。通常、ロギングの依存関係を変更する必要はなく、Spring Bootのデフォルトは問題なく機能します。
アプリケーションをサーブレットコンテナーまたはアプリケーションサーバーにデプロイする場合、Java Util Logging APIを介して実行されたログは、アプリケーションのログにルーティングされません。これにより、コンテナーまたはコンテナーにデプロイされた他のアプリケーションによって実行されたロギングが、アプリケーションのログに表示されなくなります。

4.1. ログ形式

Spring Bootからのデフォルトのログ出力は、次の例のようになります。

2019-03-05 10:57:51.112  INFO 45469 --- [           main] org.apache.catalina.core.StandardEngine  : Starting Servlet Engine: Apache Tomcat/7.0.52
2019-03-05 10:57:51.253  INFO 45469 --- [ost-startStop-1] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2019-03-05 10:57:51.253  INFO 45469 --- [ost-startStop-1] o.s.web.context.ContextLoader            : Root WebApplicationContext: initialization completed in 1358 ms
2019-03-05 10:57:51.698  INFO 45469 --- [ost-startStop-1] o.s.b.c.e.ServletRegistrationBean        : Mapping servlet: 'dispatcherServlet' to [/]
2019-03-05 10:57:51.702  INFO 45469 --- [ost-startStop-1] o.s.b.c.embedded.FilterRegistrationBean  : Mapping filter: 'hiddenHttpMethodFilter' to: [/*]

次の項目が出力されます。

  • 日付と時刻:ミリ秒の精度と簡単に並べ替え可能。

  • ログレベル: ERROR, WARN, INFO, DEBUGまたは TRACE

  • プロセス ID。

  • 実際のログメッセージの開始を区別する --- セパレータ。

  • スレッド名:角括弧で囲まれています(コンソール出力では切り捨てられる場合があります)。

  • ロガー名:これは通常、ソースクラス名です(多くの場合省略されます)。

  • ログメッセージ。

Logbackには FATAL レベルはありません。 ERRORにマップされます。

4.2. コンソール出力

デフォルトのログ構成では、メッセージが書き込まれるとコンソールにエコーされます。デフォルトでは、ERROR -level、WARN -level、および INFO -levelメッセージがログに記録されます。 --debug フラグを使用してアプリケーションを起動することにより、「デバッグ」モードを有効にすることもできます。

$ java -jar myapp.jar --debug
application.propertiesdebug=true を指定することもできます。

デバッグモードを有効にすると、コアロガー(埋め込みコンテナー、Hibernate、およびSpring Boot)の選択がより多くの情報を出力するように構成されます。デバッグモードを有効にしても、DEBUG レベルのすべてのメッセージをログに記録するようにアプリケーションが設定されるわけではありませ

または、--trace フラグ(または application.propertiestrace=true )を使用してアプリケーションを開始することにより、「トレース」モードを有効にすることができます。これにより、選択されたコアロガー(埋め込みコンテナー、Hibernateスキーマ生成、およびSpringポートフォリオ全体)のトレースログが有効になります。

4.2.1. 色分けされた出力

ターミナルがANSIをサポートしている場合、読みやすくするためにカラー出力が使用されます。 spring.output.ansi.enabledサポートされている値(Javadoc) に設定して、自動検出をオーバーライドできます。

カラーコーディングは、%clr 変換ワードを使用して構成されます。最も単純な形式では、次の例に示すように、コンバーターはログレベルに従って出力に色を付けます。

%clr(%5p)

次の表に、ログレベルと色のマッピングを示します。

レベル

FATAL

ERROR

WARN

INFO

DEBUG

TRACE

または、変換のオプションとして使用することにより、使用する色またはスタイルを指定できます。例:テキストを黄色にするには、次の設定を使用します。

%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){yellow}

次の色とスタイルがサポートされています。

  • blue

  • cyan

  • faint

  • green

  • magenta

  • red

  • yellow

4.3. ファイル出力

デフォルトでは、Spring Bootはコンソールにのみログを記録し、ログファイルを書き込みません。コンソール出力に加えてログファイルを書き込む場合は、logging.file.name または logging.file.path プロパティを設定する必要があります(たとえば、application.propertiesで)。

次の表は、logging.* プロパティを一緒に使用する方法を示しています。

表4: ロギングプロパティ
logging.file.name logging.file.path サンプル説明

(なし)

(なし)

コンソールのみのロギング。

特定のファイル

(なし)

my.log

指定されたログファイルに書き込みます。名前は、正確な場所でも、現在のディレクトリからの相対名でもかまいません。

(なし)

特定のディレクトリ

/var/log

指定されたディレクトリに spring.log を書き込みます。名前は、正確な場所でも、現在のディレクトリからの相対名でもかまいません。

ログファイルは10 MBに達するとローテーションし、コンソール出力と同様に、ERROR -level、WARN -level、および INFO -levelメッセージがデフォルトでログに記録されます。サイズの制限は、logging.file.max-size プロパティを使用して変更できます。 logging.file.max-history プロパティが設定されていない限り、過去7日間のローテーションされたログファイルはデフォルトで保持されます。ログアーカイブの合計サイズは、logging.file.total-size-capを使用して上限を設定できます。ログアーカイブの合計サイズがそのしきい値を超えると、バックアップが削除されます。アプリケーションの起動時にログアーカイブのクリーンアップを強制するには、logging.file.clean-history-on-start プロパティを使用します。

ロギングプロパティは、実際のロギングインフラストラクチャから独立しています。その結果、特定の構成キー(Logbackの logback.configurationFile など)はspring Bootによって管理されません。

4.4. ログレベル

サポートされているすべてのロギングシステムでは、level がTRACE、DEBUG、INFO、WARN、ERROR、FATAL、またはOFFのいずれかである logging.level.<logger-name>=<level> を使用して、Spring Environment (たとえば application.properties)にロガーレベルを設定できます。 root ロガーは、logging.level.rootを使用して構成できます。

次の例は、application.propertiesの潜在的なロギング設定を示しています。

logging.level.root=warn
logging.level.org.springframework.web=debug
logging.level.org.hibernate=error

環境変数を使用してログレベルを設定することもできます。例: LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUGorg.springframework.webDEBUGに設定します。

上記のアプローチは、パッケージレベルのログに対してのみ機能します。緩いバインディングは常に環境変数を小文字に変換するため、この方法で個々のクラスのロギングを構成することはできません。クラスのロギングを構成する必要がある場合は、SPRING_APPLICATION_JSON変数を使用できます。

4.5. ロググループ

関連するロガーをグループ化して、すべてを同時に構成できると便利な場合がよくあります。例:Tomcat関連のすべてのロガーのログレベルを一般的に変更することはできますが、トップレベルのパッケージを簡単に思い出すことはできません。

これを支援するために、Spring Bootでは、Spring Environmentでロギンググループを定義できます。例: application.propertiesに追加して「tomcat」グループを定義する方法は次のとおりです。

logging.group.tomcat=org.apache.catalina, org.apache.coyote, org.apache.tomcat

定義したら、グループ内のすべてのロガーのレベルを1行で変更できます。

logging.level.tomcat=TRACE

Spring Bootには、すぐに使用できる次の事前定義されたロギンググループが含まれています。

名前ロガー

Web

org.springframework.core.codec, org.springframework.http, org.springframework.web, org.springframework.boot.actuate.endpoint.web, org.springframework.boot.web.servlet.ServletContextInitializerBeans

sql

org.springframework.jdbc.core, org.hibernate.SQL, org.jooq.tools.LoggerListener

4.6. カスタムログ設定

さまざまなロギングシステムは、クラスパスに適切なライブラリを含めることでアクティブにでき、クラスパスのルートまたは次のSpring Environment プロパティで指定された場所に適切な構成ファイルを提供することでさらにカスタマイズできます: logging.config

org.springframework.boot.logging.LoggingSystem システムプロパティを使用して、Spring Bootに特定のログシステムを強制的に使用させることができます。値は、LoggingSystem 実装の完全修飾クラス名でなければなりません。 noneの値を使用して、Spring Bootのログ設定を完全に無効にすることもできます。

ApplicationContext が作成される前にロギングが初期化されるため、Spring @Configuration ファイルの @PropertySources からロギングを制御することはできません。ロギングシステムを変更または完全に無効にする唯一の方法は、システムプロパティを使用することです。

ロギングシステムに応じて、次のファイルがロードされます。

ロギングシステムカスタム

Logback

logback-spring.xml, logback-spring.groovy, logback.xmlまたは logback.groovy

Log4j2

log4j2-spring.xml または log4j2.xml

JDK (Java Utilロギング)

logging.properties

可能な場合、ロギング構成に -spring バリアントを使用することをお勧めします(たとえば、logback.xmlではなく logback-spring.xml )。標準の構成場所を使用する場合、Springはログの初期化を完全に制御できません。
Java Util Loggingには、「実行可能なjar」から実行するときに課題を引き起こす既知のクラスローディングの課題があります。「実行可能なjar」から実行する場合は、可能な限り回避することをお勧めします。

カスタマイズを支援するために、次の表で説明するように、他のいくつかのプロパティがSpring Environment からシステムプロパティに転送されます。

Spring環境システムプロパティコメント

logging.exception-conversion-word

LOG_EXCEPTION_CONVERSION_WORD

例外を記録するときに使用される変換語。

logging.file.clean-history-on-start

LOG_FILE_CLEAN_HISTORY_ON_START

起動時にアーカイブログファイルを消去するかどうか(LOG_FILEが有効な場合)。(デフォルトのLogbackセットアップでのみサポートされます。)

logging.file.name

LOG_FILE

定義されている場合、デフォルトのログ構成で使用されます。

logging.file.max-size

LOG_FILE_MAX_SIZE

ログファイルの最大サイズ(LOG_FILEが有効な場合)。(デフォルトのLogbackセットアップでのみサポートされます。)

logging.file.max-history

LOG_FILE_MAX_HISTORY

保持するアーカイブログファイルの最大数(LOG_FILEが有効な場合)。(デフォルトのLogbackセットアップでのみサポートされます。)

logging.file.path

LOG_PATH

定義されている場合、デフォルトのログ構成で使用されます。

logging.file.total-size-cap

LOG_FILE_TOTAL_SIZE_CAP

保持するログバックアップの合計サイズ(LOG_FILEが有効な場合)。(デフォルトのLogbackセットアップでのみサポートされます。)

logging.pattern.console

CONSOLE_LOG_PATTERN

コンソール(stdout)で使用するログパターン。(デフォルトのLogbackセットアップでのみサポートされます。)

logging.pattern.dateformat

LOG_DATEFORMAT_PATTERN

ログ日付形式のアペンダーパターン。(デフォルトのLogbackセットアップでのみサポートされます。)

logging.pattern.file

FILE_LOG_PATTERN

ファイルで使用するログパターン( LOG_FILE が有効な場合)。(デフォルトのLogbackセットアップでのみサポートされます。)

logging.pattern.level

LOG_LEVEL_PATTERN

ログレベルをレンダリングするときに使用する形式(デフォルト %5p)。(デフォルトのLogbackセットアップでのみサポートされます。)

logging.pattern.rolling-file-name

ROLLING_FILE_NAME_PATTERN

ロールオーバーされたログファイル名のパターン(デフォルト ${LOG_FILE}.%d{yyyy-MM-dd}.%i.gz)。(デフォルトのLogbackセットアップでのみサポートされます。)

PID

PID

現在のプロセスID(可能な場合、OS環境変数としてまだ定義されていない場合に検出されます)。

サポートされているすべてのログシステムは、構成ファイルを解析するときにシステムプロパティを参照できます。例については、spring-boot.jar のデフォルト構成を参照してください。

ロギングプロパティでプレースホルダーを使用する場合は、基になるフレームワークの構文ではなく、Spring Bootの構文を使用する必要があります。特に、Logbackを使用する場合は、: をプロパティ名とそのデフォルト値の間の区切り文字として使用し、:-は使用しないでください。

LOG_LEVEL_PATTERN (またはLogbackで logging.pattern.level )のみをオーバーライドすることにより、MDCおよびその他のアドホックコンテンツをログ行に追加できます。例: logging.pattern.level=user:%X{user} %5pを使用する場合、デフォルトのログ形式には、次の例に示すように、「user」のMDCエントリが含まれます(存在する場合)。

2019-08-30 12:30:04.031 user:someone INFO 22174 --- [  nio-8080-exec-0] demo.Controller
Handling authenticated request

4.7. Logback拡張

Spring Bootには、高度な構成に役立つLogbackの拡張機能が多数含まれています。これらの拡張機能を logback-spring.xml 構成ファイルで使用できます。

標準の logback.xml 構成ファイルのロードが早すぎるため、拡張機能を使用できません。 logback-spring.xml を使用するか、logging.config プロパティを定義する必要があります。
拡張はLogbackの構成スキャンで(英語) は使用できません。設定しようとすると、構成ファイルに変更を加えると、次のいずれかのエラーがログに記録されます。
ERROR in [email protected](英語)  :71 - no applicable action for [springProperty], current ElementPath is [[configuration][springProperty]]
ERROR in [email protected](英語)  :71 - no applicable action for [springProfile], current ElementPath is [[configuration][springProfile]]

4.7.1. プロファイル固有の構成

<springProfile> タグを使用すると、アクティブなSpringプロファイルに基づいて、構成のセクションをオプションで含めたり除外したりできます。プロファイルセクションは、<configuration> 要素内のどこでもサポートされます。 name 属性を使用して、構成を受け入れるプロファイルを指定します。 <springProfile> タグには、単純なプロファイル名( stagingなど)またはプロファイル式を含めることができます。プロファイル式を使用すると、たとえば production & (eu-central | eu-west)など、より複雑なプロファイルロジックを表現できます。詳細については、リファレンスガイドを参照してください。次のリストは、3つのサンプルプロファイルを示しています。

<springProfile name="staging">
    <!-- configuration to be enabled when the "staging" profile is active -->
</springProfile>

<springProfile name="dev | staging">
    <!-- configuration to be enabled when the "dev" or "staging" profiles are active -->
</springProfile>

<springProfile name="!production">
    <!-- configuration to be enabled when the "production" profile is not active -->
</springProfile>

4.7.2. 環境プロパティ

<springProperty> タグを使用すると、Springから Environment のプロパティを公開して、Logback内で使用できます。これは、Logback構成の application.properties ファイルの値にアクセスする場合に役立ちます。このタグは、Logbackの標準 <property> タグと同様に機能します。ただし、直接 valueを指定するのではなく、プロパティの source を( Environmentから)指定します。 local スコープ以外の場所にプロパティを保存する必要がある場合は、scope 属性を使用できます。フォールバック値が必要な場合(プロパティが Environmentに設定されていない場合)、defaultValue 属性を使用できます。次の例は、Logback内で使用するプロパティを公開する方法を示しています。

<springProperty scope="context" name="fluentHost" source="myapp.fluentd.host"
        defaultValue="localhost"/>
<appender name="FLUENT" class="ch.qos.logback.more.appenders.DataFluentAppender">
    <remoteHost>${fluentHost}</remoteHost>
    ...
</appender>
source は、ケバブの場合( my.property-nameなど)で指定する必要があります。ただし、緩和されたルールを使用して、Environment にプロパティを追加できます。

5. 国際化対応

Spring Bootはローカライズされたメッセージをサポートしているため、アプリケーションは異なる言語設定のユーザーに対応できます。デフォルトでは、Spring Bootは、クラスパスのルートで messages リソースバンドルの存在を探します。

自動構成は、構成されたリソースバンドルのデフォルトプロパティファイルが利用可能な場合に適用されます(つまり、デフォルトで messages.properties )。リソースバンドルに言語固有のプロパティファイルのみが含まれている場合、デフォルトを追加する必要があります。設定されたベース名のいずれかに一致するプロパティファイルが見つからない場合、自動構成された MessageSourceはありません。

次の例に示すように、spring.messages 名前空間を使用して、リソースバンドルのベース名と他のいくつかの属性を構成できます。

spring.messages.basename=messages,config.i18n.messages
spring.messages.fallback-to-system-locale=false
spring.messages.basename は、パッケージ修飾子またはクラスパスルートから解決されたリソースのいずれかの場所のコンマ区切りリストをサポートします。

サポートされるオプションの詳細については、 MessageSourceProperties (GitHub) を参照してください。

6. JSON

Spring Bootは、3つのJSONマッピングライブラリとの統合を提供します。

  • Gson

  • Jackson

  • JSON-B

Jacksonは、推奨されるデフォルトのライブラリです。

6.1. Jackson

Jacksonの自動構成が提供され、Jacksonは spring-boot-starter-jsonの一部です。Jacksonがクラスパスにある場合、ObjectMapper Beanが自動的に構成されます。 ObjectMapperの構成をカスタマイズするために、いくつかの構成プロパティが提供されています。

6.2. Gson

Gsonの自動構成が提供されます。Gsonがクラスパスにある場合、Gson Beanが自動的に構成されます。構成をカスタマイズするために、いくつかの spring.gson.* 構成プロパティが提供されています。さらに制御するには、1つ以上の GsonBuilderCustomizer Beanを使用できます。

6.3. JSON-B

JSON-Bの自動構成が提供されます。JSON-B APIと実装がクラスパスにある場合、Jsonb Beanが自動的に構成されます。優先されるJSON-B実装は、依存関係管理が提供されるApache Johnzonです。

7. Webアプリケーションの開発

Spring Bootは、Webアプリケーション開発に適しています。組み込みTomcat、Jetty、Undertow、またはNettyを使用して、自己完結型のHTTPサーバーを作成できます。ほとんどのWebアプリケーションは spring-boot-starter-web モジュールを使用して、すぐに起動して実行します。 spring-boot-starter-webflux モジュールを使用して、リアクティブWebアプリケーションを構築することもできます。

Spring Boot Webアプリケーションをまだ開発していない場合は、「Hello World!」に従ってください。入門セクションの例。

7.1. 「Spring Web MVC フレームワーク」

Spring Web MVCフレームワーク(単に「Spring MVC」と呼ばれることも多い)は、豊富な「モデルビューコントローラー」Webフレームワークです。Spring MVCでは、特殊な @Controller または @RestController Beanを作成して、受信HTTPリクエストを処理できます。コントローラーのメソッドは、@RequestMapping アノテーションを使用してHTTPにマップされます。

次のコードは、JSONデータを提供する典型的な @RestController を示しています。

@RestController
@RequestMapping(value="/users")
public class MyRestController {

    @RequestMapping(value="/{user}", method=RequestMethod.GET)
    public User getUser(@PathVariable Long user) {
        // ...
    }

    @RequestMapping(value="/{user}/customers", method=RequestMethod.GET)
    List<Customer> getUserCustomers(@PathVariable Long user) {
        // ...
    }

    @RequestMapping(value="/{user}", method=RequestMethod.DELETE)
    public User deleteUser(@PathVariable Long user) {
        // ...
    }

}

Spring MVCはコアSpring Frameworkの一部であり、詳細情報はリファレンスドキュメントで入手できますspring.io/guidesで利用可能なSpring MVCをカバーするいくつかのガイドもあります。

7.1.1. Spring MVC自動構成

Spring Bootは、ほとんどのアプリケーションで適切に機能するSpring MVCの自動構成を提供します。

自動構成により、Springのデフォルトに加えて次の機能が追加されます。

これらのSpring Boot MVCのカスタマイズを保持し、さらにMVCのカスタマイズ(インターセプター、フォーマッター、View Controller、およびその他の機能)を作成する場合は、@EnableWebMvc なしでタイプ WebMvcConfigurer の独自の @Configuration クラスを追加できます。

RequestMappingHandlerMapping, RequestMappingHandlerAdapterまたは ExceptionHandlerExceptionResolverのカスタムインスタンスを提供し、Spring Boot MVCのカスタマイズを維持したい場合は、タイプ WebMvcRegistrations のBeanを宣言し、それを使用してそれらのコンポーネントのカスタムインスタンスを提供できます。

Spring MVCを完全に制御したい場合は、@EnableWebMvcでアノテーション付けされた独自の @Configuration を追加するか、@EnableWebMvcのJavadocに従って、独自の @Configurationアノテーション付き DelegatingWebMvcConfiguration を追加できます。

7.1.2. HttpMessageConverters

Spring MVCは、HttpMessageConverter インターフェースを使用してHTTPリクエストとレスポンスを変換します。すぐに使用できるデフォルトが含まれています。例:オブジェクトは自動的にJSON(Jacksonライブラリを使用)またはXML(Jackson XML拡張機能(使用可能な場合)を使用、またはJAXBを使用してJackson XML拡張機能を使用できない場合)に変換できます。デフォルトでは、文字列は UTF-8でエンコードされます。

コンバーターを追加またはカスタマイズする必要がある場合は、次のリストに示すように、Spring Bootの HttpMessageConverters クラスを使用できます。

import org.springframework.boot.autoconfigure.http.HttpMessageConverters;
import org.springframework.context.annotation.*;
import org.springframework.http.converter.*;

@Configuration(proxyBeanMethods = false)
public class MyConfiguration {

    @Bean
    public HttpMessageConverters customConverters() {
        HttpMessageConverter<?> additional = ...
        HttpMessageConverter<?> another = ...
        return new HttpMessageConverters(additional, another);
    }

}

コンテキストに存在する HttpMessageConverter Beanは、コンバーターのリストに追加されます。同じ方法でデフォルトのコンバーターをオーバーライドすることもできます。

7.1.3. カスタムJSONシリアライザーとデシリアライザー

Jacksonを使用してJSONデータをシリアライズおよびデシリアライズする場合、独自の JsonSerializer および JsonDeserializer クラスを作成することができます。カスタムシリアライザーは通常、モジュールを介してJacksonに登録されます(GitHub) が、Spring BootはSpring Beanを直接登録しやすくする代替 @JsonComponent アノテーションを提供します。

JsonSerializer, JsonDeserializer または KeyDeserializer 実装で @JsonComponent アノテーションを直接使用できます。次の例に示すように、内部クラスとしてシリアライザー/デシリアライザーを含むクラスでも使用できます。

import java.io.*;
import com.fasterxml.jackson.core.*;
import com.fasterxml.jackson.databind.*;
import org.springframework.boot.jackson.*;

@JsonComponent
public class Example {

    public static class Serializer extends JsonSerializer<SomeObject> {
        // ...
    }

    public static class Deserializer extends JsonDeserializer<SomeObject> {
        // ...
    }

}

ApplicationContext 内のすべての @JsonComponent Beanは、Jacksonに自動的に登録されます。 @JsonComponent@Componentでメタアノテーションが付けられているため、通常のコンポーネントスキャン規則が適用されます。

Spring Bootは、オブジェクトを直列化するときに標準Jacksonバージョンの有用な代替を提供する JsonObjectSerializer (GitHub) および JsonObjectDeserializer (GitHub) 基本クラスも提供します。詳細については、Javadocの JsonObjectSerializer (Javadoc) および JsonObjectDeserializer (Javadoc) を参照してください。

7.1.4. MessageCodesResolver

Spring MVCには、バインディングエラーからエラーメッセージをレンダリングするためのエラーコードを生成するための戦略 MessageCodesResolverがあります。 spring.mvc.message-codes-resolver-format プロパティ PREFIX_ERROR_CODE または POSTFIX_ERROR_CODEを設定すると、Spring Bootが自動的に作成します( DefaultMessageCodesResolver.Format (Javadoc) の列挙を参照)。

7.1.5. 静的コンテンツ

デフォルトでは、Spring Bootは、クラスパス内の /static (または /public または /resources または /META-INF/resources)と呼ばれるディレクトリまたは ServletContextのルートから静的コンテンツを提供します。Spring MVCの ResourceHttpRequestHandler を使用するため、独自の WebMvcConfigurer を追加して addResourceHandlers メソッドをオーバーライドすることにより、その動作を変更できます。

スタンドアロンWebアプリケーションでは、コンテナーからのデフォルトサーブレットも有効になり、フォールバックとして機能し、Springが処理しないことを決定した場合、ServletContext のルートからコンテンツを提供します。Springは常に DispatcherServletを介して要求を処理できるため、ほとんどの場合、これは起こりません(デフォルトのMVC構成を変更しない限り)。

デフォルトでは、リソースは /**にマップされますが、spring.mvc.static-path-pattern プロパティでそれを調整できます。たとえば、すべてのリソースを /resources/** に再配置するには、次のようにします。

spring.mvc.static-path-pattern=/resources/**

spring.resources.static-locations プロパティを使用して、静的リソースの場所をカスタマイズすることもできます(デフォルト値をディレクトリの場所のリストに置き換えます)。ルートサーブレットコンテキストパス "/"もロケーションとして自動的に追加されます。

前述の「標準」の静的リソースの場所に加えて、Webjarsコンテンツ(英語) には特別なケースが作成されます。WebZZ形式でパッケージ化されている場合、/webjars/** にパスを持つリソースはjarファイルから提供されます。

アプリケーションがjarとしてパッケージ化されている場合は、src/main/webapp ディレクトリを使用しないでください。このディレクトリは一般的な標準ですが、warパッケージでのみ機能し、jarを生成する場合、ほとんどのビルドツールでは暗黙のうちに無視されます。

Spring Bootは、Spring MVCが提供する高度なリソース処理機能もサポートしているため、静的リソースのキャッシュ無効化やWebjarのバージョンに依存しないURLの使用などのユースケースが可能です。

Webjarにバージョンに依存しないURLを使用するには、webjars-locator-core 依存関係を追加します。次に、Webjarを宣言します。例としてjQueryを使用して、"/webjars/jquery/jquery.min.js" を追加すると、"/webjars/jquery/x.y.z/jquery.min.js" が生成されます( x.y.z はWebjarバージョンです)。

JBossを使用する場合、webjars-locator-coreではなく webjars-locator-jboss-vfs 依存関係を宣言する必要があります。それ以外の場合、すべてのWebjarは 404として解決されます。

キャッシュ無効化を使用するには、次の構成ですべての静的リソースのキャッシュ無効化ソリューションを構成し、URLに <link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>などのコンテンツハッシュを効果的に追加します。

spring.resources.chain.strategy.content.enabled=true
spring.resources.chain.strategy.content.paths=/**
リソースへのリンクは、ThymeleafおよびFreeMarker用に自動構成された ResourceUrlEncodingFilter のおかげで、実行時にテンプレートで書き換えられます。JSPを使用する場合は、このフィルターを手動で宣言する必要があります。現在、他のテンプレートエンジンは自動的にサポートされていませんが、カスタムテンプレートマクロ/ヘルパーおよび ResourceUrlProvider (Javadoc) を使用することができます。

JavaScriptモジュールローダーなどを使用してリソースを動的にロードする場合、ファイルの名前を変更することはできません。そのため、他の戦略もサポートされており、組み合わせることができます。"fixed" 戦略では、次の例に示すように、ファイル名を変更せずにURLに静的バージョン文字列を追加します。

spring.resources.chain.strategy.content.enabled=true
spring.resources.chain.strategy.content.paths=/**
spring.resources.chain.strategy.fixed.enabled=true
spring.resources.chain.strategy.fixed.paths=/js/lib/
spring.resources.chain.strategy.fixed.version=v12

この構成では、"/js/lib/" にあるJavaScriptモジュールは固定バージョン管理戦略("/v12/js/lib/mymodule.js")を使用しますが、他のリソースはコンテンツコンテンツ(<link href="/css/spring-2a2d595e6ed9a0b24f027f2b63b134d6.css"/>)を引き続き使用します。

サポートされるオプションの詳細については、 ResourceProperties (GitHub) を参照してください。

この機能は、専用のブログ投稿(英語) およびSpring Frameworkのリファレンスドキュメントで詳細に説明されています。

7.1.6. ウェルカムページ

Spring Bootは、静的なウェルカムページとテンプレート化されたウェルカムページの両方をサポートしています。最初に、構成された静的コンテンツの場所で index.html ファイルを探します。見つからない場合は、index テンプレートを探します。どちらかが見つかった場合、アプリケーションのウェルカムページとして自動的に使用されます。

7.1.7. カスタムファビコン

他の静的リソースと同様に、Spring Bootは構成された静的コンテンツの場所で favicon.ico を探します。そのようなファイルが存在する場合、アプリケーションのファビコンとして自動的に使用されます。

7.1.8. パスマッチングとコンテンツネゴシエーション

Spring MVCは、リクエストパスを確認し、それをアプリケーションで定義されたマッピング(たとえば、コントローラーメソッドの @GetMapping アノテーション)と照合することにより、受信HTTPリクエストをハンドラーにマッピングできます。

Spring Bootは、デフォルトでサフィックスパターンマッチングを無効にすることを選択します。つまり、"GET /projects/spring-boot.json" のようなリクエストは @GetMapping("/projects/spring-boot") マッピングに一致しません。これは、Spring MVCアプリケーションのベストプラクティスと見なされます。この機能は、適切な「Accept」リクエストヘッダーを送信しなかったHTTPクライアントにとって、これまで主に役立ちました。正しいコンテンツタイプをクライアントに送信する必要がありました。最近では、コンテンツネゴシエーションの信頼性がはるかに高くなっています。

常に適切な「Accept」リクエストヘッダーを送信しないHTTPクライアントに対処する他の方法があります。サフィックスマッチングを使用する代わりに、クエリパラメータを使用して、"GET /projects/spring-boot?format=json" などのリクエストが @GetMapping("/projects/spring-boot")にマッピングされるようにすることができます。

spring.mvc.contentnegotiation.favor-parameter=true

# We can change the parameter name, which is "format" by default:
# spring.mvc.contentnegotiation.parameter-name=myparam

# We can also register additional file extensions/media types with:
spring.mvc.contentnegotiation.media-types.markdown=text/markdown

警告を理解しても、アプリケーションでサフィックスパターンマッチングを使用する場合は、次の構成が必要です。

spring.mvc.contentnegotiation.favor-path-extension=true
spring.mvc.pathmatch.use-suffix-pattern=true

または、すべての接尾辞パターンを開くのではなく、登録された接尾辞パターンをサポートする方が安全です。

spring.mvc.contentnegotiation.favor-path-extension=true
spring.mvc.pathmatch.use-registered-suffix-pattern=true

# You can also register additional file extensions/media types with:
# spring.mvc.contentnegotiation.media-types.adoc=text/asciidoc

7.1.9. ConfigurableWebBindingInitializer

Spring MVCは WebBindingInitializer を使用して、特定の要求に対して WebDataBinder を初期化します。独自の ConfigurableWebBindingInitializer @Beanを作成する場合、Spring Bootはそれを使用するようにSpring MVCを自動的に構成します。

7.1.10. テンプレートエンジン

REST Webサービスだけでなく、Spring MVCを使用して動的なHTMLコンテンツを提供することもできます。Spring MVCは、Thymeleaf、FreeMarker、JSPなど、さまざまなテンプレートテクノロジーをサポートしています。また、他の多くのテンプレートエンジンには、独自のSpring MVC統合が含まれています。

Spring Bootには、次のテンプレートエンジンの自動構成サポートが含まれています。

可能であれば、JSPを避ける必要があります。組み込みサーブレットコンテナーで使用する場合、いくつかの既知の制限があります。

これらのテンプレートエンジンのいずれかを既定の構成で使用すると、src/main/resources/templatesからテンプレートが自動的に選択されます。

アプリケーションの実行メソッドに応じて、IntelliJ IDEAはクラスパスの順序を変えます。IDEでメインメソッドからアプリケーションを実行すると、MavenまたはGradleを使用して、またはパッケージ化されたjarからアプリケーションを実行する場合とは順序が異なります。これにより、Spring Bootがクラスパスでテンプレートを見つけられない場合があります。この問題がある場合は、IDEでクラスパスを並べ替えて、モジュールのクラスとリソースを最初に配置できます。または、次のように、クラスパス上のすべての templates ディレクトリを検索するようにテンプレートプレフィックスを設定できます: classpath*:/templates/

7.1.11. エラー処理

デフォルトでは、Spring Bootは、すべてのエラーを適切な方法で処理する /error マッピングを提供し、サーブレットコンテナーに「グローバル」エラーページとして登録されます。マシンクライアントの場合、エラー、HTTPステータス、および例外メッセージの詳細を含むJSON応答を生成します。ブラウザクライアントには、同じデータをHTML形式でレンダリングする「ホワイトラベル」エラービューがあります(カスタマイズするには、errorに解決される View を追加します)。デフォルトの動作を完全に置き換えるには、ErrorController を実装してそのタイプのBean定義を登録するか、タイプ ErrorAttributes のBeanを追加して既存のメカニズムを使用し、内容を置き換えます。

BasicErrorController は、カスタム ErrorControllerの基本クラスとして使用できます。これは、新しいコンテンツタイプのハンドラーを追加する場合に特に便利です(デフォルトでは、text/html を具体的に処理し、他のすべてにフォールバックを提供します)。これを行うには、BasicErrorControllerを継承し、produces 属性を持つ @RequestMapping を使用してpublicメソッドを追加し、新しいタイプのBeanを作成します。

次の例に示すように、@ControllerAdvice アノテーションが付けられたクラスを定義して、特定のコントローラーまたは例外タイプ、あるいはその両方を返すようにJSONドキュメントをカスタマイズすることもできます。

@ControllerAdvice(basePackageClasses = AcmeController.class)
public class AcmeControllerAdvice extends ResponseEntityExceptionHandler {

    @ExceptionHandler(YourException.class)
    @ResponseBody
    ResponseEntity<?> handleControllerException(HttpServletRequest request, Throwable ex) {
        HttpStatus status = getStatus(request);
        return new ResponseEntity<>(new CustomErrorType(status.value(), ex.getMessage()), status);
    }

    private HttpStatus getStatus(HttpServletRequest request) {
        Integer statusCode = (Integer) request.getAttribute("javax.servlet.error.status_code");
        if (statusCode == null) {
            return HttpStatus.INTERNAL_SERVER_ERROR;
        }
        return HttpStatus.valueOf(statusCode);
    }

}

上記の例では、YourExceptionAcmeControllerと同じパッケージで定義されたコントローラーによってスローされた場合、ErrorAttributes 表現の代わりに CustomErrorType POJOのJSON表現が使用されます。

カスタムエラーページ

特定のステータスコードのカスタムHTMLエラーページを表示する場合は、/error フォルダーにファイルを追加できます。エラーページは、静的HTML(つまり、任意の静的リソースフォルダーに追加)にすることも、テンプレートを使用して構築することもできます。ファイルの名前は、正確なステータスコードまたはシリーズマスクである必要があります。

例: 404 を静的HTMLファイルにマップするには、フォルダー構造は次のようになります。

src/
 +- main/
     +- java/
     |   + <source code>
     +- resources/
         +- public/
             +- error/
             |   +- 404.html
             +- <other public assets>

FreeMarkerテンプレートを使用してすべての 5xx エラーをマップするには、フォルダー構造は次のようになります。

src/
 +- main/
     +- java/
     |   + <source code>
     +- resources/
         +- templates/
             +- error/
             |   +- 5xx.ftlh
             +- <other templates>

より複雑なマッピングの場合、次の例に示すように、ErrorViewResolver インターフェースを実装するBeanを追加することもできます。

public class MyErrorViewResolver implements ErrorViewResolver {

    @Override
    public ModelAndView resolveErrorView(HttpServletRequest request,
            HttpStatus status, Map<String, Object> model) {
        // Use the request or status to optionally return a ModelAndView
        return ...
    }

}

@ExceptionHandler メソッド @ControllerAdvice などの通常のSpring MVC機能も使用できます。 ErrorController は、未処理の例外をピックアップします。

Spring MVC外のエラーページのマッピング

Spring MVCを使用しないアプリケーションの場合、ErrorPageRegistrar インターフェースを使用して ErrorPagesを直接登録できます。この抽象化は、基礎となる埋め込みサーブレットコンテナーと直接機能し、Spring MVC DispatcherServletがなくても機能します。

@Bean
public ErrorPageRegistrar errorPageRegistrar(){
    return new MyErrorPageRegistrar();
}

// ...

private static class MyErrorPageRegistrar implements ErrorPageRegistrar {

    @Override
    public void registerErrorPages(ErrorPageRegistry registry) {
        registry.addErrorPages(new ErrorPage(HttpStatus.BAD_REQUEST, "/400"));
    }

}
Filter によって処理されるパスで ErrorPage を登録する場合(JerseyやWicketなどの一部の非SpringWebフレームワークで一般的)、次に示すように、FilterERROR ディスパッチャーとして明示的に登録する必要があります。次の例:
@Bean
public FilterRegistrationBean myFilter() {
    FilterRegistrationBean registration = new FilterRegistrationBean();
    registration.setFilter(new MyFilter());
    ...
    registration.setDispatcherTypes(EnumSet.allOf(DispatcherType.class));
    return registration;
}

デフォルトの FilterRegistrationBean には ERROR ディスパッチャータイプが含まれていないことに注意してください。

注意:サーブレットコンテナーにデプロイされると、Spring Bootはエラーページフィルタを使用して、エラーステータスのリクエストを適切なエラーページに転送します。リクエストが正しいエラーページに転送されるのは、レスポンスがまだコミットされていない場合のみです。デフォルトでは、WebSphere Application Server 8.0以降は、サーブレットのサービスメソッドが正常に完了すると応答をコミットします。 com.ibm.ws.webcontainer.invokeFlushAfterServicefalseに設定して、この動作を無効にする必要があります。

7.1.12. Spring HATEOAS

ハイパーメディアを利用するRESTful APIを開発する場合、Spring Bootは、ほとんどのアプリケーションで適切に動作するSpring HATEOASの自動構成を提供します。自動構成により、@EnableHypermediaSupport を使用する必要がなくなり、多数のBeanが登録されて、ハイパーメディアベースのアプリケーションの構築が容易になります。LinkDiscoverers (クライアント側サポート用)および応答を目的の表現に正しくマーシャリングするように構成された ObjectMapper が含まれます。 ObjectMapper は、さまざまな spring.jackson.* プロパティを設定するか、存在する場合は Jackson2ObjectMapperBuilder Beanによってカスタマイズされます。

@EnableHypermediaSupportを使用して、Spring HATEOASの構成を制御できます。これを行うと、前述の ObjectMapper カスタマイズが無効になることに注意してください。

7.1.13. CORSサポート

クロスオリジンリソース共有(英語) (CORS)は、ほとんどのブラウザ(英語) で実装されているW3C仕様(英語) であり、IFRAMEやJSONPなどの安全性が低く強力なアプローチを使用する代わりに、どのようなクロスドメインリクエストを認可するかを柔軟に指定できます。

バージョン4.2の時点で、Spring MVC はCORSをサポートしています。Spring Bootアプリケーションで @CrossOrigin (Javadoc) アノテーションを使用したコントローラーメソッドCORS構成を使用する場合、特定の構成は必要ありません。グローバルCORS設定は、次の例に示すように、カスタマイズされた addCorsMappings(CorsRegistry) メソッドで WebMvcConfigurer Beanを登録することにより定義できます。

@Configuration(proxyBeanMethods = false)
public class MyConfiguration {

    @Bean
    public WebMvcConfigurer corsConfigurer() {
        return new WebMvcConfigurer() {
            @Override
            public void addCorsMappings(CorsRegistry registry) {
                registry.addMapping("/api/**");
            }
        };
    }
}

7.2. 「Spring WebFlux フレームワーク」

Spring WebFluxは、Spring Framework 5.0で導入された新しいリアクティブWebフレームワークです。Spring MVCとは異なり、サーブレットAPIを必要とせず、完全に非同期でノンブロッキングであり、Reactorプロジェクト(英語) を通じてリアクティブストリーム(英語) 仕様を実装します。

Spring WebFluxには、機能ベースとアノテーションベースの2つのフレーバーがあります。次の例に示すように、アノテーションベースのモデルはSpring MVCモデルに非常に近いものです。

@RestController
@RequestMapping("/users")
public class MyRestController {

    @GetMapping("/{user}")
    public Mono<User> getUser(@PathVariable Long user) {
        // ...
    }

    @GetMapping("/{user}/customers")
    public Flux<Customer> getUserCustomers(@PathVariable Long user) {
        // ...
    }

    @DeleteMapping("/{user}")
    public Mono<User> deleteUser(@PathVariable Long user) {
        // ...
    }

}

次の例に示すように、機能バリアントである「WebFlux.fn」は、ルーティング構成を要求の実際の処理から分離します。

@Configuration(proxyBeanMethods = false)
public class RoutingConfiguration {

    @Bean
    public RouterFunction<ServerResponse> monoRouterFunction(UserHandler userHandler) {
        return route(GET("/{user}").and(accept(APPLICATION_JSON)), userHandler::getUser)
                .andRoute(GET("/{user}/customers").and(accept(APPLICATION_JSON)), userHandler::getUserCustomers)
                .andRoute(DELETE("/{user}").and(accept(APPLICATION_JSON)), userHandler::deleteUser);
    }

}

@Component
public class UserHandler {

    public Mono<ServerResponse> getUser(ServerRequest request) {
        // ...
    }

    public Mono<ServerResponse> getUserCustomers(ServerRequest request) {
        // ...
    }

    public Mono<ServerResponse> deleteUser(ServerRequest request) {
        // ...
    }
}

WebFluxはSpring Frameworkの一部であり、詳細な情報はリファレンスドキュメントで入手できます

RouterFunction Beanをいくつでも定義して、ルーターの定義をモジュール化できます。優先順位を適用する必要がある場合は、Beanをオーダーできます。

開始するには、spring-boot-starter-webflux モジュールをアプリケーションに追加します。

spring-boot-starter-web モジュールと spring-boot-starter-webflux モジュールの両方をアプリケーションに追加すると、WebFluxではなく、Spring BootがSpring MVCを自動構成します。多くのSpring開発者が spring-boot-starter-webflux をSpring MVCアプリケーションに追加してリアクティブ WebClientを使用するため、この動作が選択されています。選択したアプリケーションタイプを SpringApplication.setWebApplicationType(WebApplicationType.REACTIVE)に設定することにより、引き続き選択を強制できます。

7.2.1. Spring WebFlux自動構成

Spring Bootは、ほとんどのアプリケーションで適切に機能するSpring WebFluxの自動構成を提供します。

自動構成により、Springのデフォルトに加えて次の機能が追加されます。

  • HttpMessageReader および HttpMessageWriter インスタンスのコーデックの構成( このドキュメントで後述)。

  • WebJarsのサポートを含む、静的リソースの提供のサポート( このドキュメントで後述)。

Spring Boot WebFlux機能を保持し、さらにWebFluxの構成を追加する場合、@EnableWebFlux なしでタイプ WebFluxConfigurer の独自の @Configuration クラスを追加できます。

Spring WebFluxを完全に制御したい場合は、@EnableWebFluxアノテーションが付けられた独自の @Configuration を追加できます。

7.2.2. HttpMessageReadersおよびHttpMessageWritersを使用したHTTPコーデック

Spring WebFluxは、HttpMessageReader および HttpMessageWriter インターフェースを使用して、HTTPリクエストおよび応答を変換します。これらは、クラスパスで使用可能なライブラリを調べることにより、実用的なデフォルトを持つように CodecConfigurer で構成されます。

Spring Bootは、コーデックの専用構成プロパティ spring.codec.*を提供します。また、CodecCustomizer インスタンスを使用して、さらにカスタマイズを適用します。例: spring.jackson.* 設定キーはJacksonコーデックに適用されます。

コーデックを追加またはカスタマイズする必要がある場合は、次の例に示すように、カスタム CodecCustomizer コンポーネントを作成できます。

import org.springframework.boot.web.codec.CodecCustomizer;

@Configuration(proxyBeanMethods = false)
public class MyConfiguration {

    @Bean
    public CodecCustomizer myCodecCustomizer() {
        return codecConfigurer -> {
            // ...
        };
    }

}

7.2.3. 静的コンテンツ

デフォルトでは、Spring Bootは、クラスパス内の /static (または /public または /resources または /META-INF/resources)と呼ばれるディレクトリから静的コンテンツを提供します。Spring WebFluxの ResourceWebHandler を使用するため、独自の WebFluxConfigurer を追加して addResourceHandlers メソッドをオーバーライドすることにより、その動作を変更できます。

デフォルトでは、リソースは /**にマップされますが、spring.webflux.static-path-pattern プロパティを設定することでそれを調整できます。たとえば、すべてのリソースを /resources/** に再配置するには、次のようにします。

spring.webflux.static-path-pattern=/resources/**

spring.resources.static-locationsを使用して、静的リソースの場所をカスタマイズすることもできます。これにより、デフォルト値がディレクトリの場所のリストに置き換えられます。そうすると、デフォルトのウェルカムページ検出がカスタムの場所に切り替わります。起動時にいずれかの場所に index.html がある場合、アプリケーションのホームページです。

前述の「標準」の静的リソースの場所に加えて、Webjarsコンテンツ(英語) には特別なケースが作成されます。WebZZ形式でパッケージ化されている場合、/webjars/** にパスを持つリソースはjarファイルから提供されます。

Spring WebFluxアプリケーションは厳密にはサーブレットAPIに依存しないため、warファイルとしてデプロイすることはできず、src/main/webapp ディレクトリを使用しません。

7.2.4. テンプレートエンジン

REST Webサービスだけでなく、Spring WebFluxを使用して動的HTMLコンテンツを提供することもできます。Spring WebFluxは、Thymeleaf、FreeMarker、Mustacheなど、さまざまなテンプレートテクノロジーをサポートしています。

Spring Bootには、次のテンプレートエンジンの自動構成サポートが含まれています。

これらのテンプレートエンジンのいずれかを既定の構成で使用すると、src/main/resources/templatesからテンプレートが自動的に選択されます。

7.2.5. エラー処理

Spring Bootは、すべてのエラーを適切な方法で処理する WebExceptionHandler を提供します。処理順序でのその位置は、WebFluxによって提供されるハンドラーの直前であり、最後に考慮されます。マシンクライアントの場合、エラー、HTTPステータス、および例外メッセージの詳細を含むJSON応答を生成します。ブラウザクライアントには、同じデータをHTML形式でレンダリングする「ホワイトラベル」エラーハンドラがあります。また、独自のHTMLテンプレートを提供してエラーを表示することもできます( 次のセクションを参照 )。

この機能をカスタマイズするための最初のステップは、多くの場合、既存のメカニズムを使用しますが、エラーの内容を置換または拡張することを伴います。そのために、タイプ ErrorAttributesのBeanを追加できます。

エラー処理の動作を変更するには、ErrorWebExceptionHandler を実装し、そのタイプのBean定義を登録できます。 WebExceptionHandler は非常に低レベルであるため、Spring Bootは次の例に示すように、WebFluxの機能的な方法でエラーを処理できる便利な AbstractErrorWebExceptionHandler も提供します。

public class CustomErrorWebExceptionHandler extends AbstractErrorWebExceptionHandler {

    // Define constructor here

    @Override
    protected RouterFunction<ServerResponse> getRoutingFunction(ErrorAttributes errorAttributes) {

        return RouterFunctions
                .route(aPredicate, aHandler)
                .andRoute(anotherPredicate, anotherHandler);
    }

}

より完全な図を得るには、DefaultErrorWebExceptionHandler を直接サブクラス化し、特定のメソッドをオーバーライドすることもできます。

カスタムエラーページ

特定のステータスコードのカスタムHTMLエラーページを表示する場合は、/error フォルダーにファイルを追加できます。エラーページは、静的HTML(つまり、任意の静的リソースフォルダーに追加)またはテンプレートを使用して作成できます。ファイルの名前は、正確なステータスコードまたはシリーズマスクである必要があります。

例: 404 を静的HTMLファイルにマップするには、フォルダー構造は次のようになります。

src/
 +- main/
     +- java/
     |   + <source code>
     +- resources/
         +- public/
             +- error/
             |   +- 404.html
             +- <other public assets>

Mustacheテンプレートを使用してすべての 5xx エラーをマップするには、フォルダー構造は次のようになります。

src/
 +- main/
     +- java/
     |   + <source code>
     +- resources/
         +- templates/
             +- error/
             |   +- 5xx.mustache
             +- <other templates>

7.2.6. Webフィルター

Spring WebFluxは、HTTPリクエスト/応答交換をフィルタリングするために実装できる WebFilter インターフェースを提供します。アプリケーションコンテキストで見つかった WebFilter Beanは、各交換のフィルタリングに自動的に使用されます。

フィルターの順序が重要な場合、Ordered を実装するか、@Orderでアノテーションを付けることができます。Spring Bootの自動構成により、Webフィルターが構成される場合があります。その場合、次の表に示す順序が使用されます。

Webフィルター順序

MetricsWebFilter

Ordered.HIGHEST_PRECEDENCE + 1

WebFilterChainProxy (Spring Security)

-100

HttpTraceWebFilter

Ordered.LOWEST_PRECEDENCE - 10

7.3. JAX-RSおよびJersey

RESTエンドポイントにJAX-RSプログラミングモデルを使用する場合は、Spring MVCの代わりに利用可能な実装のいずれかを使用できます。Jersey(英語) Apache CXF(英語) はすぐに使用できます。CXFでは、Servlet または Filter をアプリケーションコンテキストで @Bean として登録する必要があります。JerseyはネイティブSpringをサポートしているため、Spring Bootでの自動構成サポートとスターターも提供しています。

Jerseyを開始するには、spring-boot-starter-jersey を依存関係として含めてから、次の例に示すように、すべてのエンドポイントを登録するタイプ ResourceConfig@Bean が1つ必要です。

@Component
public class JerseyConfig extends ResourceConfig {

    public JerseyConfig() {
        register(Endpoint.class);
    }

}
Jerseyの実行可能アーカイブのスキャンのサポートはかなり制限されています。例: 実行可能なwarファイルを実行している場合、完全に実行可能なjarファイルまたは WEB-INF/classes で見つかったパッケージ内のエンドポイントをスキャンできません。この制限を回避するには、packages メソッドを使用せず、前の例に示すように、register メソッドを使用してエンドポイントを個別に登録する必要があります。

より高度なカスタマイズのために、ResourceConfigCustomizerを実装するBeanを任意の数だけ登録することもできます。

登録されたすべてのエンドポイントは、次の例に示すように、HTTPリソースアノテーション(@GET など)を含む @Components である必要があります。

@Component
@Path("/hello")
public class Endpoint {

    @GET
    public String message() {
        return "Hello";
    }

}

Endpoint はSpring @Componentであるため、そのライフサイクルはSpringによって管理され、@Autowired アノテーションを使用して依存関係を注入し、@Value アノテーションを使用して外部構成を注入できます。デフォルトでは、Jerseyサーブレットが登録され、/*にマップされます。 @ApplicationPathResourceConfigに追加することにより、マッピングを変更できます。

デフォルトでは、Jerseyは、jerseyServletRegistrationという名前のタイプ ServletRegistrationBean@Bean のサーブレットとしてセットアップされます。デフォルトでは、サーブレットは遅延的に初期化されますが、spring.jersey.servlet.load-on-startupを設定することでその動作をカスタマイズできます。同じ名前の独自のものを作成することにより、そのBeanを無効化またはオーバーライドできます。 spring.jersey.type=filter を設定することにより、サーブレットの代わりにフィルターを使用することもできます(この場合、置換またはオーバーライドする @BeanjerseyFilterRegistrationです)。フィルターには @Orderがあり、spring.jersey.filter.orderで設定できます。 spring.jersey.init.* を使用してプロパティのマップを指定することにより、サーブレットとフィルターの両方の登録に初期化パラメーターを指定できます。

7.4. 組み込みサーブレットコンテナーのサポート

Spring Bootには、組み込みTomcat(Apache) Jetty(英語) 、およびUndertow(GitHub) サーバーのサポートが含まれています。ほとんどの開発者は、適切な「スターター」を使用して、完全に構成されたインスタンスを取得します。デフォルトでは、組み込みサーバーはポート 8080でHTTPリクエストをリッスンします。

7.4.1. サーブレット、フィルター、およびリスナー

組み込みサーブレットコンテナーを使用する場合、Spring Beanを使用するか、サーブレットコンポーネントをスキャンすることにより、サーブレット仕様からサーブレット、フィルタ、およびすべてのリスナー( HttpSessionListenerなど)を登録できます。

サーブレット、フィルター、およびリスナーをSpring Beanとして登録する

Spring Beanである Servlet, Filterまたはサーブレット *Listener インスタンスは、組み込みコンテナーに登録されます。これは、構成中に application.properties の値を参照する場合に特に便利です。

デフォルトでは、コンテキストに含まれるサーブレットが1つのみの場合、/にマッピングされます。複数のサーブレットBeanの場合、Bean名がパスプレフィックスとして使用されます。フィルターは /*にマップします。

規則ベースのマッピングの柔軟性が不十分な場合は、ServletRegistrationBean, FilterRegistrationBeanおよび ServletListenerRegistrationBean クラスを使用して完全に制御できます。

通常、フィルターBeanを順序付けしないでおくと安全です。特定の順序が必要な場合は、Filter@Order でアノテーションを付けるか、Orderedを実装する必要があります。 @OrderでBeanメソッドにアノテーションを付けることにより、Filter の順序を構成することはできません。 Filter クラスを変更して @Order を追加したり、Orderedを実装したりできない場合は、FilterFilterRegistrationBean を定義し、setOrder(int) メソッドを使用して登録Beanの順序を設定する必要があります。 Ordered.HIGHEST_PRECEDENCEで要求本文を読み取るフィルターの構成は避けてください。アプリケーションの文字エンコード構成に反する可能性があるためです。サーブレットフィルターが要求をラップする場合、OrderedFilter.REQUEST_WRAPPER_FILTER_MAX_ORDER以下の順序で構成する必要があります。

アプリケーション内のすべての Filter の順序を確認するには、web ロギンググループlogging.level.web=debug)のデバッグレベルロギングを有効にします。登録されたフィルターの詳細(順序やURLパターンなど)は、起動時にログに記録されます。
Filter Beanはアプリケーションライフスタイルの非常に早い段階で初期化されるため、登録する際には注意してください。他のBeanと対話する Filter を登録する必要がある場合は、代わりに DelegatingFilterProxyRegistrationBean (Javadoc) の使用を検討してください。

7.4.2. サーブレットコンテキストの初期化

埋め込みサーブレットコンテナーは、サーブレット3.0+ javax.servlet.ServletContainerInitializer インターフェースまたはSpringの org.springframework.web.WebApplicationInitializer インターフェースを直接実行しません。これは、war内で実行するように設計されたサードパーティライブラリがSpring Bootアプリケーションを破損するリスクを減らすことを目的とした意図的な設計上の決定です。

Spring Bootアプリケーションでサーブレットコンテキストの初期化を実行する必要がある場合は、org.springframework.boot.web.servlet.ServletContextInitializer インターフェースを実装するBeanを登録する必要があります。単一の onStartup メソッドは ServletContext へのアクセスを提供し、必要に応じて、既存の WebApplicationInitializerへのアダプターとして簡単に使用できます。

サーブレット、フィルター、およびリスナーのスキャン

埋め込みコンテナーを使用する場合、@ServletComponentScanを使用して、@WebServlet, @WebFilterおよび @WebListener アノテーションが付けられたクラスの自動登録を有効にできます。

@ServletComponentScan は、コンテナーの組み込み検出メカニズムが代わりに使用されるスタンドアロンコンテナーでは効果がありません。

7.4.3. ServletWebServerApplicationContext

内部では、Spring Bootは、組み込みサーブレットコンテナーのサポートに異なるタイプの ApplicationContext を使用します。 ServletWebServerApplicationContext は、単一の ServletWebServerFactory Beanを検索することによって自身をブートストラップする特別なタイプの WebApplicationContext です。通常、TomcatServletWebServerFactory, JettyServletWebServerFactoryまたは UndertowServletWebServerFactory は自動構成されています。

通常、これらの実装クラスを意識する必要はありません。ほとんどのアプリケーションは自動構成され、適切な ApplicationContext および ServletWebServerFactory がユーザーに代わって作成されます。

7.4.4. 埋め込みサーブレットコンテナーのカスタマイズ

Spring Environment プロパティを使用して、一般的なサーブレットコンテナー設定を構成できます。通常、application.properties ファイルでプロパティを定義します。

一般的なサーバー設定は次のとおりです。

  • ネットワーク設定:受信HTTPリクエストのリッスンポート(server.port)、server.addressにバインドするインターフェースアドレスなど。

  • セッション設定:セッションが永続的か(server.servlet.session.persistent)、セッションタイムアウト(server.servlet.session.timeout)、セッションデータの場所(server.servlet.session.store-dir)、およびセッションCookie構成(server.servlet.session.cookie.*)。

  • エラー管理:エラーページの場所(server.error.path)など。

  • SSL

  • HTTP圧縮

Spring Bootは、可能な限り共通の設定を公開しようとしますが、常に可能とは限りません。これらの場合、専用の名前空間はサーバー固有のカスタマイズを提供します( server.tomcat および server.undertowを参照)。たとえば、アクセスログは、組み込みサーブレットコンテナーの特定の機能を使用して設定できます。

完全なリストについては、 ServerProperties (GitHub) クラスを参照してください。
プログラムによるカスタマイズ

組み込みサーブレットコンテナーをプログラムで設定する必要がある場合は、WebServerFactoryCustomizer インターフェースを実装するSpring Beanを登録できます。 WebServerFactoryCustomizer は、多数のカスタマイズsetterメソッドを含む ConfigurableServletWebServerFactoryへのアクセスを提供します。次の例は、プログラムでポートを設定する方法を示しています。

import org.springframework.boot.web.server.WebServerFactoryCustomizer;
import org.springframework.boot.web.servlet.server.ConfigurableServletWebServerFactory;
import org.springframework.stereotype.Component;

@Component
public class CustomizationBean implements WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> {

    @Override
    public void customize(ConfigurableServletWebServerFactory server) {
        server.setPort(9000);
    }

}
TomcatServletWebServerFactory, JettyServletWebServerFactoryUndertowServletWebServerFactory は、それぞれTomcat、Jetty、Undertow用の追加のカスタマイズsetterメソッドを持つ ConfigurableServletWebServerFactory の専用バリアントです。
ConfigurableServletWebServerFactoryを直接カスタマイズする

前述のカスタマイズ手法があまりにも制限されている場合は、TomcatServletWebServerFactory, JettyServletWebServerFactoryまたは UndertowServletWebServerFactory Beanを自分で登録できます。

@Bean
public ConfigurableServletWebServerFactory webServerFactory() {
    TomcatServletWebServerFactory factory = new TomcatServletWebServerFactory();
    factory.setPort(9000);
    factory.setSessionTimeout(10, TimeUnit.MINUTES);
    factory.addErrorPages(new ErrorPage(HttpStatus.NOT_FOUND, "/notfound.html"));
    return factory;
}

Setterは、多くの構成オプション用に提供されています。よりエキゾチックな何かをする必要がある場合、いくつかのprotectedメソッド「フック」も提供されます。詳細については、ソースコードのドキュメント(Javadoc) を参照してください。

7.4.5. JSPの制限

組み込みサーブレットコンテナーを使用する(実行可能アーカイブとしてパッケージ化されている)Spring Bootアプリケーションを実行する場合、JSPサポートにはいくつかの制限があります。

  • JettyとTomcatでは、warパッケージを使用すれば動作するはずです。実行可能なwarは、java -jarで起動すると動作し、任意の標準コンテナーに配備することもできます。実行可能jarを使用する場合、JSPはサポートされません。

  • UndertowはJSPをサポートしていません。

  • カスタム error.jsp ページを作成しても、エラー処理のデフォルトビューは上書きされません。代わりにカスタムエラーページを使用する必要があります。

7.5. 埋め込み型リアクティブサーバーのサポート

Spring Bootには、Reactor、Netty、Tomcat、Jetty、およびUndertowの埋め込み型リアクティブWebサーバーのサポートが含まれています。ほとんどの開発者は適切な「スターター」を使用して、完全に構成されたインスタンスを取得します。デフォルトでは、組み込みサーバーはポート8080でHTTPリクエストをリッスンします。

7.6. リアクティブサーバーリソースの構成

Reactor NettyまたはJettyサーバーを自動構成する場合、Spring Bootは、サーバーインスタンスにHTTPリソースを提供する特定のBean ReactorResourceFactory または JettyResourceFactoryを作成します。

デフォルトでは、これらのリソースは、最適なパフォーマンスのために、Reactor NettyおよびJettyクライアントとも共有されます。

  • 同じテクノロジーがサーバーとクライアントに使用されます

  • クライアントインスタンスは、Spring Bootによって自動構成された WebClient.Builder Beanを使用して構築されます

開発者は、カスタム ReactorResourceFactory または JettyResourceFactory Beanを提供することにより、JettyおよびReactor Nettyのリソース構成をオーバーライドできます。これは、クライアントとサーバーの両方に適用されます。

WebClientランタイムセクションでクライアント側のリソース構成について詳しく知ることができます。

8. RSocket

RSocket(英語) は、バイトストリームトランスポートで使用するバイナリプロトコルです。単一の接続を介して渡す非同期メッセージを介して対称相互作用モデルを有効にします。

Spring Frameworkの spring-messaging モジュールは、クライアント側とサーバー側の両方でRSocketリクエスターとレスポンダーのサポートを提供します。RSocketプロトコルの概要など、詳細については、Spring FrameworkリファレンスのRSocketセクションを参照してください。

8.1. RSocket戦略の自動構成

Spring Bootは、RSocketペイロードのエンコードおよびデコードに必要なすべてのインフラストラクチャを提供する RSocketStrategies Beanを自動構成します。デフォルトでは、自動構成は以下を順番に構成しようとします。

  1. Jacksonを使用したCBOR(英語) コーデック

  2. Jacksonを使用したJSONコーデック

spring-boot-starter-rsocket スターターは両方の依存関係を提供します。Jacksonサポートセクションをチェックして、カスタマイズの可能性について詳しく調べましょう。

開発者は、RSocketStrategiesCustomizer インターフェースを実装するBeanを作成することにより、RSocketStrategies コンポーネントをカスタマイズできます。コーデックの順序を決定するため、@Order は重要であることに注意してください。

8.2. RSocketサーバーの自動構成

Spring Bootは、RSocketサーバーの自動構成を提供します。必要な依存関係は spring-boot-starter-rsocketによって提供されます。

Spring Bootを使用すると、WebFluxサーバーからWebSocketを介してRSocketを公開したり、独立したRSocketサーバーを立ち上げることができます。これは、アプリケーションのタイプとその構成によって異なります。

WebFluxアプリケーション(つまり、タイプ WebApplicationType.REACTIVE)の場合、RSocketサーバーは、次のプロパティが一致する場合にのみWebサーバーにプラグインされます。

spring.rsocket.server.mapping-path=/rsocket # a mapping path is defined
spring.rsocket.server.transport=websocket # websocket is chosen as a transport
#spring.rsocket.server.port= # no port is defined
RSocketをWebサーバーに接続することは、Reactor Nettyでのみサポートされています。RSocket自体はそのライブラリで構築されています。

または、RSocket TCPまたはwebsocketサーバーは、独立した組み込みサーバーとして起動されます。依存関係の要件に加えて、唯一の必要な構成は、そのサーバーのポートを定義することです。

spring.rsocket.server.port=9898 # the only required configuration
spring.rsocket.server.transport=tcp # you're free to configure other properties

8.3. SpringメッセージングRSocketサポート

Spring Bootは、RSocketのSpringメッセージングインフラストラクチャを自動構成します。

これは、Spring Bootが、アプリケーションへのRSocket要求を処理する RSocketMessageHandler Beanを作成することを意味します。

8.4. RSocketRequesterを使用したRSocketサービスの呼び出し

サーバーとクライアントの間に RSocket チャネルが確立されると、どのパーティも相手とリクエストを送受信できます。

サーバーとして、RSocket @Controllerの任意のハンドラーメソッドで RSocketRequester インスタンスをインジェクトできます。クライアントとして、最初にRSocket接続を設定および確立する必要があります。Spring Bootは、予想されるコーデックでこのような場合に RSocketRequester.Builder を自動構成します。

RSocketRequester.Builder インスタンスはプロトタイプBeanです。つまり、各注入ポイントは新しいインスタンスを提供します。このビルダーはステートフルであり、同じインスタンスを使用して異なる設定でリクエスターを作成しないでくださいため、これは意図的に行われます。

次のコードは典型的な例を示しています。

@Service
public class MyService {

    private final Mono<RSocketRequester> rsocketRequester;

    public MyService(RSocketRequester.Builder rsocketRequesterBuilder) {
        this.rsocketRequester = rsocketRequesterBuilder
                .connectTcp("example.org", 9898).cache();
    }

    public Mono<User> someRSocketCall(String name) {
        return this.rsocketRequester.flatMap(req ->
                    req.route("user").data(name).retrieveMono(User.class));
    }

}

9. セキュリティ

Spring Securityがクラスパスにある場合、Webアプリケーションはデフォルトで保護されます。Spring Bootは、Spring Securityのコンテンツネゴシエーション戦略に基づいて、httpBasicformLoginのどちらを使用するかを決定します。メソッドレベルのセキュリティをWebアプリケーションに追加するために、必要な設定で @EnableGlobalMethodSecurity を追加することもできます。追加情報はSpring Securityリファレンスガイドにあります。

デフォルトの UserDetailsService には単一のユーザーがいます。ユーザー名は userであり、パスワードはランダムであり、次の例に示すように、アプリケーションの起動時にINFOレベルで出力されます。

Using generated security password: 78fa095d-3f4c-48b1-ad50-e24c31d5cf35
ロギング構成を微調整する場合は、org.springframework.boot.autoconfigure.security カテゴリーが INFO -levelメッセージを記録するように設定されていることを確認してください。それ以外の場合、デフォルトのパスワードは出力されません。

spring.security.user.name および spring.security.user.passwordを提供することにより、ユーザー名とパスワードを変更できます。

Webアプリケーションでデフォルトで取得する基本機能は次のとおりです。

  • UserDetailsService (またはWebFluxアプリケーションの場合は ReactiveUserDetailsService )メモリ内ストアを持つBeanと、生成されたパスワードを持つ単一のユーザー(ユーザーのプロパティについては SecurityProperties.User (Javadoc) を参照)。

  • アプリケーション全体(アクチュエーターがクラスパス上にある場合はアクチュエーターエンドポイントを含む)に対するフォームベースのログインまたはHTTP Basicセキュリティ(リクエストの Accept ヘッダーに依存)。

  • 認証イベントを公開するための DefaultAuthenticationEventPublisher

Beanを追加することにより、異なる AuthenticationEventPublisher を提供できます。

9.1. MVCセキュリティ

デフォルトのセキュリティ構成は、SecurityAutoConfiguration および UserDetailsServiceAutoConfigurationに実装されています。 SecurityAutoConfiguration はWebセキュリティ用に SpringBootWebSecurityConfiguration をインポートし、UserDetailsServiceAutoConfiguration は認証を構成します。これは非Webアプリケーションにも関連します。デフォルトのWebアプリケーションセキュリティ設定を完全にオフにするには、またはOAuth 2クライアントやリソースサーバーなどの複数のSpring Securityコンポーネントを組み合わせるには、タイプ WebSecurityConfigurerAdapter のBeanを追加します(これにより、UserDetailsService 構成またはアクチュエーターのセキュリティが無効になりません)。

UserDetailsService 構成もオフにするには、タイプ UserDetailsService, AuthenticationProviderまたは AuthenticationManagerのBeanを追加できます。

カスタム WebSecurityConfigurerAdapterを追加することにより、アクセスルールをオーバーライドできます。Spring Bootは、アクチュエーターエンドポイントおよび静的リソースのアクセスルールをオーバーライドするために使用できる便利なメソッドを提供します。 EndpointRequest を使用して、management.endpoints.web.base-path プロパティに基づく RequestMatcher を作成できます。 PathRequest を使用して、一般的に使用される場所のリソース用の RequestMatcher を作成できます。

9.2. WebFluxセキュリティ

Spring MVCアプリケーションと同様に、spring-boot-starter-security 依存関係を追加することにより、WebFluxアプリケーションを保護できます。デフォルトのセキュリティ構成は、ReactiveSecurityAutoConfiguration および UserDetailsServiceAutoConfigurationに実装されています。 ReactiveSecurityAutoConfiguration はWebセキュリティのために WebFluxSecurityConfiguration をインポートし、UserDetailsServiceAutoConfiguration は認証を構成します。これは非Webアプリケーションにも関連します。デフォルトのWebアプリケーションセキュリティ設定を完全にオフにするには、タイプ WebFilterChainProxy のBeanを追加できます(これにより、UserDetailsService 設定またはアクチュエーターのセキュリティが無効になりません)。

UserDetailsService 構成もオフにするには、タイプ ReactiveUserDetailsService または ReactiveAuthenticationManagerのBeanを追加できます。

カスタム SecurityWebFilterChain Beanを追加することにより、アクセスルールと、OAuth 2クライアントやリソースサーバーなどの複数のSpring Securityコンポーネントの使用を構成できます。Spring Bootは、アクチュエーターエンドポイントおよび静的リソースのアクセスルールをオーバーライドするために使用できる便利なメソッドを提供します。 EndpointRequest を使用して、management.endpoints.web.base-path プロパティに基づく ServerWebExchangeMatcher を作成できます。

PathRequest を使用して、一般的に使用される場所のリソース用の ServerWebExchangeMatcher を作成できます。

例:次のようなものを追加して、セキュリティ構成をカスタマイズできます。

@Bean
public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
    return http
        .authorizeExchange()
            .matchers(PathRequest.toStaticResources().atCommonLocations()).permitAll()
            .pathMatchers("/foo", "/bar")
                .authenticated().and()
            .formLogin().and()
        .build();
}

9.3. OAuth2

OAuth2(英語) は、Springでサポートされている広く使用されている認可フレームワークです。

9.3.1. クライアント

クラスパスに spring-security-oauth2-client がある場合、自動構成を利用して、OAuth2 / Open ID Connectクライアントを簡単にセットアップできます。この構成では、OAuth2ClientPropertiesのプロパティを使用します。同じプロパティが、サーブレットアプリケーションとリアクティブアプリケーションの両方に適用可能です。

次の例に示すように、spring.security.oauth2.client プレフィックスに複数のOAuth2クライアントとプロバイダーを登録できます。

spring.security.oauth2.client.registration.my-client-1.client-id=abcd
spring.security.oauth2.client.registration.my-client-1.client-secret=password
spring.security.oauth2.client.registration.my-client-1.client-name=Client for user scope
spring.security.oauth2.client.registration.my-client-1.provider=my-oauth-provider
spring.security.oauth2.client.registration.my-client-1.scope=user
spring.security.oauth2.client.registration.my-client-1.redirect-uri=https://my-redirect-uri.com
spring.security.oauth2.client.registration.my-client-1.client-authentication-method=basic
spring.security.oauth2.client.registration.my-client-1.authorization-grant-type=authorization_code

spring.security.oauth2.client.registration.my-client-2.client-id=abcd
spring.security.oauth2.client.registration.my-client-2.client-secret=password
spring.security.oauth2.client.registration.my-client-2.client-name=Client for email scope
spring.security.oauth2.client.registration.my-client-2.provider=my-oauth-provider
spring.security.oauth2.client.registration.my-client-2.scope=email
spring.security.oauth2.client.registration.my-client-2.redirect-uri=https://my-redirect-uri.com
spring.security.oauth2.client.registration.my-client-2.client-authentication-method=basic
spring.security.oauth2.client.registration.my-client-2.authorization-grant-type=authorization_code

spring.security.oauth2.client.provider.my-oauth-provider.authorization-uri=https://my-auth-server/oauth/authorize
spring.security.oauth2.client.provider.my-oauth-provider.token-uri=https://my-auth-server/oauth/token
spring.security.oauth2.client.provider.my-oauth-provider.user-info-uri=https://my-auth-server/userinfo
spring.security.oauth2.client.provider.my-oauth-provider.user-info-authentication-method=header
spring.security.oauth2.client.provider.my-oauth-provider.jwk-set-uri=https://my-auth-server/token_keys
spring.security.oauth2.client.provider.my-oauth-provider.user-name-attribute=name

OpenID Connectディスカバリ(英語) をサポートするOpenID Connectプロバイダーの場合、構成をさらに簡素化できます。プロバイダーは、発行者IDとしてアサートするURIである issuer-uri で構成する必要があります。例:提供された issuer-uri が「https://example.com」の場合、OpenID Provider Configuration Request は「https://example.com/.well-known/openid-configuration」になります。結果は OpenID Provider Configuration Responseになると予想されます。次の例は、issuer-uriを使用してOpenID Connectプロバイダーを構成する方法を示しています。

spring.security.oauth2.client.provider.oidc-provider.issuer-uri=https://dev-123456.oktapreview.com/oauth2/default/

デフォルトでは、Spring Securityの OAuth2LoginAuthenticationFilter/login/oauth2/code/*に一致するURLのみを処理します。 redirect-uri をカスタマイズして別のパターンを使用する場合は、そのカスタムパターンを処理するための構成を提供する必要があります。例:サーブレットアプリケーションの場合、次のような独自の WebSecurityConfigurerAdapter を追加できます。

public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .anyRequest().authenticated()
                .and()
            .oauth2Login()
                .redirectionEndpoint()
                    .baseUri("/custom-callback");
    }
}
一般的なプロバイダーのOAuth2クライアント登録

Google、Github、Facebook、およびOktaを含む一般的なOAuth2およびOpenIDプロバイダーには、一連のプロバイダーのデフォルト(それぞれgoogle, github, facebookおよび okta)を提供します。

これらのプロバイダーをカスタマイズする必要がない場合は、provider 属性をデフォルトを推測する必要がある属性に設定できます。また、クライアント登録のキーがデフォルトでサポートされているプロバイダーと一致する場合、Spring Bootも同様に推測します。

つまり、次の例の2つの構成では、Googleプロバイダーを使用しています。

spring.security.oauth2.client.registration.my-client.client-id=abcd
spring.security.oauth2.client.registration.my-client.client-secret=password
spring.security.oauth2.client.registration.my-client.provider=google

spring.security.oauth2.client.registration.google.client-id=abcd
spring.security.oauth2.client.registration.google.client-secret=password

9.3.2. リソースサーバー

クラスパスに spring-security-oauth2-resource-server がある場合、Spring BootはOAuth2リソースサーバーをセットアップできます。JWT構成の場合、次の例に示すように、JWKセットURIまたはOIDC発行者URIを指定する必要があります。

spring.security.oauth2.resourceserver.jwt.jwk-set-uri=https://example.com/oauth2/default/v1/keys
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://dev-123456.oktapreview.com/oauth2/default/
認可サーバーがJWK Set URIをサポートしていない場合、JWTの署名の検証に使用される公開鍵でリソースサーバーを構成できます。これは、spring.security.oauth2.resourceserver.jwt.public-key-location プロパティを使用して実行できます。値は、PEMエンコードされたx509形式の公開キーを含むファイルを指す必要があります。

同じプロパティは、サーブレットアプリケーションと事後アプリケーションの両方に適用できます。

または、サーブレットアプリケーション用に独自の JwtDecoder Beanを定義するか、リアクティブアプリケーション用に ReactiveJwtDecoder を定義できます。

JWTの代わりにOpaqueトークンが使用される場合、次のプロパティを設定して、イントロスペクションを介してトークンを検証できます。

spring.security.oauth2.resourceserver.opaquetoken.introspection-uri=https://example.com/check-token
spring.security.oauth2.resourceserver.opaquetoken.client-id=my-client-id
spring.security.oauth2.resourceserver.opaquetoken.client-secret=my-client-secret

繰り返しますが、同じプロパティがサーブレットとリアクティブの両方のアプリケーションに適用可能です。

または、サーブレットアプリケーション用に独自の OpaqueTokenIntrospector Beanを定義するか、リアクティブアプリケーション用に ReactiveOpaqueTokenIntrospector を定義できます。

9.3.3. 認可サーバー

現在、Spring SecurityはOAuth 2.0認可サーバーの実装をサポートしていません。ただし、この機能はSpring Security OAuthプロジェクトから利用でき、最終的にはSpring Securityに完全に置き換えられます。それまでは、spring-security-oauth2-autoconfigure モジュールを使用して、OAuth 2.0認可サーバーを簡単にセットアップできます。手順については、ドキュメント(英語) を参照してください。

9.4. SAML 2.0

9.4.1. 証明書利用者

クラスパスに spring-security-saml2-service-provider がある場合、いくつかの自動構成を利用して、SAML 2.0証明書利用者を簡単にセットアップできます。この構成では、Saml2RelyingPartyPropertiesのプロパティを使用します。

証明書利用者登録は、IDプロバイダーIDPとサービスプロバイダーSPの間のペア構成を表します。次の例に示すように、spring.security.saml2.relyingparty プレフィックスに複数の証明書利用者を登録できます。

spring.security.saml2.relyingparty.registration.my-relying-party1.signing.credentials[0].private-key-location=path-to-private-key
spring.security.saml2.relyingparty.registration.my-relying-party1.signing.credentials[0].certificate-location=path-to-certificate
spring.security.saml2.relyingparty.registration.my-relying-party1.identityprovider.verification.credentials[0].certificate-location=path-to-verification-cert
spring.security.saml2.relyingparty.registration.my-relying-party1.identityprovider.entity-id=remote-idp-entity-id1
spring.security.saml2.relyingparty.registration.my-relying-party1.identityprovider.sso-url=https://remoteidp1.sso.url

spring.security.saml2.relyingparty.registration.my-relying-party2.signing.credentials[0].private-key-location=path-to-private-key
spring.security.saml2.relyingparty.registration.my-relying-party2.signing.credentials[0].certificate-location=path-to-certificate
spring.security.saml2.relyingparty.registration.my-relying-party2.identityprovider.verification.credentials[0].certificate-location=path-to-other-verification-cert
spring.security.saml2.relyingparty.registration.my-relying-party2.identityprovider.entity-id=remote-idp-entity-id2
spring.security.saml2.relyingparty.registration.my-relying-party2.identityprovider.sso-url=https://remoteidp2.sso.url

9.5. アクチュエーターのセキュリティ

セキュリティのために、/health および /info 以外のすべてのアクチュエーターはデフォルトで無効になっています。 management.endpoints.web.exposure.include プロパティを使用して、アクチュエーターを有効にすることができます。

Spring Securityがクラスパス上にあり、他のWebSecurityConfigurerAdapterが存在しない場合、/health および /info 以外のすべてのアクチュエーターは、Spring Boot自動構成によって保護されます。カスタム WebSecurityConfigurerAdapterを定義すると、Spring Bootの自動構成がバックオフし、アクチュエーターアクセスルールを完全に制御できるようになります。

management.endpoints.web.exposure.includeを設定する前に、露出したアクチュエーターに機密情報が含まれていないこと、および/またはファイアウォールの背後に配置したり、Spring Securityのようなもので保護することを確認してください。

9.5.1. クロスサイトリクエストフォージェリ保護

Spring BootはSpring Securityのデフォルトに依存しているため、CSRF保護はデフォルトでオンになっています。つまり、POST (シャットダウンおよびロガーのエンドポイント)、PUT、または DELETE を必要とするアクチュエーターエンドポイントは、デフォルトのセキュリティ構成が使用されている場合、403禁止エラーを受け取ります。

非ブラウザクライアントによって使用されるサービスを作成している場合にのみ、CSRF保護を完全に無効にすることをお勧めします。

CSRF保護に関する追加情報は、Spring Securityリファレンスガイドにあります。

10. SQLデータベースでの作業

Spring Frameworkは、JdbcTemplate を使用したJDBCへの直接アクセスから、Hibernateなどの「オブジェクトリレーショナルマッピング」テクノロジーの完成まで、SQLデータベースの操作に対する広範なサポートを提供します。Spring Dataは追加レベルの機能を提供します。Repository 実装をインターフェースから直接作成し、規約を使用してメソッド名からクエリを生成します。

10.1. DataSourceを構成する

Javaの javax.sql.DataSource インターフェースは、データベース接続を操作する標準的な方法を提供します。伝統的に、「DataSource」は、URL といくつかの資格情報を使用してデータベース接続を確立します。

通常、DataSourceの構成を完全に制御するためのより高度な例については、「方法」セクションを参照してください。

10.1.1. 組み込みデータベースのサポート

インメモリ埋め込みデータベースを使用してアプリケーションを開発すると便利な場合がよくあります。明らかに、インメモリデータベースは永続的なストレージを提供しません。アプリケーションの起動時にデータベースにデータを入力し、アプリケーションの終了時にデータを破棄する準備をする必要があります。

「使い方」セクションには、データベースの初期化方法に関するセクションが含まれています。

Spring Bootは、組み込みH2(英語) HSQL(英語) 、およびDerby(Apache) データベースを自動構成できます。接続URLを提供する必要はありません。使用する組み込みデータベースへのビルド依存関係のみを含める必要があります。

テストでこの機能を使用している場合、使用するアプリケーションコンテキストの数に関係なく、テストスイート全体で同じデータベースが再利用されることに気付く場合があります。各コンテキストに個別の組み込みデータベースがあることを確認する場合は、spring.datasource.generate-unique-nametrueに設定する必要があります。

例:典型的なPOM依存関係は次のとおりです。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>org.hsqldb</groupId>
    <artifactId>hsqldb</artifactId>
    <scope>runtime</scope>
</dependency>
組み込みデータベースを自動構成するには、spring-jdbc に依存する必要があります。この例では、spring-boot-starter-data-jpaを介して推移的にプルされます。
何らかの理由で埋め込みデータベースの接続URLを構成する場合は、データベースの自動シャットダウンが無効になっていることを確認してください。H2を使用する場合は、DB_CLOSE_ON_EXIT=FALSE を使用する必要があります。HSQLDBを使用する場合は、shutdown=true が使用されていないことを確認する必要があります。データベースの自動シャットダウンを無効にすると、Spring Bootがデータベースを閉じるタイミングを制御できるため、データベースへのアクセスが不要になったときに確実に実行されます。

10.1.2. 本番データベースへの接続

本番データベース接続は、プーリング DataSourceを使用して自動構成することもできます。Spring Bootは、特定の実装を選択するために次のアルゴリズムを使用します。

  1. パフォーマンスと同時実行性の点から、HikariCP(GitHub) をお勧めします。HikariCPが使用可能な場合、常に選択します。

  2. それ以外の場合、Tomcatプーリング DataSource が利用可能であれば、それを使用します。

  3. HikariCPもTomcatプーリングデータソースも使用できず、Commons DBCP2(Apache) が使用可能な場合は、それを使用します。

spring-boot-starter-jdbc または spring-boot-starter-data-jpa の「スターター」を使用する場合、HikariCPへの依存関係が自動的に取得されます。

spring.datasource.type プロパティを設定することにより、そのアルゴリズムを完全にバイパスし、使用する接続プールを指定できます。 tomcat-jdbc はデフォルトで提供されているため、これはTomcatコンテナーでアプリケーションを実行する場合に特に重要です。
追加の接続プールは、常に手動で構成できます。独自の DataSource Beanを定義すると、自動構成は行われません。

DataSource構成は、spring.datasource.*の外部構成プロパティによって制御されます。例: application.propertiesで次のセクションを宣言できます。

spring.datasource.url=jdbc:mysql://localhost/test
spring.datasource.username=dbuser
spring.datasource.password=dbpass
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.url プロパティを設定して、少なくともURLを指定する必要があります。そうでない場合、Spring Bootは組み込みデータベースの自動構成を試みます。
Spring Bootは urlからほとんどのデータベースについて推測できるため、多くの場合、driver-class-nameを指定する必要はありません。
プーリング DataSource を作成するには、有効な Driver クラスが利用可能であることを確認できる必要があるため、何かを行う前にそれを確認します。つまり、spring.datasource.driver-class-name=com.mysql.jdbc.Driverを設定する場合、そのクラスはロード可能でなければなりません。

サポートされるオプションの詳細については、 DataSourceProperties (GitHub) を参照してください。これらは、実際の実装に関係なく機能する標準オプションです。それぞれの接頭辞(spring.datasource.hikari.*, spring.datasource.tomcat.*、および spring.datasource.dbcp2.*)を使用して、実装固有の設定を微調整することもできます。詳細については、使用している接続プール実装のドキュメントを参照してください。

たとえば、Tomcat接続プール(Apache) を使用する場合、次の例に示すように、多くの追加設定をカスタマイズできます。

# Number of ms to wait before throwing an exception if no connection is available.
spring.datasource.tomcat.max-wait=10000

# Maximum number of active connections that can be allocated from this pool at the same time.
spring.datasource.tomcat.max-active=50

# Validate the connection before borrowing it from the pool.
spring.datasource.tomcat.test-on-borrow=true

10.1.3. JNDI DataSourceへの接続

Spring Bootアプリケーションをアプリケーションサーバーにデプロイする場合、アプリケーションサーバーの組み込み機能を使用してDataSourceを構成および管理し、JNDIを使用してそれにアクセスすることができます。

spring.datasource.jndi-name プロパティは、特定のJNDIロケーションから DataSource にアクセスするための spring.datasource.url, spring.datasource.usernameおよび spring.datasource.password プロパティの代替として使用できます。例: application.properties の次のセクションは、JBoss ASで定義された DataSourceにアクセスする方法を示しています。

spring.datasource.jndi-name=java:jboss/datasources/customers

10.2. JdbcTemplateを使用する

Springの JdbcTemplate および NamedParameterJdbcTemplate クラスは自動構成されており、次の例に示すように、独自のBeanに直接 @Autowire できます。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final JdbcTemplate jdbcTemplate;

    @Autowired
    public MyBean(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    // ...

}

次の例に示すように、spring.jdbc.template.* プロパティを使用して、テンプレートの一部のプロパティをカスタマイズできます。

spring.jdbc.template.max-rows=500
NamedParameterJdbcTemplate は、バックグラウンドで同じ JdbcTemplate インスタンスを再利用します。複数の JdbcTemplate が定義されていて、1次候補が存在しない場合、NamedParameterJdbcTemplate は自動構成されません。

10.3. JPAおよびSpring Data JPA

Java Persistence APIは、オブジェクトをリレーショナルデータベースに「マップ」できる標準テクノロジーです。 spring-boot-starter-data-jpa POMを使用すると、簡単に開始できます。以下の重要な依存関係を提供します。

  • Hibernate:最も一般的なJPA実装の1つ。

  • Spring Data JPA:JPAベースのリポジトリを簡単に実装できます。

  • Spring ORM:Spring FrameworkからのコアORMサポート。

ここでは、JPAまたはSpring Dataの詳細については詳しく説明しません。spring.io“JPA でデータアクセス”ガイドに従い、Spring Data JPAおよびHibernate(英語) のリファレンスドキュメントを読むことができます。

10.3.1. エンティティクラス

従来、JPA「エンティティ」クラスは persistence.xml ファイルで指定されていました。Spring Bootでは、このファイルは不要であり、代わりに「エンティティスキャン」が使用されます。デフォルトでは、メイン構成クラス( @EnableAutoConfiguration または @SpringBootApplicationでアノテーションが付けられたもの)のすべてのパッケージが検索されます。

@Entity, @Embeddableまたは @MappedSuperclass のアノテーションが付けられたクラスが考慮されます。典型的なエンティティクラスは、次の例のようになります。

package com.example.myapp.domain;

import java.io.Serializable;
import javax.persistence.*;

@Entity
public class City implements Serializable {

    @Id
    @GeneratedValue
    private Long id;

    @Column(nullable = false)
    private String name;

    @Column(nullable = false)
    private String state;

    // ... additional members, often include @OneToMany mappings

    protected City() {
        // no-args constructor required by JPA spec
        // this one is protected since it shouldn't be used directly
    }

    public City(String name, String state) {
        this.name = name;
        this.state = state;
    }

    public String getName() {
        return this.name;
    }

    public String getState() {
        return this.state;
    }

    // ... etc

}
@EntityScan アノテーションを使用して、エンティティスキャンの場所をカスタマイズできます。「howto.html」使い方を参照してください。

10.3.2. Spring Data JPAリポジトリ

Spring Data JPAリポジトリは、データにアクセスするために定義できるインターフェースです。JPAクエリは、メソッド名から自動的に作成されます。例: CityRepository インターフェースは、特定の状態のすべての都市を見つけるために findAllByState(String state) メソッドを宣言する場合があります。

より複雑なクエリの場合、Spring Dataの Query (Javadoc) アノテーションでメソッドにアノテーションを付けることができます。

Spring Dataリポジトリは通常、 Repository (Javadoc) または CrudRepository (Javadoc) インターフェースから拡張されます。自動構成を使用する場合、リポジトリはメイン構成クラス( @EnableAutoConfiguration または @SpringBootApplicationでアノテーションが付けられたもの)を含むパッケージから検索されます。

次の例は、典型的なSpring Dataリポジトリインターフェース定義を示しています。

package com.example.myapp.domain;

import org.springframework.data.domain.*;
import org.springframework.data.repository.*;

public interface CityRepository extends Repository<City, Long> {

    Page<City> findAll(Pageable pageable);

    City findByNameAndStateAllIgnoringCase(String name, String state);

}

Spring Data JPAリポジトリは、3つの異なるブートストラップモードをサポートしています:デフォルト、遅延、およびレイジー。遅延または遅延ブートストラップを有効にするには、spring.data.jpa.repositories.bootstrap-mode プロパティをそれぞれ deferred または lazy に設定します。遅延または遅延ブートストラップを使用する場合、自動構成された EntityManagerFactoryBuilder は、コンテキストの AsyncTaskExecutorをブートストラップエグゼキューターとして使用します(存在する場合)。複数存在する場合は、applicationTaskExecutor という名前が使用されます。

Spring Data JPAに関して、ほんの少し触れただけです。詳細については、Spring Data JPAリファレンスドキュメントを参照してください。

10.3.3. JPAデータベースの作成と削除

デフォルトでは、組み込みデータベース(H2、HSQL、またはDerby)を使用する場合にのみ、JPAデータベースが自動的に作成されます。 spring.jpa.* プロパティを使用して、JPA設定を明示的に構成できます。例:テーブルを作成および削除するには、次の行を application.propertiesに追加します。

spring.jpa.hibernate.ddl-auto=create-drop
Hibernateの独自の内部プロパティ名(覚えている場合)は hibernate.hbm2ddl.autoです。 spring.jpa.properties.* を使用して、他のHibernateネイティブプロパティとともに設定できます(プレフィックスは、エンティティマネージャーに追加する前に削除されます)。次の行は、HibernateのJPAプロパティの設定例を示しています。
spring.jpa.properties.hibernate.globally_quoted_identifiers=true

上記の例の行は、hibernate.globally_quoted_identifiers プロパティの true の値をHibernateエンティティマネージャーに渡します。

デフォルトでは、ApplicationContext が開始されるまで、DDLの実行(または検証)は延期されます。 spring.jpa.generate-ddl フラグもありますが、ddl-auto 設定がよりきめ細かいため、Hibernate自動構成がアクティブな場合は使用されません。

10.3.4. ビューでEntityManagerを開きます

Webアプリケーションを実行している場合、Spring Bootはデフォルトで OpenEntityManagerInViewInterceptor (Javadoc) を登録して「ビューでEntityManagerを開く」パターンを適用し、Webビューでの遅延読み込みを可能にします。この動作が望ましくない場合は、application.propertiesspring.jpa.open-in-viewfalse に設定する必要があります。

10.4. Spring Data JDBC

Spring DataにはJDBCのリポジトリサポートが含まれており、CrudRepositoryのメソッドのSQLを自動的に生成します。より高度なクエリのために、@Query アノテーションが提供されています。

Spring Bootは、必要な依存関係がクラスパスにある場合、Spring DataのJDBCリポジトリを自動構成します。 spring-boot-starter-data-jdbcへの単一の依存関係でプロジェクトに追加できます。必要に応じて、@EnableJdbcRepositories アノテーションまたは JdbcConfiguration サブクラスをアプリケーションに追加して、Spring Data JDBCの構成を制御できます。

Spring Data JDBCの詳細については、リファレンスドキュメントを参照してください。

10.5. H2のWebコンソールを使用する

H2データベース(英語) は、Spring Bootが自動構成できるブラウザーベースのコンソール(英語) を提供します。コンソールは、次の条件が満たされると自動構成されます。

  • サーブレットベースのWebアプリケーションを開発しています。

  • com.h2database:h2 はクラスパス上にあります。

  • Spring Bootの開発者ツールを使用しています。

Spring Bootの開発者ツールを使用していないが、H2のコンソールを引き続き使用したい場合は、spring.h2.console.enabled プロパティを trueの値で構成できます。
H2コンソールは開発中の使用のみを目的としているため、spring.h2.console.enabled が本番環境で true に設定されないように注意する必要があります。

10.5.1. H2コンソールのパスを変更する

デフォルトでは、コンソールは /h2-consoleで使用可能です。 spring.h2.console.path プロパティを使用して、コンソールのパスをカスタマイズできます。

10.6. jOOQを使用する

jOOQオブジェクト指向クエリ( jOOQ(英語) )は、データベースからJavaコードを生成し、その流れるようなAPIを介してタイプセーフなSQLクエリを作成できるData Geekery(英語) の人気製品です。Spring Bootでは、有償版とオープンソース版の両方を使用できます。

10.6.1. コード生成

jOOQタイプセーフクエリを使用するには、データベーススキーマからJavaクラスを生成する必要があります。jOOQユーザーマニュアル(英語) の指示に従うことができます。 jooq-codegen-maven プラグインを使用し、spring-boot-starter-parent 「親POM」も使用する場合、プラグインの <version> タグを安全に省略できます。Springブート定義バージョン変数( h2.versionなど)を使用して、プラグインのデータベース依存関係を宣言することもできます。次のリストに例を示します。

<plugin>
    <groupId>org.jooq</groupId>
    <artifactId>jooq-codegen-maven</artifactId>
    <executions>
        ...
    </executions>
    <dependencies>
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <version>${h2.version}</version>
        </dependency>
    </dependencies>
    <configuration>
        <jdbc>
            <driver>org.h2.Driver</driver>
            <url>jdbc:h2:~/yourdatabase</url>
        </jdbc>
        <generator>
            ...
        </generator>
    </configuration>
</plugin>

10.6.2. DSLContextを使用する

jOOQが提供する流れるようなAPIは、org.jooq.DSLContext インターフェースを介して開始されます。Spring Bootは、DSLContext をSpring Beanとして自動構成し、それをアプリケーション DataSourceに接続します。 DSLContextを使用するには、次の例に示すように、@Autowire を使用できます。

@Component
public class JooqExample implements CommandLineRunner {

    private final DSLContext create;

    @Autowired
    public JooqExample(DSLContext dslContext) {
        this.create = dslContext;
    }

}
jOOQマニュアルでは、create という名前の変数を使用して DSLContextを保持する傾向があります。

その後、次の例に示すように、DSLContext を使用してクエリを作成できます。

public List<GregorianCalendar> authorsBornAfter1980() {
    return this.create.selectFrom(AUTHOR)
        .where(AUTHOR.DATE_OF_BIRTH.greaterThan(new GregorianCalendar(1980, 0, 1)))
        .fetch(AUTHOR.DATE_OF_BIRTH);
}

10.6.3. jOOQ SQLダイアレクト

spring.jooq.sql-dialect プロパティが設定されていない限り、Spring Bootはデータソースに使用するSQLダイアレクトを決定します。Spring Bootがダイアレクトを検出できなかった場合、DEFAULTを使用します。

Spring Bootは、jOOQのオープンソースバージョンでサポートされているダイアレクトのみを自動構成できます。

10.6.4. jOOQのカスタマイズ

jOOQ Configuration の作成時に使用される独自の @Bean 定義を定義することにより、より高度なカスタマイズを実現できます。次のjOOQタイプのBeanを定義できます。

  • ConnectionProvider

  • ExecutorProvider

  • TransactionProvider

  • RecordMapperProvider

  • RecordUnmapperProvider

  • Settings

  • RecordListenerProvider

  • ExecuteListenerProvider

  • VisitListenerProvider

  • TransactionListenerProvider

jOOQ構成を完全に制御したい場合は、独自の org.jooq.Configuration @Bean を作成することもできます。

11. NoSQLテクノロジーの使用

Spring Dataは、次のようなさまざまなNoSQLテクノロジーへのアクセスに役立つ追加プロジェクトを提供します。

Spring Bootは、Redis、MongoDB、Neo4j、Elasticsearch、Solr Cassandra、Couchbase、およびLDAPの自動構成を提供します。他のプロジェクトを利用することもできますが、自分で構成する必要があります。spring.io/projects/spring-dataの適切なリファレンスドキュメントを参照してください。

11.1. Redis

Redis(英語) は、キャッシュ、メッセージブローカー、および豊富な機能を備えたキーと値のストアです。Spring Bootは、Lettuce(GitHub) およびJedis(GitHub) クライアントライブラリの基本的な自動構成と、Spring Data Redis(GitHub) が提供する抽象化を提供します。

依存関係を便利な方法で収集するための spring-boot-starter-data-redis 「スターター」があります。デフォルトでは、Lettuce(GitHub) を使用します。そのスターターは、従来のアプリケーションとリアクティブアプリケーションの両方を処理します。

また、事後対応をサポートする他の店舗との一貫性を保つために、spring-boot-starter-data-redis-reactive 「スターター」も提供しています。

11.1.1. Redisへの接続

他のSpring Beanと同じように、自動構成された RedisConnectionFactory, StringRedisTemplateまたはvanilla RedisTemplate インスタンスを注入できます。デフォルトでは、インスタンスは localhost:6379のRedisサーバーへの接続を試みます。次のリストは、そのようなBeanの例を示しています。

@Component
public class MyBean {

    private StringRedisTemplate template;

    @Autowired
    public MyBean(StringRedisTemplate template) {
        this.template = template;
    }

    // ...

}
より高度なカスタマイズのために、LettuceClientConfigurationBuilderCustomizer を実装する任意の数のBeanを登録することもできます。Jedisを使用する場合は、JedisClientConfigurationBuilderCustomizer も利用できます。

自動構成タイプのいずれかの独自の @Bean を追加すると、デフォルトが置き換えられます( RedisTemplateの場合を除き、除外がそのタイプではなくBean名 redisTemplateに基づいている場合)。デフォルトでは、commons-pool2 がクラスパス上にある場合、プールされた接続ファクトリーを取得します。

11.2. MongoDB

MongoDB(英語) は、従来のテーブルベースのリレーショナルデータの代わりにJSONのようなスキーマを使用するオープンソースのNoSQLドキュメントデータベースです。Spring Bootは、spring-boot-starter-data-mongodb および spring-boot-starter-data-mongodb-reactive 「スターター」など、MongoDBを操作するためのいくつかの便利な機能を提供します。

11.2.1. MongoDBデータベースへの接続

Mongoデータベースにアクセスするには、自動構成された org.springframework.data.mongodb.MongoDbFactoryを挿入できます。デフォルトでは、インスタンスは mongodb://localhost/testでMongoDBサーバーへの接続を試みます。次の例は、MongoDBデータベースに接続する方法を示しています。

import org.springframework.data.mongodb.MongoDbFactory;
import com.mongodb.DB;

@Component
public class MyBean {

    private final MongoDbFactory mongo;

    @Autowired
    public MyBean(MongoDbFactory mongo) {
        this.mongo = mongo;
    }

    // ...

    public void example() {
        DB db = mongo.getDb();
        // ...
    }

}

次の例に示すように、spring.data.mongodb.uri プロパティを設定してURLを変更し、レプリカセットなどの追加設定を構成できます。

spring.data.mongodb.uri=mongodb://user:[email protected](英語)  :12345,mongo2.example.com:23456/test

または、Mongo 2.xを使用している限り、host / portを指定できます。例: application.propertiesで次の設定を宣言できます。

spring.data.mongodb.host=mongoserver
spring.data.mongodb.port=27017

独自の MongoClientを定義している場合、それを使用して適切な MongoDbFactoryを自動構成します。 com.mongodb.MongoClientcom.mongodb.client.MongoClient の両方がサポートされています。

Mongo 3.0 Javaドライバーを使用する場合、spring.data.mongodb.host および spring.data.mongodb.port はサポートされません。このような場合、spring.data.mongodb.uri を使用してすべての構成を提供する必要があります。
spring.data.mongodb.port が指定されていない場合、デフォルトの 27017 が使用されます。前に示した例からこの行を削除できます。
Spring Data Mongoを使用しない場合は、MongoDbFactoryを使用する代わりに com.mongodb.MongoClient Beanを注入できます。MongoDB接続の確立を完全に制御したい場合は、独自の MongoDbFactory または MongoClient Beanを宣言することもできます。
リアクティブドライバーを使用している場合、SSLにはNettyが必要です。Nettyが使用可能で、使用するファクトリーがまだカスタマイズされていない場合、自動構成によりこのファクトリーが自動的に構成されます。

11.2.2. MongoTemplate

Spring Data MongoDBは、その設計がSpringの JdbcTemplateに非常に似ている MongoTemplate (英語) クラスを提供します。 JdbcTemplateと同様に、Spring Bootは、次のように、テンプレートをインジェクトするためにBeanを自動構成します。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.mongodb.core.MongoTemplate;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final MongoTemplate mongoTemplate;

    @Autowired
    public MyBean(MongoTemplate mongoTemplate) {
        this.mongoTemplate = mongoTemplate;
    }

    // ...

}

詳細については、 MongoOperations Javadoc(英語) を参照してください。

11.2.3. Spring Data MongoDBリポジトリ

Spring Dataには、MongoDBのリポジトリサポートが含まれています。前述のJPAリポジトリと同様に、基本的な原則は、クエリがメソッド名に基づいて自動的に構築されることです。

実際、Spring Data JPAとSpring Data MongoDBの両方が同じ共通インフラストラクチャを共有しています。以前のJPAの例を使用できます。City がJPA @EntityではなくMongoデータクラスであると仮定すると、次の例に示すように同じように機能します。

package com.example.myapp.domain;

import org.springframework.data.domain.*;
import org.springframework.data.repository.*;

public interface CityRepository extends Repository<City, Long> {

    Page<City> findAll(Pageable pageable);

    City findByNameAndStateAllIgnoringCase(String name, String state);

}
@EntityScan アノテーションを使用して、ドキュメントのスキャン場所をカスタマイズできます。
リッチオブジェクトマッピングテクノロジを含むSpring Data MongoDBの詳細については、リファレンスドキュメントを参照してください

11.2.4. 組み込みMongo

Spring Bootは、組み込みMongo(GitHub) の自動構成を提供します。Spring Bootアプリケーションで使用するには、de.flapdoodle.embed:de.flapdoodle.embed.mongoに依存関係を追加します。

Mongoがリッスンするポートは、spring.data.mongodb.port プロパティを設定することで構成できます。ランダムに割り当てられた空きポートを使用するには、値0を使用します。MongoAutoConfiguration によって作成された MongoClient は、ランダムに割り当てられたポートを使用するように自動的に構成されます。

カスタムポートを構成しない場合、組み込みサポートはデフォルトで(27017ではなく)ランダムポートを使用します。

クラスパスにSLF4Jがある場合、Mongoによって生成された出力は、org.springframework.boot.autoconfigure.mongo.embedded.EmbeddedMongoという名前のロガーに自動的にルーティングされます。

独自の IMongodConfig および IRuntimeConfig Beanを宣言して、Mongoインスタンスの構成とロギングルーティングを制御できます。ダウンロード構成は、DownloadConfigBuilderCustomizer Beanを宣言することによりカスタマイズできます。

11.3. Neo4j

Neo4j(英語) は、ファーストクラスの関係で接続されたノードのリッチデータモデルを使用するオープンソースのNoSQLグラフデータベースであり、従来のRDBMSアプローチよりも接続されたビッグデータに適しています。Spring Bootは、spring-boot-starter-data-neo4j 「スターター」など、Neo4jでの作業にいくつかの便利な機能を提供します。

11.3.1. Neo4jデータベースへの接続

Neo4jサーバーにアクセスするために、自動構成された org.neo4j.ogm.session.Sessionを挿入できます。デフォルトでは、インスタンスはBoltプロトコルを使用して localhost:7687 でNeo4jサーバーに接続しようとします。次の例は、Neo4j Sessionを注入する方法を示しています。

@Component
public class MyBean {

    private final Session session;

    @Autowired
    public MyBean(Session session) {
        this.session = session;
    }

    // ...

}

次の例に示すように、spring.data.neo4j.* プロパティを設定することにより、使用するURIおよび資格情報を構成できます。

spring.data.neo4j.uri=bolt://my-server:7687
spring.data.neo4j.username=neo4j
spring.data.neo4j.password=secret

org.neo4j.ogm.config.Configuration Beanまたは org.neo4j.ogm.session.SessionFactory Beanを追加することにより、セッションの作成を完全に制御できます。

11.3.2. 埋め込みモードを使用する

org.neo4j:neo4j-ogm-embedded-driver をアプリケーションの依存関係に追加すると、Spring Bootは、アプリケーションのシャットダウン時にデータを保持しないNeo4jのインプロセス埋め込みインスタンスを自動的に構成します。

組み込みNeo4j OGMドライバーはNeo4jカーネル自体を提供しないため、org.neo4j:neo4j を依存関係として自分で宣言する必要があります。互換性のあるバージョンのリストについては、Neo4j OGMのドキュメントを参照して(英語) ください。

クラスパスに複数のドライバーがある場合、組み込みドライバーは他のドライバーよりも優先されます。 spring.data.neo4j.embedded.enabled=falseを設定することにより、埋め込みモードを明示的に無効にできます。

データNeo4jテストは、上記のように組み込みドライバーとNeo4jカーネルがクラスパス上にある場合、組み込みNeo4jインスタンスを自動的に使用します。

構成内のデータベースファイルへのパスを指定することにより、埋め込みモードの永続性を有効にできます。 spring.data.neo4j.uri=file://var/tmp/graph.db

11.3.3. ネイティブ型の使用

Neo4j-OGMは、java.time.*のようないくつかのタイプを、String ベースのプロパティまたはNeo4jが提供するネイティブタイプのいずれかにマッピングできます。後方互換性の理由から、Neo4j-OGMのデフォルトは String ベースの表現を使用することです。ネイティブ型を使用するには、org.neo4j:neo4j-ogm-bolt-native-types または org.neo4j:neo4j-ogm-embedded-native-typesのいずれかに依存関係を追加し、次の例に示すように spring.data.neo4j.use-native-types プロパティを構成します。

spring.data.neo4j.use-native-types=true

11.3.4. Neo4jSession

デフォルトでは、Webアプリケーションを実行している場合、セッションはリクエストの処理全体のスレッドにバインドされます(つまり、「セッションを表示中に開く」パターンを使用します)。この動作が望ましくない場合は、application.properties ファイルに次の行を追加します。

spring.data.neo4j.open-in-view=false

11.3.5. Spring Data Neo4jリポジトリ

Spring Dataには、Neo4jのリポジトリサポートが含まれています。

Spring Data Neo4jは、他の多くのSpring Dataモジュールと同様に、Spring Data JPAと共通のインフラストラクチャを共有しています。以前のJPAの例を使用して、City をJPA @Entity ではなくNeo4j OGM @NodeEntity として定義すると、リポジトリの抽象化は次の例に示すように同じように機能します。

package com.example.myapp.domain;

import java.util.Optional;

import org.springframework.data.neo4j.repository.*;

public interface CityRepository extends Neo4jRepository<City, Long> {

    Optional<City> findOneByNameAndState(String name, String state);

}

spring-boot-starter-data-neo4j 「スターター」により、リポジトリのサポートとトランザクション管理が可能になります。 @Configuration -beanでそれぞれ @EnableNeo4jRepositories@EntityScan を使用して、リポジトリとエンティティを探すように場所をカスタマイズできます。

オブジェクトマッピングテクノロジーを含むSpring Data Neo4jの詳細については、リファレンスドキュメントを参照してください(英語)

11.4. Solr

Apache Solr(英語) は検索エンジンです。Spring Bootは、Solr 5クライアントライブラリの基本的な自動構成と、Spring Data Solr(GitHub) が提供する抽象化を提供します。依存関係を便利な方法で収集するための spring-boot-starter-data-solr 「スターター」があります。

11.4.1. Solrへの接続

他のSpring Beanと同様に、自動構成された SolrClient インスタンスを注入できます。デフォルトでは、インスタンスは localhost:8983/solrのサーバーへの接続を試みます。次の例は、Solr Beanを注入する方法を示しています。

@Component
public class MyBean {

    private SolrClient solr;

    @Autowired
    public MyBean(SolrClient solr) {
        this.solr = solr;
    }

    // ...

}

タイプ SolrClientの独自の @Bean を追加すると、デフォルトが置き換えられます。

11.4.2. Spring Data Solrリポジトリ

Spring Dataには、Apache Solrのリポジトリサポートが含まれています。前述のJPAリポジトリと同様に、基本的な原則は、クエリがメソッド名に基づいて自動的に構築されることです。

実際、Spring Data JPA SolrとSpring Data Solrは、同じ共通インフラストラクチャを共有しています。以前のJPAの例を使用すると、City がJPA @Entityではなく @SolrDocument クラスになったと仮定すると、同じように機能します。

IP:Spring Data Solrの詳細については、リファレンスドキュメントを参照してください(英語)

11.5. Elasticsearch

Elasticsearch(英語) は、オープンソースの分散型RESTREST検索および分析エンジンです。Spring Bootは、Elasticsearchの基本的な自動構成を提供します。

Spring Bootはいくつかのクライアントをサポートしています:

  • 公式のJava「低レベル」および「高レベル」RESTクライアント

  • Spring Data Elasticsearchが提供する ReactiveElasticsearchClient

トランスポートクライアントは引き続き使用できますが、Spring Data Elasticsearch(GitHub) およびElasticsearch自体ではサポートが非推奨になりました。今後のリリースで削除される予定です。Spring Bootは、専用の「スターター」 spring-boot-starter-data-elasticsearchを提供します。

ElasticsearchとSpring Data Elasticsearchの両方がRESTクライアントの公式サポートを提供するため、Jest(GitHub) クライアントも非推奨になりました。

11.5.1. RESTクライアントを使用してElasticsearchに接続する

Elasticsearchには、クラスターのクエリに使用できる「低レベル」クライアントと「高レベル」クライアントの2つの異なるRESTクライアント(英語) が付属しています。

クラスパスに org.elasticsearch.client:elasticsearch-rest-client 依存関係がある場合、Spring Bootは、デフォルトで localhost:9200をターゲットとする RestClient Beanを自動構成および登録します。次の例に示すように、RestClient の構成方法をさらに調整できます。

spring.elasticsearch.rest.uris=https://search.example.com:9200
spring.elasticsearch.rest.read-timeout=10s
spring.elasticsearch.rest.username=user
spring.elasticsearch.rest.password=secret

より高度なカスタマイズのために、RestClientBuilderCustomizer を実装する任意の数のBeanを登録することもできます。登録を完全に制御するには、RestClient Beanを定義します。

クラスパスに org.elasticsearch.client:elasticsearch-rest-high-level-client 依存関係がある場合、Spring Bootは RestHighLevelClientを自動構成し、既存の RestClient BeanをラップしてHTTP構成を再利用します。

11.5.2. Reactive RESTクライアントを使用してElasticsearchに接続する

Spring Data Elasticsearchは、Elasticsearchインスタンスをリアクティブ方式で照会するために ReactiveElasticsearchClient を提供しています。WebFluxの WebClientの上に構築されているため、spring-boot-starter-elasticsearchspring-boot-starter-webflux の両方の依存関係がこのサポートを有効にできます。

デフォルトでは、Spring Bootは localhost:9200をターゲットとする ReactiveElasticsearchClient Beanを自動構成および登録します。次の例に示すように、構成方法をさらに調整できます。

spring.data.elasticsearch.client.reactive.endpoints=search.example.com:9200
spring.data.elasticsearch.client.reactive.use-ssl=true
spring.data.elasticsearch.client.reactive.socket-timeout=10s
spring.data.elasticsearch.client.reactive.username=user
spring.data.elasticsearch.client.reactive.password=secret

構成プロパティが十分ではなく、クライアント構成を完全に制御したい場合は、カスタム ClientConfiguration Beanを登録できます。

11.5.3. Jestを使用してElasticsearchに接続する

Spring Bootが公式 RestHighLevelClientをサポートするようになったため、Jestサポートは非推奨になりました。

クラスパスに Jest がある場合、デフォルトで localhost:9200をターゲットとする自動構成の JestClient を注入できます。次の例に示すように、クライアントの構成方法をさらに調整できます。

spring.elasticsearch.jest.uris=https://search.example.com:9200
spring.elasticsearch.jest.read-timeout=10000
spring.elasticsearch.jest.username=user
spring.elasticsearch.jest.password=secret

より高度なカスタマイズのために、HttpClientConfigBuilderCustomizer を実装する任意の数のBeanを登録することもできます。次の例では、追加のHTTP設定を調整します。

static class HttpSettingsCustomizer implements HttpClientConfigBuilderCustomizer {

    @Override
    public void customize(HttpClientConfig.Builder builder) {
        builder.maxTotalConnection(100).defaultMaxTotalConnectionPerRoute(5);
    }

}

登録を完全に制御するには、JestClient Beanを定義します。

11.5.4. Spring Dataを使用してElasticsearchに接続する

Elasticsearchに接続するには、RestHighLevelClient Beanを定義するか、Spring Bootによって自動構成するか、アプリケーションによって手動で提供する必要があります(前のセクションを参照)。この構成を配置すると、次の例に示すように、他のSpring Beanと同様に ElasticsearchRestTemplate を注入できます。

@Component
public class MyBean {

    private final ElasticsearchRestTemplate template;

    public MyBean(ElasticsearchRestTemplate template) {
        this.template = template;
    }

    // ...

}

spring-data-elasticsearch および WebClient (通常 spring-boot-starter-webflux)を使用するために必要な依存関係がある場合、Spring BootはReactiveElasticsearchClientおよび ReactiveElasticsearchTemplate をBeanとして自動構成することもできます。これらは、他のRESTクライアントに対応する事後対応型です。

11.5.5. Spring Data Elasticsearchリポジトリ

Spring Dataには、Elasticsearchのリポジトリサポートが含まれています。前述のJPAリポジトリと同様に、基本的な原則は、クエリがメソッド名に基づいて自動的に構築されることです。

実際、Spring Data JPAとSpring Data Elasticsearchの両方が同じ共通インフラストラクチャを共有しています。以前のJPAの例を使用すると、City がJPA @EntityではなくElasticsearch @Document クラスであると仮定すると、同じように機能します。

Spring Data Elasticsearchの詳細については、リファレンスドキュメントを参照してください(英語)

Spring Bootは、ElasticsearchRestTemplate または ReactiveElasticsearchTemplate Beanを使用して、クラシックおよびリアクティブの両方のElasticsearchリポジトリをサポートします。おそらく、これらのBeanは、必要な依存関係が存在する場合、Spring Bootによって自動構成されます。

Elasticsearchリポジトリのバッキングに独自のテンプレートを使用する場合は、"elasticsearchTemplate"という名前である限り、独自の ElasticsearchRestTemplate または ElasticsearchOperations @Beanを追加できます。Bean名が "reactiveElasticsearchTemplate"ReactiveElasticsearchTemplate および ReactiveElasticsearchOperationsにも同じことが当てはまります。

次のプロパティを使用して、リポジトリのサポートを無効にすることができます。

spring.data.elasticsearch.repositories.enabled=false

11.6. Cassandra

Cassandra(Apache) は、多くのコモディティサーバーで大量のデータを処理するために設計されたオープンソースの分散データベース管理システムです。Spring Bootは、Cassandraの自動構成と、Spring Data Cassandra(GitHub) が提供する抽象化を提供します。依存関係を便利な方法で収集するための spring-boot-starter-data-cassandra 「スターター」があります。

11.6.1. Cassandraへの接続

他のSpring Beanと同様に、自動構成された CassandraTemplate またはCassandra Session インスタンスを注入できます。 spring.data.cassandra.* プロパティを使用して、接続をカスタマイズできます。通常、次の例に示すように、keyspace-name および contact-points プロパティを提供します。

spring.data.cassandra.keyspace-name=mykeyspace
spring.data.cassandra.contact-points=cassandrahost1,cassandrahost2

より高度なカスタマイズのために、ClusterBuilderCustomizer を実装する任意の数のBeanを登録することもできます。

次のコードリストは、Cassandra Beanを挿入する方法を示しています。

@Component
public class MyBean {

    private CassandraTemplate template;

    @Autowired
    public MyBean(CassandraTemplate template) {
        this.template = template;
    }

    // ...

}

タイプ CassandraTemplateの独自の @Bean を追加すると、デフォルトが置き換えられます。

11.6.2. Spring Data Cassandraリポジトリ

Spring Dataには、Cassandraの基本的なリポジトリサポートが含まれています。現在、これは前述のJPAリポジトリよりも制限されており、ファインダメソッドに @Queryでアノテーションを付ける必要があります。

Spring Data Cassandraの詳細については、リファレンスドキュメントを参照してください

11.7. Couchbase

Couchbase(英語) は、対話型アプリケーション向けに最適化された、オープンソースの分散型マルチモデルNoSQLドキュメント指向データベースです。Spring Bootは、Couchbaseの自動構成と、Spring Data Couchbase(GitHub) が提供する抽象化を提供します。依存関係を便利な方法で収集するための spring-boot-starter-data-couchbase および spring-boot-starter-data-couchbase-reactive 「スターター」があります。

11.7.1. Couchbaseへの接続

Couchbase SDKといくつかの構成を追加することにより、Bucket および Cluster を取得できます。 spring.couchbase.* プロパティを使用して、接続をカスタマイズできます。通常、次の例に示すように、ブートストラップホスト、バケット名、およびパスワードを指定します。

spring.couchbase.bootstrap-hosts=my-host-1,192.168.1.123
spring.couchbase.bucket.name=my-bucket
spring.couchbase.bucket.password=secret
少なくともブートストラップホストを指定する必要があります。その場合、バケット名は default で、パスワードは空の文字列です。または、独自の org.springframework.data.couchbase.config.CouchbaseConfigurer @Bean を定義して、構成全体を制御できます。

CouchbaseEnvironment 設定の一部をカスタマイズすることもできます。たとえば、次の構成は、新しい Bucket を開くために使用するタイムアウトを変更し、SSLサポートを有効にします。

spring.couchbase.env.timeouts.connect=3000
spring.couchbase.env.ssl.key-store=/location/of/keystore.jks
spring.couchbase.env.ssl.key-store-password=secret

詳細については、spring.couchbase.env.* プロパティを確認してください。

11.7.2. Spring Data Couchbaseリポジトリ

Spring Dataには、Couchbaseのリポジトリサポートが含まれています。Spring Data Couchbaseの詳細については、リファレンスドキュメントを参照してください(英語)

他のSpring Beanと同様に、自動構成された CouchbaseTemplate インスタンスを注入できます。ただし、デフォルトの CouchbaseConfigurer が使用可能であれば(前述のようにCouchbaseサポートを有効にすると発生します)。

次の例は、Couchbase Beanを注入する方法を示しています。

@Component
public class MyBean {

    private final CouchbaseTemplate template;

    @Autowired
    public MyBean(CouchbaseTemplate template) {
        this.template = template;
    }

    // ...

}

自動構成によって提供されるBeanをオーバーライドするために、独自の構成で定義できるBeanがいくつかあります。

  • couchbaseTemplateという名前の CouchbaseTemplate @Bean

  • couchbaseIndexManagerという名前の IndexManager @Bean

  • couchbaseCustomConversionsという名前の CustomConversions @Bean

独自の構成でこれらの名前をハードコードしないようにするには、Spring Data Couchbaseが提供する BeanNames を再利用できます。たとえば、次のように、使用するコンバーターをカスタマイズできます。

@Configuration(proxyBeanMethods = false)
public class SomeConfiguration {

    @Bean(BeanNames.COUCHBASE_CUSTOM_CONVERSIONS)
    public CustomConversions myCustomConversions() {
        return new CustomConversions(...);
    }

    // ...

}
Spring Data Couchbaseの自動構成を完全にバイパスしたい場合は、org.springframework.data.couchbase.config.AbstractCouchbaseDataConfigurationの独自の実装を提供してください。

11.8. LDAP

LDAP(英語) (ライトウェイトディレクトリアクセスプロトコル)は、IPネットワークを介して分散ディレクトリ情報サービスにアクセスして維持するための、ベンダーに依存しないオープンな業界標準のアプリケーションプロトコルです。Spring Bootは、準拠するLDAPサーバーの自動構成と、UnboundID(英語) の組み込みインメモリLDAPサーバーのサポートを提供します。

LDAP抽象化はSpring Data LDAP(GitHub) によって提供されます。依存関係を便利な方法で収集するための spring-boot-starter-data-ldap 「スターター」があります。

11.8.1. LDAPサーバーへの接続

LDAPサーバーに接続するには、次の例に示すように、spring-boot-starter-data-ldap 「Starter」または spring-ldap-core への依存関係を宣言してから、application.propertiesでサーバーのURLを宣言してください。

spring.ldap.urls=ldap://myserver:1235
spring.ldap.username=admin
spring.ldap.password=secret

接続設定をカスタマイズする必要がある場合は、spring.ldap.base および spring.ldap.base-environment プロパティを使用できます。

LdapContextSource は、これらの設定に基づいて自動構成されます。たとえば PooledContextSourceを使用するなど、カスタマイズする必要がある場合は、自動構成された LdapContextSourceを注入できます。カスタマイズされた ContextSource@Primary のフラグを付けて、自動構成された LdapTemplate がそれを使用するようにしてください。

11.8.2. Spring Data LDAPリポジトリ

Spring Dataには、LDAPのリポジトリサポートが含まれています。Spring Data LDAPの詳細については、リファレンスドキュメントを参照してください(英語)

次の例に示すように、他のSpring Beanと同様に、自動構成された LdapTemplate インスタンスを注入することもできます。

@Component
public class MyBean {

    private final LdapTemplate template;

    @Autowired
    public MyBean(LdapTemplate template) {
        this.template = template;
    }

    // ...

}

11.8.3. 組み込みインメモリLDAPサーバー

テスト目的で、Spring BootはUnboundID(英語) からのインメモリLDAPサーバーの自動構成をサポートしています。サーバーを構成するには、次のように、com.unboundid:unboundid-ldapsdk に依存関係を追加し、spring.ldap.embedded.base-dn プロパティを宣言します。

spring.ldap.embedded.base-dn=dc=spring,dc=io

複数のbase-dn値を定義することは可能ですが、識別名には通常コンマが含まれるため、正しい表記を使用して定義する必要があります。

yamlファイルでは、yamlリスト表記を使用できます。

spring.ldap.embedded.base-dn:
  - dc=spring,dc=io
  - dc=pivotal,dc=io

プロパティファイルでは、プロパティ名の一部としてインデックスを含める必要があります。

spring.ldap.embedded.base-dn[0]=dc=spring,dc=io
spring.ldap.embedded.base-dn[1]=dc=pivotal,dc=io

デフォルトでは、サーバーはランダムなポートで起動し、通常のLDAPサポートをトリガーします。 spring.ldap.urls プロパティを指定する必要はありません。

クラスパスに schema.ldif ファイルがある場合、サーバーの初期化に使用されます。別のリソースから初期化スクリプトをロードする場合は、spring.ldap.embedded.ldif プロパティも使用できます。

デフォルトでは、LDIF ファイルを検証するために標準スキーマが使用されます。 spring.ldap.embedded.validation.enabled プロパティを設定することにより、検証を完全にオフにできます。カスタム属性がある場合は、spring.ldap.embedded.validation.schema を使用してカスタム属性タイプまたはオブジェクトクラスを定義できます。

11.9. InfluxDB

InfluxDB(英語) は、運用監視、アプリケーションメトリック、モノのインターネットセンサーデータ、リアルタイム分析などのフィールドにおける時系列データの高速で高可用性の保存と取得に最適化されたオープンソースの時系列データベースです。

11.9.1. InfluxDBへの接続

次の例に示すように、influxdb-java クライアントがクラスパス上にあり、データベースのURLが設定されている場合、Spring Bootは InfluxDB インスタンスを自動構成します。

spring.influx.url=https://172.0.0.1:8086

InfluxDBへの接続にユーザーとパスワードが必要な場合、それに応じて spring.influx.user および spring.influx.password プロパティを設定できます。

InfluxDBはOkHttpに依存しています。 InfluxDB がバックグラウンドで使用するHTTPクライアントを調整する必要がある場合は、InfluxDbOkHttpClientBuilderProvider Beanを登録できます。

12. キャッシング

Spring Frameworkは、アプリケーションに透過的にキャッシュを追加するためのサポートを提供します。コアでは、抽象化によりメソッドにキャッシュが適用されるため、キャッシュで利用可能な情報に基づいて実行回数が削減されます。キャッシングロジックは、呼び出し側に干渉することなく透過的に適用されます。Spring Bootは、@EnableCaching アノテーションを介してキャッシュサポートが有効になっている限り、キャッシュインフラストラクチャを自動構成します。

詳細については、Spring Frameworkリファレンスの関連セクションを確認してください。

簡単に言えば、次の例に示すように、サービスの操作にキャッシュを追加することは、メソッドに関連するアノテーションを追加するのと同じくらい簡単です。

import org.springframework.cache.annotation.Cacheable;
import org.springframework.stereotype.Component;

@Component
public class MathService {

    @Cacheable("piDecimals")
    public int computePiDecimal(int i) {
        // ...
    }

}

この例は、潜在的にコストのかかる操作でのキャッシュの使用を示しています。 computePiDecimalを呼び出す前に、抽象化は i 引数に一致する piDecimals キャッシュ内のエントリを探します。エントリが見つかった場合、キャッシュ内のコンテンツはすぐに呼び出し元に返され、メソッドは呼び出されません。それ以外の場合、メソッドが呼び出され、値を返す前にキャッシュが更新されます。

標準のJSR-107(JCache)アノテーション( @CacheResultなど)を透過的に使用することもできます。ただし、Spring CacheアノテーションとJCacheアノテーションを混在させないでください。

特定のキャッシュライブラリを追加しない場合、Spring Bootはメモリ内の同時マップを使用する単純なプロバイダーを自動構成します。キャッシュが必要な場合(前の例の piDecimals など)、このプロバイダーがキャッシュを作成します。単純なプロバイダーは、本番環境での使用にはあまりお勧めしませんが、使い始めて、機能を理解していることを確認するには最適です。使用するキャッシュプロバイダーについて決めたら、必ずそのドキュメントを読んで、アプリケーションが使用するキャッシュを構成する方法を理解しましょう。ほぼすべてのプロバイダーでは、アプリケーションで使用するすべてのキャッシュを明示的に構成する必要があります。 spring.cache.cache-names プロパティで定義されたデフォルトのキャッシュをカスタマイズする方法を提供するものもあります。

キャッシュからデータを透過的に更新または削除することもできます。

12.1. サポートされているキャッシュプロバイダー

キャッシュ抽象化は実際のストアを提供せず、org.springframework.cache.Cache および org.springframework.cache.CacheManager インターフェースによって具体化される抽象化に依存します。

タイプ CacheManager のBeanまたは cacheResolver という名前の CacheResolver を定義していない場合( CachingConfigurer (Javadoc) を参照)、Spring Bootは以下のプロバイダーを(示された順序で)検出しようとします。

spring.cache.type プロパティを設定することにより、特定のキャッシュプロバイダーを強制することもできます。特定の環境(テストなど)でキャッシュを完全に無効にする必要がある場合は、このプロパティを使用します。
spring-boot-starter-cache 「スターター」を使用して、基本的なキャッシュの依存関係をすばやく追加します。スターターは spring-context-supportを取り込みます。依存関係を手動で追加する場合、JCache、EhCache 2.x、またはCaffeineサポートを使用するには、spring-context-support を含める必要があります。

CacheManager がSpring Bootによって自動構成されている場合、CacheManagerCustomizer インターフェースを実装するBeanを公開することにより、完全に初期化される前に構成をさらに調整できます。次の例では、null 値を基になるマップに渡す必要があることを示すフラグを設定します。

@Bean
public CacheManagerCustomizer<ConcurrentMapCacheManager> cacheManagerCustomizer() {
    return new CacheManagerCustomizer<ConcurrentMapCacheManager>() {
        @Override
        public void customize(ConcurrentMapCacheManager cacheManager) {
            cacheManager.setAllowNullValues(false);
        }
    };
}
上記の例では、自動構成された ConcurrentMapCacheManager が予期されています。そうでない場合(独自の構成を提供したか、別のキャッシュプロバイダーが自動構成された場合)、カスタマイザーはまったく呼び出されません。カスタマイザーは必要な数だけ持つことができ、@Order または Orderedを使用してオーダーすることもできます。

12.1.1. 汎用

コンテキストが少なくとも 1つの org.springframework.cache.Cache Beanを定義している場合、汎用キャッシングが使用されます。そのタイプのすべてのBeanをラップする CacheManager が作成されます。

12.1.2. JCache (JSR-107)

JCache(英語) は、クラスパスに javax.cache.spi.CachingProvider が存在することでブートストラップされ(つまり、JSR-107準拠のキャッシングライブラリがクラスパスに存在します)、JCacheCacheManagerspring-boot-starter-cache 「スターター」によって提供されます。さまざまな準拠ライブラリが利用可能であり、Spring BootはEhcache 3、Hazelcast、およびInfinispanの依存関係管理を提供します。他の準拠ライブラリも追加できます。

複数のプロバイダーが存在する場合がありますが、その場合はプロバイダーを明示的に指定する必要があります。JSR-107標準が構成ファイルの場所を定義する標準化された方法を強制しない場合でも、Spring Bootは、次の例に示すように、実装の詳細でキャッシュを設定するために最善を尽くします。

# Only necessary if more than one provider is present
spring.cache.jcache.provider=com.acme.MyCachingProvider
spring.cache.jcache.config=classpath:acme.xml
キャッシュライブラリがネイティブ実装とJSR-107サポートの両方を提供する場合、Spring BootはJSR-107サポートを優先するため、別のJSR-107実装に切り替えると同じ機能を使用できます。
Spring BootはHazelcastを一般的にサポートしています。単一の HazelcastInstance が使用可能な場合、spring.cache.jcache.config プロパティが指定されていない限り、CacheManager にも自動的に再利用されます。

基になる javax.cache.cacheManagerをカスタマイズするには、2つの方法があります。

  • spring.cache.cache-names プロパティを設定することにより、起動時にキャッシュを作成できます。カスタム javax.cache.configuration.Configuration Beanが定義されている場合、それを使用してカスタマイズします。

  • org.springframework.boot.autoconfigure.cache.JCacheManagerCustomizer Beanは、完全なカスタマイズのために CacheManager を参照して呼び出されます。

標準 javax.cache.CacheManager Beanが定義されている場合、抽象化が期待する org.springframework.cache.CacheManager 実装で自動的にラップされます。それ以上のカスタマイズは適用されません。

12.1.3. EhCache 2.x

ehcache.xml という名前のファイルがクラスパスのルートで見つかる場合、EhCache(英語) 2.xが使用されます。EhCache 2.xが見つかった場合、spring-boot-starter-cache 「スターター」によって提供される EhCacheCacheManager を使用して、キャッシュマネージャーをブートストラップします。次の例に示すように、代替構成ファイルも提供できます。

spring.cache.ehcache.config=classpath:config/another-config.xml

12.1.4. Hazelcast

Spring BootはHazelcastを一般的にサポートしています。 HazelcastInstance が自動構成されている場合、CacheManagerに自動的にラップされます。

12.1.5. Infinispan

Infinispan(英語) にはデフォルトの構成ファイルの場所がないため、明示的に指定する必要があります。それ以外の場合、デフォルトのブートストラップが使用されます。

spring.cache.infinispan.config=infinispan.xml

spring.cache.cache-names プロパティを設定することにより、起動時にキャッシュを作成できます。カスタム ConfigurationBuilder Beanが定義されている場合、それを使用してキャッシュをカスタマイズします。

Spring BootでのInfinispanのサポートは組み込みモードに制限されており、非常に基本的なものです。さらにオプションが必要な場合は、代わりに公式のInfinispan Spring Bootスターターを使用する必要があります。詳細については、Infinispanのドキュメント(GitHub) を参照してください。

12.1.6. Couchbase

Couchbase(英語) Javaクライアントと couchbase-spring-cache 実装が使用可能であり、Couchbaseが構成されている場合、CouchbaseCacheManager が自動構成されます。 spring.cache.cache-names プロパティを設定することにより、起動時に追加のキャッシュを作成することもできます。これらのキャッシュは、自動構成された Bucket で動作します。カスタマイザーを使用して、別の Bucket に追加のキャッシュを作成することできます。「メイン」 Bucket に2つのキャッシュ(cache1 および cache2)が必要であり、「別の」 Bucketに2秒のカスタム存続時間を持つ1つの(cache3)キャッシュが必要であると仮定します。次のように、構成を通じて最初の2つのキャッシュを作成できます。

spring.cache.cache-names=cache1,cache2

次に、次のように、@Configuration クラスを定義して、追加の Bucket および cache3 キャッシュを構成できます。

@Configuration(proxyBeanMethods = false)
public class CouchbaseCacheConfiguration {

    private final Cluster cluster;

    public CouchbaseCacheConfiguration(Cluster cluster) {
        this.cluster = cluster;
    }

    @Bean
    public Bucket anotherBucket() {
        return this.cluster.openBucket("another", "secret");
    }

    @Bean
    public CacheManagerCustomizer<CouchbaseCacheManager> cacheManagerCustomizer() {
        return c -> {
            c.prepareCache("cache3", CacheBuilder.newInstance(anotherBucket())
                    .withExpiration(2));
        };
    }

}

このサンプル構成は、自動構成によって作成された Cluster を再利用します。

12.1.7. Redis

Redis(英語) が使用可能で構成されている場合、RedisCacheManager は自動構成されます。 spring.cache.cache-names プロパティを設定することにより、起動時に追加のキャッシュを作成でき、spring.cache.redis.* プロパティを使用してキャッシュのデフォルトを設定できます。たとえば、次の構成では、存続時間 10分で cache1 および cache2 キャッシュを作成します。

spring.cache.cache-names=cache1,cache2
spring.cache.redis.time-to-live=600000
デフォルトでは、2つの個別のキャッシュが同じキーを使用する場合、Redisに重複するキーがなく、無効な値を返すことができないように、キープレフィックスが追加されます。独自の RedisCacheManagerを作成する場合は、この設定を有効にしておくことを強くお勧めします。
独自の RedisCacheConfiguration @Bean を追加することにより、デフォルト構成を完全に制御できます。これは、デフォルトの直列化戦略をカスタマイズする場合に便利です。

構成をさらに制御する必要がある場合は、RedisCacheManagerBuilderCustomizer Beanの登録を検討してください。次の例は、cache1 および cache2の特定の存続時間を構成するカスタマイザーを示しています。

@Bean
public RedisCacheManagerBuilderCustomizer myRedisCacheManagerBuilderCustomizer() {
    return (builder) -> builder
            .withCacheConfiguration("cache1",
                    RedisCacheConfiguration.defaultCacheConfig().entryTtl(Duration.ofSeconds(10)))
            .withCacheConfiguration("cache2",
                    RedisCacheConfiguration.defaultCacheConfig().entryTtl(Duration.ofMinutes(1)));

}

12.1.8. Caffeine

Caffeine(GitHub) は、Guavaのサポートに代わるGuavaのキャッシュのJava 8の書き換えです。Caffeineが存在する場合、CaffeineCacheManagerspring-boot-starter-cache 「スターター」によって提供される)が自動構成されます。キャッシュは、起動時に spring.cache.cache-names プロパティを設定することで作成でき、次のいずれか(示された順序)でカスタマイズできます。

  1. spring.cache.caffeine.specによって定義されたキャッシュ仕様

  2. com.github.benmanes.caffeine.cache.CaffeineSpec Beanが定義されています

  3. com.github.benmanes.caffeine.cache.Caffeine Beanが定義されています

たとえば、次の構成では、最大サイズが500で存続時間が10分の cache1 および cache2 キャッシュが作成されます。

spring.cache.cache-names=cache1,cache2
spring.cache.caffeine.spec=maximumSize=500,expireAfterAccess=600s

com.github.benmanes.caffeine.cache.CacheLoader Beanが定義されている場合、CaffeineCacheManagerに自動的に関連付けられます。 CacheLoader はキャッシュマネージャーによって管理されるすべてのキャッシュに関連付けられるため、CacheLoader<Object, Object>として定義する必要があります。自動構成では、他の一般的なタイプは無視されます。

12.1.9. シンプル

他のプロバイダーが見つからない場合は、ConcurrentHashMap をキャッシュストアとして使用する単純な実装が構成されます。アプリケーションにキャッシングライブラリが存在しない場合、これがデフォルトです。デフォルトでは、キャッシュは必要に応じて作成されますが、cache-names プロパティを設定することにより、使用可能なキャッシュのリストを制限できます。たとえば、cache1 および cache2 キャッシュのみが必要な場合は、cache-names プロパティを次のように設定します。

spring.cache.cache-names=cache1,cache2

そうすると、アプリケーションがリストにないキャッシュを使用する場合、実行時にキャッシュが必要になりますが、起動時は失敗します。これは、宣言されていないキャッシュを使用する場合の「実際の」キャッシュプロバイダーの動作に似ています。

12.1.10. なし

@EnableCaching が構成に存在する場合、適切なキャッシュ構成も期待されます。特定の環境でキャッシュを完全に無効にする必要がある場合は、次の例に示すように、キャッシュタイプを強制的に none に設定して、no-op実装を使用します。

spring.cache.type=none

13. メッセージング

Spring Frameworkは、JmsTemplate を使用したJMS APIの単純化された使用から、メッセージを非同期で受信するための完全なインフラストラクチャまで、メッセージングシステムとの統合に対する広範なサポートを提供します。Spring AMQPは、Advanced Message Queuing Protocolに同様の機能セットを提供します。Spring Bootは、RabbitTemplate およびRabbitMQの自動構成オプションも提供します。Spring WebSocketはSTOMPメッセージングのサポートをネイティブに含み、Spring Bootはスターターおよび少量の自動構成を介してそれをサポートします。Spring Bootは、Apache Kafkaもサポートしています。

13.1. JMS

javax.jms.ConnectionFactory インターフェースは、JMSブローカーと対話するための javax.jms.Connection を作成する標準的な方法を提供します。SpringはJMSを使用するために ConnectionFactory を必要としますが、通常は直接使用する必要はなく、代わりに高レベルのメッセージング抽象化に依存できます。(詳細については、Spring Frameworkリファレンスドキュメントの関連セクションを参照してください。)Spring Bootは、メッセージを送受信するために必要なインフラストラクチャーを自動構成します。

13.1.1. ActiveMQサポート

ActiveMQ(Apache) がクラスパスで使用可能な場合、Spring Bootは ConnectionFactoryも構成できます。ブローカーが存在する場合、組み込みブローカーが自動的に開始および構成されます(構成によってブローカーURLが指定されていない場合)。

spring-boot-starter-activemqを使用する場合、JMSと統合するSpringインフラストラクチャと同様に、ActiveMQインスタンスの接続または埋め込みに必要な依存関係が提供されます。

ActiveMQ構成は、spring.activemq.*の外部構成プロパティによって制御されます。例: application.propertiesで次のセクションを宣言できます。

spring.activemq.broker-url=tcp://192.168.1.210:9876
spring.activemq.user=admin
spring.activemq.password=secret

デフォルトでは、CachingConnectionFactory は、spring.jms.*の外部構成プロパティによって制御できる適切な設定でネイティブ ConnectionFactory をラップします。

spring.jms.cache.session-cache-size=5

ネイティブプーリングを使用する場合は、次の例に示すように、org.messaginghub:pooled-jms に依存関係を追加し、それに応じて JmsPoolConnectionFactory を構成することにより、使用できます。

spring.activemq.pool.enabled=true
spring.activemq.pool.max-connections=50
サポートされるオプションの詳細については、 ActiveMQProperties (GitHub) を参照してください。より高度なカスタマイズのために、ActiveMQConnectionFactoryCustomizer を実装する任意の数のBeanを登録することもできます。

デフォルトでは、ActiveMQは宛先がまだ存在しない場合に宛先を作成し、指定された名前に対して宛先が解決されるようにします。

13.1.2. Artemisサポート

Spring Bootは、クラスパスでArtemis(Apache) が使用可能であることを検出すると、ConnectionFactory を自動構成できます。ブローカーが存在する場合、埋め込みモードのブローカーは自動的に起動および構成されます(モードプロパティが明示的に設定されていない場合)。サポートされるモードは、embedded (組み込みブローカーが必要であり、ブローカーがクラスパスで使用できない場合にエラーが発生することを明示するため)および nativenetty トランスポートプロトコルを使用してブローカーに接続するため)です。後者が構成されている場合、Spring Bootは、デフォルト設定でローカルマシンで実行されているブローカーに接続する ConnectionFactory を構成します。

spring-boot-starter-artemisを使用する場合、既存のArtemisインスタンスに接続するために必要な依存関係と、JMSと統合するSpringインフラストラクチャが提供されます。 org.apache.activemq:artemis-jms-server をアプリケーションに追加すると、埋め込みモードを使用できます。

Artemisの構成は、spring.artemis.*の外部構成プロパティによって制御されます。例: application.propertiesで次のセクションを宣言できます。

spring.artemis.mode=native
spring.artemis.host=192.168.1.210
spring.artemis.port=9876
spring.artemis.user=admin
spring.artemis.password=secret

ブローカーを埋め込むときに、永続性を有効にし、使用可能にする必要がある宛先をリストするかどうかを選択できます。これらをコンマ区切りリストとして指定して、デフォルトのオプションで作成するか、タイプ org.apache.activemq.artemis.jms.server.config.JMSQueueConfiguration または org.apache.activemq.artemis.jms.server.config.TopicConfigurationのBeanをそれぞれ高度なキューおよびトピック構成に定義できます。

デフォルトでは、CachingConnectionFactory は、spring.jms.*の外部構成プロパティによって制御できる適切な設定でネイティブ ConnectionFactory をラップします。

spring.jms.cache.session-cache-size=5

ネイティブプーリングを使用する場合は、次の例に示すように、org.messaginghub:pooled-jms に依存関係を追加し、それに応じて JmsPoolConnectionFactory を構成することにより、使用できます。

spring.artemis.pool.enabled=true
spring.artemis.pool.max-connections=50

サポートされるオプションの詳細については、 ArtemisProperties (GitHub) を参照してください。

JNDIルックアップは含まれず、宛先はArtemis構成の name 属性または構成を通じて提供された名前を使用して、名前に対して解決されます。

13.1.3. JNDI ConnectionFactoryを使用する

アプリケーションサーバーでアプリケーションを実行している場合、Spring BootはJNDIを使用してJMS ConnectionFactory を見つけようとします。デフォルトでは、java:/JmsXAjava:/XAConnectionFactory の場所がチェックされます。次の例に示すように、別の場所を指定する必要がある場合は、spring.jms.jndi-name プロパティを使用できます。

spring.jms.jndi-name=java:/MyConnectionFactory

13.1.4. メッセージを送る

Springの JmsTemplate は自動構成されており、次の例に示すように、独自のBeanに直接オートワイヤーできます。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.jms.core.JmsTemplate;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final JmsTemplate jmsTemplate;

    @Autowired
    public MyBean(JmsTemplate jmsTemplate) {
        this.jmsTemplate = jmsTemplate;
    }

    // ...

}
JmsMessagingTemplate (Javadoc) は、同様の方法で注入できます。 DestinationResolver または MessageConverter Beanが定義されている場合、自動構成された JmsTemplateに自動的に関連付けられます。

13.1.5. メッセージを受信する

JMSインフラストラクチャが存在する場合、Beanに @JmsListener のアノテーションを付けてリスナーエンドポイントを作成できます。 JmsListenerContainerFactory が定義されていない場合、デフォルトのものが自動的に構成されます。 DestinationResolver または MessageConverter Beanが定義されている場合、それらは自動的にデフォルトファクトリに関連付けられます。

デフォルトでは、デフォルトのファクトリはトランザクションです。 JtaTransactionManager が存在するインフラストラクチャで実行すると、デフォルトでリスナーコンテナーに関連付けられます。そうでない場合、sessionTransacted フラグが有効になります。後者のシナリオでは、リスナーメソッド(またはそのデリゲート)に @Transactional を追加することにより、ローカルデータストアトランザクションを受信メッセージの処理に関連付けることができます。これにより、ローカルトランザクションが完了すると、受信メッセージが確認されます。これには、同じJMSセッションで実行された応答メッセージの送信も含まれます。

次のコンポーネントは、someQueue 宛先にリスナーエンドポイントを作成します。

@Component
public class MyBean {

    @JmsListener(destination = "someQueue")
    public void processMessage(String content) {
        // ...
    }

}
詳細については、@EnableJmsのJavadocを参照してください。

さらに JmsListenerContainerFactory インスタンスを作成する必要がある場合、またはデフォルトをオーバーライドする場合は、Spring Bootが提供する DefaultJmsListenerContainerFactoryConfigurer を使用して、自動構成されたものと同じ設定で DefaultJmsListenerContainerFactory を初期化できます。

たとえば、次の例では、特定の MessageConverterを使用する別のファクトリーを公開しています。

@Configuration(proxyBeanMethods = false)
static class JmsConfiguration {

    @Bean
    public DefaultJmsListenerContainerFactory myFactory(
            DefaultJmsListenerContainerFactoryConfigurer configurer) {
        DefaultJmsListenerContainerFactory factory =
                new DefaultJmsListenerContainerFactory();
        configurer.configure(factory, connectionFactory());
        factory.setMessageConverter(myMessageConverter());
        return factory;
    }

}

その後、次のように @JmsListenerアノテーション付きメソッドでファクトリーを使用できます。

@Component
public class MyBean {

    @JmsListener(destination = "someQueue", containerFactory="myFactory")
    public void processMessage(String content) {
        // ...
    }

}

13.2. AMQP

Advanced Message Queuing Protocol(AMQP)は、メッセージ指向ミドルウェア向けのプラットフォームに依存しないワイヤーレベルのプロトコルです。Spring AMQPプロジェクトは、コアSpringコンセプトをAMQPベースのメッセージングソリューションの開発に適用します。Spring Bootは、spring-boot-starter-amqp 「スターター」など、RabbitMQを介してAMQPを操作するためのいくつかの便利な機能を提供します。

13.2.1. RabbitMQサポート

RabbitMQ(英語) は、AMQPプロトコルに基づいた、軽量で信頼性が高く、スケーラブルでポータブルなメッセージブローカーです。Springは、RabbitMQ を使用してAMQPプロトコルを介して通信します。

RabbitMQ構成は、spring.rabbitmq.*の外部構成プロパティによって制御されます。例: application.propertiesで次のセクションを宣言できます。

spring.rabbitmq.host=localhost
spring.rabbitmq.port=5672
spring.rabbitmq.username=admin
spring.rabbitmq.password=secret

または、addresses 属性を使用して同じ接続を構成できます。

spring.rabbitmq.addresses=amqp://admin:[email protected](英語)  

ConnectionNameStrategy Beanがコンテキストに存在する場合、自動構成された ConnectionFactoryによって作成された接続に名前を付けるために自動的に使用されます。サポートされるオプションの詳細については、 RabbitProperties (GitHub) を参照してください。

詳細については、RabbitMQで使用されるプロトコルであるAMQPを理解する(英語) を参照してください。

13.2.2. メッセージを送る

Springの AmqpTemplate および AmqpAdmin は自動構成され、次の例に示すように、独自のBeanに直接オートワイヤーできます。

import org.springframework.amqp.core.AmqpAdmin;
import org.springframework.amqp.core.AmqpTemplate;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final AmqpAdmin amqpAdmin;
    private final AmqpTemplate amqpTemplate;

    @Autowired
    public MyBean(AmqpAdmin amqpAdmin, AmqpTemplate amqpTemplate) {
        this.amqpAdmin = amqpAdmin;
        this.amqpTemplate = amqpTemplate;
    }

    // ...

}
RabbitMessagingTemplate (英語) は、同様の方法で注入できます。 MessageConverter Beanが定義されている場合、自動構成された AmqpTemplateに自動的に関連付けられます。

必要に応じて、Beanとして定義されている org.springframework.amqp.core.Queue は、RabbitMQインスタンスで対応するキューを宣言するために自動的に使用されます。

操作を再試行するには、AmqpTemplate で再試行を有効にします(たとえば、ブローカー接続が失われた場合)。

spring.rabbitmq.template.retry.enabled=true
spring.rabbitmq.template.retry.initial-interval=2s

再試行はデフォルトで無効になっています。 RabbitRetryTemplateCustomizer Beanを宣言することにより、プログラムで RetryTemplate をカスタマイズすることもできます。

13.2.3. メッセージを受信する

Rabbitインフラストラクチャが存在する場合、@RabbitListener でBeanにアノテーションを付けてリスナーエンドポイントを作成できます。 RabbitListenerContainerFactory が定義されていない場合、デフォルトの SimpleRabbitListenerContainerFactory が自動的に構成され、spring.rabbitmq.listener.type プロパティを使用して直接コンテナーに切り替えることができます。 MessageConverter または MessageRecoverer Beanが定義されている場合、自動的にデフォルトファクトリに関連付けられます。

次のサンプルコンポーネントは、someQueue キューにリスナーエンドポイントを作成します。

@Component
public class MyBean {

    @RabbitListener(queues = "someQueue")
    public void processMessage(String content) {
        // ...
    }

}
詳細については、@EnableRabbitのJavadocを参照して(英語) ください。

さらに RabbitListenerContainerFactory インスタンスを作成する必要がある場合、またはデフォルトをオーバーライドする場合、Spring Bootは SimpleRabbitListenerContainerFactoryConfigurer および DirectRabbitListenerContainerFactoryConfigurer を提供します。これらを使用して、自動構成で使用されるファクトリーと同じ設定で SimpleRabbitListenerContainerFactory および DirectRabbitListenerContainerFactory を初期化できます。

選択したコンテナーの種類は関係ありません。これらの2つのBeanは、自動構成によって公開されます。

たとえば、次の構成クラスは、特定の MessageConverterを使用する別のファクトリーを公開します。

@Configuration(proxyBeanMethods = false)
static class RabbitConfiguration {

    @Bean
    public SimpleRabbitListenerContainerFactory myFactory(
            SimpleRabbitListenerContainerFactoryConfigurer configurer) {
        SimpleRabbitListenerContainerFactory factory =
                new SimpleRabbitListenerContainerFactory();
        configurer.configure(factory, connectionFactory);
        factory.setMessageConverter(myMessageConverter());
        return factory;
    }

}

次に、次のように、任意の @RabbitListenerアノテーション付きメソッドでファクトリーを使用できます。

@Component
public class MyBean {

    @RabbitListener(queues = "someQueue", containerFactory="myFactory")
    public void processMessage(String content) {
        // ...
    }

}

再試行を有効にして、リスナーが例外をスローする状況を処理できます。デフォルトでは、RejectAndDontRequeueRecoverer が使用されますが、独自の MessageRecoverer を定義できます。再試行が使い果たされると、ブローカーがそうするように構成されている場合、メッセージは拒否され、送達不能交換にドロップまたはルーティングされます。デフォルトでは、再試行は無効になっています。 RabbitRetryTemplateCustomizer Beanを宣言することにより、RetryTemplate をプログラムでカスタマイズすることもできます。

デフォルトでは、再試行が無効になっていて、リスナーが例外をスローした場合、配信は無期限に再試行されます。この動作は次の2つの方法で変更できます。defaultRequeueRejected プロパティを false に設定して再配信をゼロにするか、AmqpRejectAndDontRequeueException をスローしてメッセージを拒否することを通知します。後者は、再試行が有効で、配信試行の最大数に達したときに使用されるメカニズムです。

13.3. Apache Kafkaのサポート

Apache Kafka(英語) は、spring-kafka プロジェクトの自動構成を提供することによりサポートされます。

Kafka構成は、spring.kafka.*の外部構成プロパティによって制御されます。例: application.propertiesで次のセクションを宣言できます。

spring.kafka.bootstrap-servers=localhost:9092
spring.kafka.consumer.group-id=myGroup
起動時にトピックを作成するには、タイプ NewTopicのBeanを追加します。トピックが既に存在する場合、Beanは無視されます。

サポートされるオプションの詳細については、 KafkaProperties (GitHub) を参照してください。

13.3.1. メッセージを送る

Springの KafkaTemplate は自動構成されており、次の例に示すように、独自のBeanに直接オートワイヤーできます。

@Component
public class MyBean {

    private final KafkaTemplate kafkaTemplate;

    @Autowired
    public MyBean(KafkaTemplate kafkaTemplate) {
        this.kafkaTemplate = kafkaTemplate;
    }

    // ...

}
プロパティ spring.kafka.producer.transaction-id-prefix が定義されている場合、KafkaTransactionManager が自動的に構成されます。また、RecordMessageConverter Beanが定義されている場合、自動構成された KafkaTemplateに自動的に関連付けられます。

13.3.2. メッセージを受信する

Apache Kafkaインフラストラクチャが存在する場合、Beanに @KafkaListener のアノテーションを付けてリスナーエンドポイントを作成できます。 KafkaListenerContainerFactory が定義されていない場合は、spring.kafka.listener.*で定義されたキーを使用してデフォルトが自動的に構成されます。

次のコンポーネントは、someTopic トピックにリスナーエンドポイントを作成します。

@Component
public class MyBean {

    @KafkaListener(topics = "someTopic")
    public void processMessage(String content) {
        // ...
    }

}

KafkaTransactionManager Beanが定義されている場合、自動的にコンテナーファクトリに関連付けられます。同様に、ErrorHandler, AfterRollbackProcessor または ConsumerAwareRebalanceListener Beanが定義されている場合、自動的にデフォルトファクトリに関連付けられます。

リスナーのタイプに応じて、RecordMessageConverter または BatchMessageConverter Beanがデフォルトファクトリに関連付けられます。 RecordMessageConverter Beanのみがバッチリスナーに存在する場合、BatchMessageConverterにラップされます。

カスタム ChainedKafkaTransactionManager は、通常、自動構成された KafkaTransactionManager Beanを参照するため、@Primary とマークする必要があります。

13.3.3. Kafkaストリーム

Spring for Apache Kafkaは、StreamsBuilder オブジェクトを作成し、そのストリームのライフサイクルを管理するファクトリーBeanを提供します。Spring Bootは、kafka-streams がクラスパス上にあり、Kafkaストリームが @EnableKafkaStreams アノテーションを介して有効になっている限り、必要な KafkaStreamsConfiguration Beanを自動構成します。

Kafkaストリームを有効にすると、アプリケーションIDとブートストラップサーバーを設定する必要があります。前者は spring.kafka.streams.application-idを使用して構成でき、設定されていない場合はデフォルトで spring.application.name になります。後者は、グローバルに設定することも、ストリームに対してのみ具体的にオーバーライドすることもできます。

専用プロパティを使用して、いくつかの追加プロパティを利用できます。他の任意のKafkaプロパティは、spring.kafka.streams.properties 名前空間を使用して設定できます。詳細については、Kafkaの追加プロパティも参照してください。

ファクトリーBeanを使用するには、次の例に示すように、StreamsBuilder@Bean に接続するだけです。

@Configuration(proxyBeanMethods = false)
@EnableKafkaStreams
public static class KafkaStreamsExampleConfiguration {

    @Bean
    public KStream<Integer, String> kStream(StreamsBuilder streamsBuilder) {
        KStream<Integer, String> stream = streamsBuilder.stream("ks1In");
        stream.map((k, v) -> new KeyValue<>(k, v.toUpperCase())).to("ks1Out",
                Produced.with(Serdes.Integer(), new JsonSerde<>()));
        return stream;
    }

}

デフォルトでは、作成する StreamBuilder オブジェクトによって管理されるストリームは自動的に開始されます。 spring.kafka.streams.auto-startup プロパティを使用して、この動作をカスタマイズできます。

13.3.4. Kafkaの追加プロパティ

自動構成でサポートされるプロパティはappendix-application-properties.htmlに示されています。ほとんどの場合、これらのプロパティ(ハイフン付きまたはキャメルケース)は、Apache Kafkaドット付きプロパティに直接マップされることに注意してください。詳細については、Apache Kafkaのドキュメントを参照してください。

これらのプロパティの最初のいくつかはすべてのコンポーネント(プロデューサー、コンシューマー、管理者、およびストリーム)に適用されますが、異なる値を使用する場合はコンポーネントレベルで指定できます。Apache Kafkaは、重要度が高、中、または低のプロパティを指定します。Spring Boot自動構成は、すべての重要度の高いプロパティ、一部の選択されたMEDIUMおよびLOWプロパティ、およびデフォルト値を持たないプロパティをサポートします。

Kafkaでサポートされているプロパティのサブセットのみが、KafkaProperties クラスから直接利用できます。直接サポートされていない追加のプロパティを使用してプロデューサーまたはコンシューマーを構成する場合は、次のプロパティを使用します。

spring.kafka.properties.prop.one=first
spring.kafka.admin.properties.prop.two=second
spring.kafka.consumer.properties.prop.three=third
spring.kafka.producer.properties.prop.four=fourth
spring.kafka.streams.properties.prop.five=fifth

これにより、共通の prop.one Kafkaプロパティが first (プロデューサー、コンシューマー、および管理者に適用)、prop.two adminプロパティが secondに、prop.three コンシューマープロパティが thirdに、prop.four プロデューサープロパティが fourth に、prop.five ストリームプロパティが fifthに設定されます。

Spring Kafka JsonDeserializer は、次のように構成することもできます。

spring.kafka.consumer.value-deserializer=org.springframework.kafka.support.serializer.JsonDeserializer
spring.kafka.consumer.properties.spring.json.value.default.type=com.example.Invoice
spring.kafka.consumer.properties.spring.json.trusted.packages=com.example,org.acme

同様に、型情報をヘッダーで送信する JsonSerializer のデフォルトの動作を無効にできます。

spring.kafka.producer.value-serializer=org.springframework.kafka.support.serializer.JsonSerializer
spring.kafka.producer.properties.spring.json.add.type.headers=false
この方法で設定されたプロパティは、Spring Bootが明示的にサポートする構成アイテムをオーバーライドします。

13.3.5. 組み込みKafkaを使用したテスト

Spring for Apache Kafkaは、組み込みApache Kafkaブローカーを使用してプロジェクトをテストする便利な方法を提供します。この機能を使用するには、spring-kafka-test モジュールの @EmbeddedKafka でテストクラスにアノテーションを付けます。詳細については、Spring for Apache Kafka リファレンスマニュアル(英語) を参照してください。

前述の組み込みApache KafkaブローカーでSpring Bootの自動構成を機能させるには、組み込みブローカーアドレスのシステムプロパティ( EmbeddedKafkaBrokerが入力)をApache KafkaのSpring Boot構成プロパティに再マッピングする必要があります。それにはいくつかの方法があります。

  • 組み込みブローカーアドレスをテストクラスの spring.kafka.bootstrap-servers にマップするシステムプロパティを提供します。

static {
    System.setProperty(EmbeddedKafkaBroker.BROKER_LIST_PROPERTY, "spring.kafka.bootstrap-servers");
}
  • @EmbeddedKafka アノテーションでプロパティ名を構成します。

@EmbeddedKafka(topics = "someTopic",
        bootstrapServersProperty = "spring.kafka.bootstrap-servers")
  • 構成プロパティでプレースホルダーを使用します。

spring.kafka.bootstrap-servers=${spring.embedded.kafka.brokers}

14. RestTemplateを使用したRESTサービスの呼び出し

アプリケーションからリモート RESTサービスを呼び出す必要がある場合は、Spring Frameworkの RestTemplate (Javadoc) クラスを使用できます。 RestTemplate インスタンスは使用する前にカスタマイズする必要があることが多いため、Spring Bootは単一の自動構成 RestTemplate Beanを提供しません。ただし、必要に応じて RestTemplate インスタンスを作成するために使用できる RestTemplateBuilderを自動構成します。自動構成された RestTemplateBuilder は、実用的な HttpMessageConvertersRestTemplate インスタンスに確実に適用されるようにします。

次のコードは典型的な例を示しています。

@Service
public class MyService {

    private final RestTemplate restTemplate;

    public MyService(RestTemplateBuilder restTemplateBuilder) {
        this.restTemplate = restTemplateBuilder.build();
    }

    public Details someRestCall(String name) {
        return this.restTemplate.getForObject("/{name}/details", Details.class, name);
    }

}
RestTemplateBuilder には、RestTemplateをすばやく構成するために使用できる多くの便利なメソッドが含まれています。例:BASIC認証サポートを追加するには、builder.basicAuthentication("user", "password").build()を使用できます。

14.1. RestTemplateのカスタマイズ

RestTemplate カスタマイズには、カスタマイズの適用範囲に応じて3つの主なアプローチがあります。

カスタマイズの範囲をできる限り狭くするには、自動構成された RestTemplateBuilder を挿入し、必要に応じてそのメソッドを呼び出します。各メソッド呼び出しは新しい RestTemplateBuilder インスタンスを返すため、カスタマイズはこのビルダーの使用にのみ影響します。

アプリケーション全体で追加のカスタマイズを行うには、RestTemplateCustomizer Beanを使用します。このようなBeanはすべて、自動構成された RestTemplateBuilder に自動的に登録され、それを使用して作成されたすべてのテンプレートに適用されます。

次の例は、192.168.0.5を除くすべてのホストに対してプロキシの使用を構成するカスタマイザーを示しています。

static class ProxyCustomizer implements RestTemplateCustomizer {

    @Override
    public void customize(RestTemplate restTemplate) {
        HttpHost proxy = new HttpHost("proxy.example.com");
        HttpClient httpClient = HttpClientBuilder.create().setRoutePlanner(new DefaultProxyRoutePlanner(proxy) {

            @Override
            public HttpHost determineProxy(HttpHost target, HttpRequest request, HttpContext context)
                    throws HttpException {
                if (target.getHostName().equals("192.168.0.5")) {
                    return null;
                }
                return super.determineProxy(target, request, context);
            }

        }).build();
        restTemplate.setRequestFactory(new HttpComponentsClientHttpRequestFactory(httpClient));
    }

}

最後に、最も極端な(そしてめったに使用されない)オプションは、独自の RestTemplateBuilder Beanを作成することです。これにより、RestTemplateBuilder の自動構成がオフになり、RestTemplateCustomizer Beanが使用されなくなります。

15. WebClientを使用したRESTサービスの呼び出し

クラスパスにSpring WebFluxがある場合、WebClient を使用してリモート RESTサービスを呼び出すこともできます。 RestTemplateと比較して、このクライアントはより機能的な感触を持ち、完全に反応的です。 WebClient の詳細については、Spring Frameworkドキュメントの専用のセクションを参照してください。

Spring Bootは、WebClient.Builder を作成して事前設定します。コンポーネントに注入し、WebClient インスタンスを作成するために使用することを強くお勧めします。Spring Bootは、そのビルダーを構成して、HTTPリソースを共有し、コーデックのセットアップをサーバーのものと同じ方法で反映します(WebFlux HTTPコーデックの自動構成を参照)。

次のコードは典型的な例を示しています。

@Service
public class MyService {

    private final WebClient webClient;

    public MyService(WebClient.Builder webClientBuilder) {
        this.webClient = webClientBuilder.baseUrl("https://example.org").build();
    }

    public Mono<Details> someRestCall(String name) {
        return this.webClient.get().uri("/{name}/details", name)
                        .retrieve().bodyToMono(Details.class);
    }

}

15.1. WebClientランタイム

Spring Bootは、アプリケーションクラスパスで利用可能なライブラリに応じて、どの ClientHttpConnector を使用して WebClientを駆動するかを自動検出します。今のところ、Reactor NettyおよびJetty RSクライアントがサポートされています。

spring-boot-starter-webflux スターターは、デフォルトで io.projectreactor.netty:reactor-netty に依存しており、サーバーとクライアントの両方の実装をもたらします。代わりにJettyをリアクティブサーバーとして使用することを選択した場合、Jetty Reactive HTTPクライアントライブラリ org.eclipse.jetty:jetty-reactive-httpclientへの依存関係を追加する必要があります。サーバーとクライアントに同じテクノロジーを使用すると、クライアントとサーバー間でHTTPリソースが自動的に共有されるため、利点があります。

開発者は、カスタム ReactorResourceFactory または JettyResourceFactory Beanを提供することにより、JettyおよびReactor Nettyのリソース構成をオーバーライドできます。これは、クライアントとサーバーの両方に適用されます。

クライアントのその選択をオーバーライドする場合は、独自の ClientHttpConnector Beanを定義し、クライアント構成を完全に制御できます。

15.2. WebClientのカスタマイズ

WebClient カスタマイズには、カスタマイズの適用範囲に応じて3つの主なアプローチがあります。

カスタマイズの範囲をできる限り狭くするには、自動構成された WebClient.Builder を挿入し、必要に応じてそのメソッドを呼び出します。 WebClient.Builder インスタンスはステートフルです:ビルダーでの変更は、その後作成されたすべてのクライアントに反映されます。同じビルダーで複数のクライアントを作成する場合は、WebClient.Builder other = builder.clone();でビルダーを複製することも検討できます。

アプリケーション全体で、すべての WebClient.Builder インスタンスに追加のカスタマイズを行うには、WebClientCustomizer Beanを宣言し、注入の時点で WebClient.Builder をローカルに変更します。

最後に、元のAPIにフォールバックして WebClient.create()を使用できます。その場合、自動構成または WebClientCustomizer は適用されません。

16. 検証

Bean検証1.1でサポートされるメソッド検証機能は、JSR-303実装(Hibernateバリデーターなど)がクラスパス上にある限り、自動的に有効になります。これにより、Beanメソッドに、パラメーターおよび/または戻り値の javax.validation 制約をアノテーションできます。このようなアノテーション付きメソッドを持つターゲットクラスには、インライン制約アノテーションを検索するメソッドの型レベルで @Validated アノテーションを付ける必要があります。

たとえば、次のサービスは最初の引数の検証をトリガーし、そのサイズが8〜10であることを確認します。

@Service
@Validated
public class MyBean {

    public Archive findByCodeAndAuthor(@Size(min = 8, max = 10) String code,
            Author author) {
        ...
    }

}

17. メール送信

Spring Frameworkは、JavaMailSender インターフェースを使用してメールを送信するための簡単な抽象化を提供し、Spring Bootはスターターモジュールと同様に自動構成を提供します。

JavaMailSenderの使用方法の詳細については、リファレンスドキュメントを参照してください。

spring.mail.host および関連するライブラリ( spring-boot-starter-mailで定義されている)が使用可能な場合、存在しない場合はデフォルトの JavaMailSender が作成されます。送信者は、spring.mail 名前空間の構成アイテムによってさらにカスタマイズできます。詳細については、 MailProperties (GitHub) を参照してください。

特に、特定のデフォルトのタイムアウト値は無限であり、次の例に示すように、応答しないメールサーバーによってスレッドがブロックされるのを避けるために、これを変更することができます。

spring.mail.properties.mail.smtp.connectiontimeout=5000
spring.mail.properties.mail.smtp.timeout=3000
spring.mail.properties.mail.smtp.writetimeout=5000

JNDIの既存の Session を使用して JavaMailSender を構成することもできます。

spring.mail.jndi-name=mail/Session

jndi-name が設定されると、他のすべてのセッション関連の設定よりも優先されます。

18. JTAを使用した分散トランザクション

Spring Bootは、Atomikos(英語) またはBitronix(GitHub) 組み込みトランザクションマネージャーのいずれかを使用して、複数のXAリソースにわたる分散JTAトランザクションをサポートします。適切なJava EE Application Serverにデプロイする場合、JTAトランザクションもサポートされます。

JTA環境が検出されると、Springの JtaTransactionManager を使用してトランザクションが管理されます。自動構成されたJMS、DataSource、およびJPA Beanは、XAトランザクションをサポートするためにアップグレードされます。 @Transactionalなどの標準的なSpringイディオムを使用して、分散トランザクションに参加できます。JTA環境内でローカルトランザクションを使用する場合は、spring.jta.enabled プロパティを false に設定して、JTA自動構成を無効にすることができます。

18.1. Atomikos Transaction Managerを使用する

Atomikos(英語) は、Spring Bootアプリケーションに組み込むことができる一般的なオープンソーストランザクションマネージャーです。 spring-boot-starter-jta-atomikos スターターを使用して、適切なAtomikosライブラリをプルできます。Spring Bootは、Atomikosを自動構成し、適切な depends-on 設定がSpring Beanに適用され、起動とシャットダウンの順序が正しくなるようにします。

デフォルトでは、Atomikosトランザクションログは、アプリケーションのホームディレクトリ(アプリケーションjarファイルが存在するディレクトリ)の transaction-logs ディレクトリに書き込まれます。 application.properties ファイルで spring.jta.log-dir プロパティを設定することにより、このディレクトリの場所をカスタマイズできます。 spring.jta.atomikos.properties で始まるプロパティは、Atomikos UserTransactionServiceImpのカスタマイズにも使用できます。詳細については、 AtomikosProperties Javadocを参照してください。

複数のトランザクションマネージャーが同じリソースマネージャーを安全に調整できるようにするには、各Atomikosインスタンスに一意のIDを設定する必要があります。デフォルトでは、このIDはAtomikosが実行されているマシンのIPアドレスです。本番環境での一意性を確保するには、アプリケーションのインスタンスごとに異なる値を使用して spring.jta.transaction-manager-id プロパティを構成する必要があります。

18.2. Bitronix Transaction Managerの使用

Bitronix(GitHub) は、人気のあるオープンソースJTAトランザクションマネージャーの実装です。 spring-boot-starter-jta-bitronix スターターを使用して、適切なBitronix依存関係をプロジェクトに追加できます。Atomikosと同様に、Spring BootはBitronixを自動的に構成し、Beanを後処理して、起動とシャットダウンの順序が正しいことを確認します。

デフォルトでは、Bitronixトランザクションログファイル(part1.btm および part2.btm)は、アプリケーションホームディレクトリの transaction-logs ディレクトリに書き込まれます。 spring.jta.log-dir プロパティを設定することにより、このディレクトリの場所をカスタマイズできます。 spring.jta.bitronix.properties で始まるプロパティも bitronix.tm.Configuration Beanにバインドされており、完全なカスタマイズが可能です。詳細については、Bitronixのドキュメント(GitHub) を参照してください。

複数のトランザクションマネージャーが同じリソースマネージャーを安全に調整できるようにするには、各Bitronixインスタンスを一意のIDで構成する必要があります。デフォルトでは、このIDはBitronixが実行されているマシンのIPアドレスです。本番環境での一意性を確保するには、アプリケーションのインスタンスごとに異なる値を使用して spring.jta.transaction-manager-id プロパティを構成する必要があります。

18.3. Java EE Managed Transaction Managerの使用

Spring Bootアプリケーションを war または ear ファイルとしてパッケージ化し、それをJava EEアプリケーションサーバーにデプロイする場合、アプリケーションサーバーの組み込みトランザクションマネージャーを使用できます。Spring Bootは、一般的なJNDIロケーション(java:comp/UserTransaction, java:comp/TransactionManagerなど)を調べることにより、トランザクションマネージャーの自動構成を試みます。アプリケーションサーバーが提供するトランザクションサービスを使用する場合は、通常、すべてのリソースがサーバーによって管理され、JNDI経由で公開されるようにすることも必要です。Spring Bootは、JNDIパス(java:/JmsXA または java:/XAConnectionFactory)で ConnectionFactory を探すことでJMSの自動構成を試みます。 spring.datasource.jndi-name プロパティを使用して DataSourceを構成できます。

18.4. XAと非XA JMS接続の混在

JTAを使用する場合、プライマリJMS ConnectionFactory BeanはXA対応であり、分散トランザクションに参加します。状況によっては、非XA ConnectionFactoryを使用して特定のJMSメッセージを処理したい場合があります。例:JMS処理ロジックはXAタイムアウトよりも時間がかかる場合があります。

非XA ConnectionFactoryを使用する場合は、@Primary jmsConnectionFactory Beanではなく、nonXaJmsConnectionFactory Beanを注入できます。一貫性を保つため、Beanエイリアス xaJmsConnectionFactoryを使用して jmsConnectionFactory Beanも提供されます。

次の例は、ConnectionFactory インスタンスを注入する方法を示しています。

// Inject the primary (XA aware) ConnectionFactory
@Autowired
private ConnectionFactory defaultConnectionFactory;

// Inject the XA aware ConnectionFactory (uses the alias and injects the same as above)
@Autowired
@Qualifier("xaJmsConnectionFactory")
private ConnectionFactory xaConnectionFactory;

// Inject the non-XA aware ConnectionFactory
@Autowired
@Qualifier("nonXaJmsConnectionFactory")
private ConnectionFactory nonXaConnectionFactory;

18.5. 代替の組み込みトランザクションマネージャーのサポート

XAConnectionFactoryWrapper (GitHub) および XADataSourceWrapper (GitHub) インターフェースを使用して、代替の組み込みトランザクションマネージャーをサポートできます。インターフェースは、XAConnectionFactory および XADataSource Beanをラップし、通常の ConnectionFactory および DataSource Beanとして公開し、分散トランザクションに透過的に登録します。 JtaTransactionManager Beanおよび適切なXAラッパーBeanが ApplicationContext内に登録されている場合、DataSourceおよびJMS自動構成はJTAバリアントを使用します。

BitronixXAConnectionFactoryWrapper(GitHub) およびBitronixXADataSourceWrapper(GitHub) は、XAラッパーの作成方法の良い例を提供します。

19. Hazelcast

Hazelcast(英語) がクラスパス上にあり、適切な構成が見つかった場合、Spring Bootは、アプリケーションに挿入できる HazelcastInstance を自動構成します。

com.hazelcast.config.Config Beanを定義すると、Spring Bootはそれを使用します。構成がインスタンス名を定義している場合、Spring Bootは新しいインスタンスを作成するのではなく、既存のインスタンスを見つけようとします。

次の例に示すように、構成で使用するHazelcast構成ファイルを指定することもできます。

spring.hazelcast.config=classpath:config/my-hazelcast.xml

それ以外の場合、Spring Bootは、デフォルトの場所(作業ディレクトリまたはクラスパスのルートにある hazelcast.xml、または同じ場所にある .yaml の対応する場所)からHazelcast構成を見つけようとします。 hazelcast.config システムプロパティが設定されているかどうかも確認します。詳細については、Hazelcastのドキュメント(英語) を参照してください。

hazelcast-client がクラスパスに存在する場合、Spring Bootは最初に次の構成オプションを確認してクライアントを作成しようとします。

  • com.hazelcast.client.config.ClientConfig Beanの存在。

  • spring.hazelcast.config プロパティによって定義された構成ファイル。

  • hazelcast.client.config システムプロパティの存在。

  • 作業ディレクトリまたはクラスパスのルートにある hazelcast-client.xml

  • 作業ディレクトリまたはクラスパスのルートにある hazelcast-client.yaml

Spring Bootには、Hazelcastの明示的なキャッシュサポートもあります。キャッシュが有効になっている場合、HazelcastInstanceCacheManager 実装に自動的にラップされます。

20. Quartzスケジューラー

Spring Bootは、spring-boot-starter-quartz 「スターター」を含む、Quartzスケジューラー(英語) を操作するためのいくつかの便利な機能を提供します。Quartzが使用可能な場合、Scheduler は( SchedulerFactoryBean 抽象化により)自動構成されます。

次のタイプのBeanが自動的に取得され、Schedulerに関連付けられます。

  • JobDetail : 特定のジョブを定義します。 JobDetail インスタンスは、JobBuilder APIを使用して構築できます。

  • Calendar .

  • Trigger : 特定のジョブがいつトリガーされるかを定義します。

デフォルトでは、インメモリ JobStore が使用されます。ただし、次の例に示すように、DataSource Beanがアプリケーションで利用可能であり、それに応じて spring.quartz.job-store-type プロパティが構成されている場合、JDBCベースのストアを構成できます。

spring.quartz.job-store-type=jdbc

JDBCストアを使用すると、次の例に示すように、起動時にスキーマを初期化できます。

spring.quartz.jdbc.initialize-schema=always
デフォルトでは、Quartzライブラリで提供される標準スクリプトを使用して、データベースが検出および初期化されます。これらのスクリプトは既存のテーブルを削除し、再起動するたびにすべてのトリガーを削除します。 spring.quartz.jdbc.schema プロパティを設定して、カスタムスクリプトを提供することもできます。

Quartzにアプリケーションのメイン DataSource以外の DataSource を使用させるには、DataSource Beanを宣言し、@Bean メソッドに @QuartzDataSourceでアノテーションを付けます。これにより、SchedulerFactoryBean とスキーマの初期化の両方でQuartz固有の DataSource が使用されるようになります。

デフォルトでは、構成によって作成されたジョブは、永続ジョブストアから読み取られた登録済みのジョブを上書きしません。既存のジョブ定義の上書きを有効にするには、spring.quartz.overwrite-existing-jobs プロパティを設定します。

Quartzスケジューラー構成は、spring.quartz プロパティおよび SchedulerFactoryBeanCustomizer Beanを使用してカスタマイズできます。これにより、プログラムによる SchedulerFactoryBean のカスタマイズが可能になります。 spring.quartz.properties.*を使用して、高度なQuartz構成プロパティをカスタマイズできます。

特に、Quartzは spring.quartz.propertiesを介してスケジューラーを構成する方法を提供するため、Executor Beanはスケジューラーに関連付けられていません。タスクエグゼキューターをカスタマイズする必要がある場合は、SchedulerFactoryBeanCustomizerの実装を検討してください。

ジョブは、setterを定義してデータマッププロパティを挿入できます。次の例に示すように、通常のBeanも同様の方法で注入できます。

public class SampleJob extends QuartzJobBean {

    private MyService myService;

    private String name;

    // Inject "MyService" bean
    public void setMyService(MyService myService) { ... }

    // Inject the "name" job data property
    public void setName(String name) { ... }

    @Override
    protected void executeInternal(JobExecutionContext context)
            throws JobExecutionException {
        ...
    }

}

21. タスクの実行とスケジューリング

コンテキストに Executor Beanがない場合、Spring Bootは、非同期タスク実行(@EnableAsync)およびSpring MVC非同期要求処理に自動的に関連付けることができる実用的なデフォルトで ThreadPoolTaskExecutor を自動構成します。

コンテキストでカスタム Executor を定義した場合、通常のタスク実行(つまり @EnableAsync)はそれを透過的に使用しますが、AsyncTaskExecutor 実装( applicationTaskExecutorという名前)が必要なため、Spring MVCサポートは構成されません。ターゲットの配置に応じて、ExecutorThreadPoolTaskExecutor に変更するか、カスタム Executorをラップする ThreadPoolTaskExecutorAsyncConfigurer の両方を定義できます。

自動構成された TaskExecutorBuilder を使用すると、自動構成がデフォルトで行うことを再現するインスタンスを簡単に作成できます。

スレッドプールは、負荷に応じて拡大および縮小できる8つのコアスレッドを使用します。これらのデフォルト設定は、次の例に示すように、spring.task.execution 名前空間を使用して微調整できます。

spring.task.execution.pool.max-size=16
spring.task.execution.pool.queue-capacity=100
spring.task.execution.pool.keep-alive=10s

これにより、キューがいっぱい(100タスク)になったときにスレッドプールが最大16スレッドに増加するように、スレッドプールが制限キューを使用するように変更されます。プールの縮小は、スレッドが10秒間(デフォルトでは60秒ではなく)アイドル状態のときに回収されるため、より積極的です。

スケジュールされたタスクの実行(@EnableScheduling)に関連付ける必要がある場合は、ThreadPoolTaskScheduler を自動構成することもできます。スレッドプールはデフォルトで1つのスレッドを使用し、これらの設定は spring.task.scheduling 名前空間を使用して微調整できます。

カスタムexecutorまたはスケジューラーを作成する必要がある場合、コンテキストで TaskExecutorBuilder Beanと TaskSchedulerBuilder Beanの両方が使用可能になります。

22. Spring Integration

Spring Bootは、spring-boot-starter-integration 「スターター」を含む、Spring Integrationで作業するためのいくつかの便利な機能を提供します。Spring Integrationは、メッセージング、およびHTTP、TCPなどのその他のトランスポートを抽象化します。Spring Integrationがクラスパスで使用可能な場合、@EnableIntegration アノテーションを介して初期化されます。

Spring Bootは、追加のSpring Integrationモジュールの存在によってトリガーされるいくつかの機能も構成します。 spring-integration-jmx もクラスパス上にある場合、メッセージ処理統計はJMXを介して公開されます。 spring-integration-jdbc が利用可能な場合、次の行に示すように、起動時にデフォルトのデータベーススキーマを作成できます。

spring.integration.jdbc.initialize-schema=always

詳細については、 IntegrationAutoConfiguration (GitHub) および IntegrationProperties (GitHub) クラスを参照してください。

デフォルトでは、Micrometer meterRegistry Beanが存在する場合、Spring IntegrationメトリックはMicrometerによって管理されます。レガシーSpring Integrationメトリックを使用する場合は、DefaultMetricsFactory Beanをアプリケーションコンテキストに追加します。

23. Spring Session

Spring Bootは、広範囲のデータストアにSpring Session自動構成を提供します。サーブレットWebアプリケーションを構築する場合、次のストアを自動構成できます。

  • JDBC

  • Redis

  • Hazelcast

  • MongoDB

リアクティブWebアプリケーションを構築する場合、次のストアを自動構成できます。

  • Redis

  • MongoDB

単一のSpring Sessionモジュールがクラスパスに存在する場合、Spring Bootはそのストア実装を自動的に使用します。実装が複数ある場合は、セッションの保存に使用する StoreType (GitHub) を選択する必要があります。たとえば、JDBCをバックエンドストアとして使用するには、次のようにアプリケーションを構成できます。

spring.session.store-type=jdbc
store-typenoneに設定することにより、Spring Sessionを無効にできます。

各ストアには特定の追加設定があります。たとえば、次の例に示すように、JDBCストアのテーブルの名前をカスタマイズできます。

spring.session.jdbc.table-name=SESSIONS

セッションのタイムアウトを設定するには、spring.session.timeout プロパティを使用できます。そのプロパティが設定されていない場合、自動構成は server.servlet.session.timeoutの値にフォールバックします。

24. JMXを介した監視と管理

Java Management Extensions(JMX)は、アプリケーションを監視および管理するための標準メカニズムを提供します。Spring Bootは、IDが mbeanServerのBeanとして最適な MBeanServer を公開します。Spring JMXアノテーション(@ManagedResource, @ManagedAttribute、または @ManagedOperation)でアノテーションが付けられたBeanはすべて公開されます。

プラットフォームが標準の MBeanServerを提供する場合、Spring Bootはそれを使用し、必要に応じてデフォルトでVM MBeanServer を使用します。すべてが失敗すると、新しい MBeanServer が作成されます。

詳細については、 JmxAutoConfiguration (GitHub) クラスを参照してください。

25. テスト

Spring Bootは、アプリケーションをテストするときに役立つ多くのユーティリティとアノテーションを提供します。テストサポートは2つのモジュールによって提供されます。spring-boot-test にはコアアイテムが含まれ、spring-boot-test-autoconfigure はテストの自動構成をサポートします。

ほとんどの開発者は、Spring BootテストモジュールとJUnit Jupiter、AssertJ、Hamcrest、およびその他の便利なライブラリの両方をインポートする spring-boot-starter-test “ Starter”を使用します。

また、スターターはVintageエンジンを提供するため、JUnit 4とJUnit 5の両方のテストを実行できます。テストをJUnit 5に移行した場合、次の例に示すように、JUnit 4サポートを除外する必要があります。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
    <exclusions>
        <exclusion>
            <groupId>org.junit.vintage</groupId>
            <artifactId>junit-vintage-engine</artifactId>
        </exclusion>
    </exclusions>
</dependency>

25.1. テスト範囲の依存関係

spring-boot-starter-test 「スターター」( test scope内)には、以下の提供ライブラリが含まれています。

  • JUnit 5(英語) (JUnit 4との後方互換性のためのVintageエンジンを含む):Javaアプリケーションの単体テストのための事実上の標準。

  • SpringテストおよびSpring Bootテスト:Spring Bootアプリケーションのユーティリティおよび統合テストのサポート。

  • AssertJ(英語) : 流れるようなアサーションライブラリ。

  • Hamcrest(GitHub) : マッチャーオブジェクトのライブラリ(制約または述語として知られる)。

  • Mockito(英語) : Javaモックフレームワーク。

  • JSONassert(GitHub) : JSONのアサーションライブラリ。

  • JsonPath(GitHub) : JSONのXPath。

通常、これらの一般的なライブラリは、テストを作成するときに役立つことがわかります。これらのライブラリがニーズに合わない場合は、独自のテスト依存関係を追加できます。

25.2. Springアプリケーションのテスト

依存性注入の主な利点の1つは、コードを単体テストしやすくすることです。Springを使用しなくても、new 演算子を使用してオブジェクトをインスタンス化できます。実際の依存関係の代わりにモックオブジェクトを使用することもできます

多くの場合、単体テストを超えて統合テストを開始する必要があります(Spring ApplicationContextを使用)。アプリケーションのデプロイを必要とせずに、または他のインフラストラクチャに接続する必要なく、統合テストを実行できると便利です。

Spring Frameworkには、このような統合テスト専用のテストモジュールが含まれています。 org.springframework:spring-test に直接依存関係を宣言するか、spring-boot-starter-test 「スターター」を使用して依存関係を一時的にプルできます。

spring-test モジュールを使用したことがない場合は、Spring Frameworkリファレンスドキュメントの関連セクションを読むことから始めてください。

25.3. Spring Bootアプリケーションのテスト

Spring BootアプリケーションはSpring ApplicationContextであるため、vanilla Springコンテキストで通常行うことを超えてテストするために特別なことを行う必要はありません。

Spring Bootの外部プロパティ、ロギング、およびその他の機能は、SpringApplication を使用して作成する場合にのみ、デフォルトでコンテキストにインストールされます。

Spring Bootは @SpringBootTest アノテーションを提供します。これは、Spring Boot機能が必要な場合に標準の spring-test @ContextConfiguration アノテーションの代替として使用できます。アノテーションは、SpringApplicationを使用してテストで使用される ApplicationContext を作成することにより機能します@SpringBootTest に加えて、アプリケーションのより具体的なスライスをテストするために、他の多くのアノテーションも提供されています。

JUnit 4を使用している場合は、@RunWith(SpringRunner.class) もテストに追加することを忘れないでください。追加しないと、アノテーションは無視されます。JUnit 5を使用している場合、同等の @ExtendWith(SpringExtension.class)@SpringBootTest として追加する必要はなく、他の @…Test アノテーションには既にアノテーションが付けられています。

デフォルトでは、@SpringBootTest はサーバーを起動しません。 @SpringBootTestwebEnvironment 属性を使用して、テストの実行方法をさらに絞り込むことができます。

  • MOCK(デフォルト):Web ApplicationContext をロードし、モックWeb環境を提供します。このアノテーションを使用すると、組み込みサーバーは起動しません。Web環境がクラスパスで利用できない場合、このモードは通常の非Web ApplicationContextの作成に透過的にフォールバックします。Webアプリケーションのモックベースのテストのために、 @AutoConfigureMockMvc または @AutoConfigureWebTestClient と組み合わせて使用できます。

  • RANDOM_PORT : WebServerApplicationContext をロードし、実際のWeb環境を提供します。組み込みサーバーが起動され、ランダムポートでリッスンします。

  • DEFINED_PORT : WebServerApplicationContext をロードし、実際のWeb環境を提供します。組み込みサーバーが開始され、定義済みのポート( application.propertiesから)またはデフォルトのポート 8080でlistenします。

  • NONE : SpringApplication を使用して ApplicationContext をロードしますが Web環境(モックまたはその他)を提供しません。

テストが @Transactionalの場合、デフォルトで各テストメソッドの最後にトランザクションをロールバックします。ただし、RANDOM_PORT または DEFINED_PORT のいずれかでこの配置を使用すると、実際のサーブレット環境が暗黙的に提供されるため、HTTPクライアントとサーバーは別々のスレッドで、別々のトランザクションで実行されます。この場合、サーバーで開始されたトランザクションはロールバックしません。
@SpringBootTestwebEnvironment = WebEnvironment.RANDOM_PORT は、アプリケーションが管理サーバーに異なるポートを使用している場合、別のランダムポートで管理サーバーを起動します。

25.3.1. Webアプリケーションタイプの検出

Spring MVCが利用可能な場合、通常のMVCベースのアプリケーションコンテキストが設定されます。SpringとWebFluxしかない場合は、それを検出し、代わりにWebFluxベースのアプリケーションコンテキストを構成します。

両方が存在する場合、Spring MVCが優先されます。このシナリオでリアクティブWebアプリケーションをテストする場合は、spring.main.web-application-type プロパティを設定する必要があります。

@SpringBootTest(properties = "spring.main.web-application-type=reactive")
class MyWebFluxTests { ... }

25.3.2. テスト構成の検出

Springテストフレームワークに精通している場合、どのSpring @Configuration をロードするかを指定するために @ContextConfiguration(classes=…​) を使用することに慣れているかもしれません。あるいは、テスト内でネストされた @Configuration クラスを頻繁に使用した可能性があります。

Spring Bootアプリケーションをテストする場合、これは多くの場合必要ありません。Spring Bootの @*Test アノテーションは、明示的に定義しない限り、プライマリ設定を自動的に検索します。

検索アルゴリズムは、@SpringBootApplication または @SpringBootConfigurationアノテーションが付けられたクラスを見つけるまで、テストを含むパッケージから機能します。実用的なメソッドでコードを構造化する限り、通常、メイン構成が見つかります。

@SpringBootApplication の基礎となるコンポーネントスキャン構成は、スライシングが期待どおりに機能することを確認するために使用される除外フィルターを定義します。 @SpringBootApplicationアノテーション付きクラスで明示的な @ComponentScan ディレクティブを使用している場合、これらのフィルターが無効になることに注意してください。スライスを使用している場合は、再度定義する必要があります。

プライマリ設定をカスタマイズする場合は、ネストされた @TestConfiguration クラスを使用できます。アプリケーションのプライマリ設定の代わりに使用されるネストされた @Configuration クラスとは異なり、ネストされた @TestConfiguration クラスはアプリケーションのプライマリ設定に加えて使用されます。

Springのテストフレームワークは、テスト間のアプリケーションコンテキストをキャッシュします。テストが同じ構成を共有している限り(検出方法に関係なく)、コンテキストをロードする潜在的に時間のかかるプロセスは1回しか発生しません。

25.3.3. テスト構成の除外

アプリケーションがコンポーネントスキャンを使用している場合(たとえば、@SpringBootApplication または @ComponentScanを使用している場合)、特定のテスト用に作成した最上位の構成クラスが誤ってどこでも取得される可能性があります。

前に見たように、@TestConfiguration をテストの内部クラスで使用して、プライマリ構成をカスタマイズできます。 @TestConfiguration は、最上位クラスに配置されると、src/test/java のクラスをスキャンで取得しないことを示します。その後、次の例に示すように、必要な場所にそのクラスを明示的にインポートできます。

@SpringBootTest
@Import(MyTestsConfiguration.class)
class MyTests {

    @Test
    void exampleTest() {
        ...
    }

}
@ComponentScan を直接使用する場合(つまり、@SpringBootApplicationを使用しない場合)、TypeExcludeFilter を登録する必要があります。詳細については、Javadocを参照してください。

25.3.4. アプリケーション引数の使用

アプリケーションで引数が必要な場合は、args 属性を使用して @SpringBootTest引数を注入させることができます。

@SpringBootTest(args = "--app.test=one")
class ApplicationArgumentsExampleTests {

    @Test
    void applicationArgumentsPopulated(@Autowired ApplicationArguments args) {
        assertThat(args.getOptionNames()).containsOnly("app.test");
        assertThat(args.getOptionValues("app.test")).containsOnly("one");
    }

}

25.3.5. モック環境でのテスト

デフォルトでは、@SpringBootTest はサーバーを起動しません。このモック環境に対してテストするWebエンドポイントがある場合、次の例に示すように MockMvc を追加で構成できます。

import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@SpringBootTest
@AutoConfigureMockMvc
class MockMvcExampleTests {

    @Test
    void exampleTest(@Autowired MockMvc mvc) throws Exception {
        mvc.perform(get("/")).andExpect(status().isOk()).andExpect(content().string("Hello World"));
    }

}
完全な ApplicationContextを開始せずにWebレイヤーのみに焦点を合わせたい場合は、代わりに @WebMvcTest の使用を検討してください

または、次の例に示すように WebTestClient を構成できます。

import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.reactive.AutoConfigureWebTestClient;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.reactive.server.WebTestClient;

@SpringBootTest
@AutoConfigureWebTestClient
class MockWebTestClientExampleTests {

    @Test
    void exampleTest(@Autowired WebTestClient webClient) {
        webClient.get().uri("/").exchange().expectStatus().isOk().expectBody(String.class).isEqualTo("Hello World");
    }

}

モック環境内でのテストは、通常、完全なサーブレットコンテナーで実行するよりも高速です。ただし、モックはSpring MVCレイヤーで発生するため、下位レベルのサーブレットコンテナーの動作に依存するコードはMockMvcで直接テストできません。

例:Spring Bootのエラー処理は、サーブレットコンテナーによって提供される「エラーページ」サポートに基づいています。これは、MVCレイヤーが期待どおりに例外をスローおよび処理することをテストできますが、特定のカスタムエラーページがレンダリングされることを直接テストできないことを意味します。これらの下位レベルの懸念事項をテストする必要がある場合は、次のセクションで説明するように、完全に実行されているサーバーを起動できます。

25.3.6. 実行中のサーバーでテストする

完全に稼働しているサーバーを起動する必要がある場合は、ランダムなポートを使用することをお勧めします。 @SpringBootTest(webEnvironment=WebEnvironment.RANDOM_PORT)を使用すると、テストを実行するたびに使用可能なポートがランダムに選択されます。

@LocalServerPort アノテーションを使用して、テストに実際に使用されるポートを挿入できます。便宜上、開始されたサーバーに対してREST呼び出しを行う必要があるテストでは、@Autowire WebTestClient を追加できます。これは、実行中のサーバーへの相対リンクを解決し、次の例に示すように、応答を検証する専用APIを備えています:

import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.test.web.reactive.server.WebTestClient;

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class RandomPortWebTestClientExampleTests {

    @Test
    void exampleTest(@Autowired WebTestClient webClient) {
        webClient.get().uri("/").exchange().expectStatus().isOk().expectBody(String.class).isEqualTo("Hello World");
    }

}

このセットアップでは、クラスパスに spring-webflux が必要です。Webfluxを追加できない場合、または追加しない場合、Spring Bootは TestRestTemplate 機能も提供します。

import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.boot.test.web.client.TestRestTemplate;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class RandomPortTestRestTemplateExampleTests {

    @Test
    void exampleTest(@Autowired TestRestTemplate restTemplate) {
        String body = restTemplate.getForObject("/", String.class);
        assertThat(body).isEqualTo("Hello World");
    }

}

25.3.7. WebTestClientのカスタマイズ

WebTestClient Beanをカスタマイズするには、WebTestClientBuilderCustomizer Beanを構成します。このようなBeanは、WebTestClientの作成に使用される WebTestClient.Builder で呼び出されます。

25.3.8. JMXを使用する

テストコンテキストフレームワークはコンテキストをキャッシュするため、JMXはデフォルトで無効になり、同一ドメインに同一のコンポーネントが登録されないようにします。そのようなテストが MBeanServerにアクセスする必要がある場合、同様にダーティマークを付けることを検討してください。

@ExtendWith(SpringExtension.class)
@SpringBootTest(properties = "spring.jmx.enabled=true")
@DirtiesContext
class SampleJmxTests {

    @Autowired
    private MBeanServer mBeanServer;

    @Test
    void exampleTest() {
        // ...
    }

}

25.3.9. Beanのモックとスパイ

テストを実行するとき、アプリケーションコンテキスト内の特定のコンポーネントをモックする必要がある場合があります。例:開発中は利用できないリモートサービスのファサードがある場合があります。モックは、実際の環境では引き起こしにくい障害をシミュレートする場合にも役立ちます。

Spring Bootには、ApplicationContext内のBeanのMockitoモックを定義するために使用できる @MockBean アノテーションが含まれています。アノテーションを使用して、新しいBeanを追加したり、単一の既存のBean定義を置き換えることができます。アノテーションは、テストクラス、テスト内のフィールド、または @Configuration クラスとフィールドで直接使用できます。フィールドで使用すると、作成されたモックのインスタンスも注入されます。モックBeanは、各テストメソッドの後に自動的にリセットされます。

テストでSpring Bootのテストアノテーションの1つ( @SpringBootTestなど)を使用する場合、この機能は自動的に有効になります。別の配置でこの機能を使用するには、次の例に示すように、リスナーを明示的に追加する必要があります。

@TestExecutionListeners(MockitoTestExecutionListener.class)

次の例では、既存の RemoteService Beanをモック実装に置き換えます。

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.*;
import org.springframework.boot.test.context.*;
import org.springframework.boot.test.mock.mockito.*;

import static org.assertj.core.api.Assertions.*;
import static org.mockito.BDDMockito.*;

@SpringBootTest
class MyTests {

    @MockBean
    private RemoteService remoteService;

    @Autowired
    private Reverser reverser;

    @Test
    void exampleTest() {
        // RemoteService has been injected into the reverser bean
        given(this.remoteService.someCall()).willReturn("mock");
        String reverse = reverser.reverseSomeCall();
        assertThat(reverse).isEqualTo("kcom");
    }

}
@MockBean を使用して、アプリケーションコンテキストのリフレッシュ中に実行されるBeanの動作をモックすることはできません。テストが実行されるまでに、アプリケーションコンテキストのリフレッシュが完了し、モック動作を構成するには遅すぎます。この状況では、@Bean メソッドを使用してモックを作成および構成することをお勧めします。

さらに、@SpyBean を使用して、既存のBeanをMockito spyでラップすることができます。詳細については、Javadocを参照してください。

スコープ付きBean用に作成されたものなどのCGLibプロキシは、プロキシされたメソッドを finalとして宣言します。これにより、Mockitoはデフォルト設定で final メソッドをモックまたはスパイできないため、Mockitoが正しく機能しなくなります。このようなBeanをモックまたはスパイしたい場合は、org.mockito:mockito-inline をアプリケーションのテスト依存関係に追加して、Mockitoがインラインモックメーカーを使用するように構成します。これにより、Mockitoは final メソッドをモックおよびスパイできます。
Springのテストフレームワークはテスト間でアプリケーションコンテキストをキャッシュし、同じ構成を共有するテストでコンテキストを再利用しますが、@MockBean または @SpyBean の使用はキャッシュキーに影響し、コンテキストの数を増やす可能性が高くなります。
@SpyBean を使用して、名前でパラメーターを参照する @Cacheable メソッドでBeanをスパイする場合、アプリケーションは -parametersでコンパイルする必要があります。これにより、Beanがスパイされると、パラメーター名がキャッシュインフラストラクチャで使用可能になります。

25.3.10. 自動構成されたテスト

Spring Bootの自動構成システムは、アプリケーションではうまく機能しますが、テストでは少し大きすぎる場合があります。多くの場合、アプリケーションの「スライス」をテストするために必要な構成の部分のみをロードすると役立ちます。例:Spring MVCコントローラーがURLを正しくマッピングしていることをテストしたい場合があり、それらのテストにデータベース呼び出しを含めたくない場合、またはJPAエンティティをテストしたい場合、それらのテスト時にWebレイヤーに関心がない場合実行。

spring-boot-test-autoconfigure モジュールには、このような「スライス」を自動的に構成するために使用できる多くのアノテーションが含まれています。それぞれが同様に機能し、ApplicationContext をロードする @…​Test アノテーションと、自動構成設定のカスタマイズに使用できる1つ以上の @AutoConfigure…​ アノテーションを提供します。

各スライスは、コンポーネントスキャンを適切なコンポーネントに制限し、非常に制限された自動構成クラスのセットをロードします。それらのいずれかを除外する必要がある場合、ほとんどの @…​Test アノテーションは excludeAutoConfiguration 属性を提供します。または、@ImportAutoConfiguration#excludeを使用できます。
1つのテストで複数の @…​Test アノテーションを使用して複数の「スライス」を含めることはサポートされていません。複数の「スライス」が必要な場合は、@…​Test アノテーションの1つを選択し、他の「スライス」の @AutoConfigure…​ アノテーションを手動で含めます。
@AutoConfigure…​ アノテーションを標準の @SpringBootTest アノテーションとともに使用することもできます。アプリケーションの「スライス」に興味はないが、自動構成されたテストBeanの一部が必要な場合は、この組み合わせを使用できます。

25.3.11. 自動構成されたJSONテスト

オブジェクトのJSON直列化と逆直列化が期待どおりに機能することをテストするには、@JsonTest アノテーションを使用できます。 @JsonTest は、使用可能なサポートされているJSONマッパーを自動構成します。これは、次のライブラリのいずれかです。

  • Jackson ObjectMapper@JsonComponent BeanおよびJackson Module s

  • Gson

  • Jsonb

@JsonTest によって有効にされる自動構成のリストは、付録に記載されています。

自動構成の要素を構成する必要がある場合は、@AutoConfigureJsonTesters アノテーションを使用できます。

Spring Bootには、JSONAssertおよびJsonPathライブラリと連携してJSONが期待どおりに表示されることを確認するAssertJベースのヘルパーが含まれています。 JacksonTester, GsonTester, JsonbTesterおよび BasicJsonTester クラスは、それぞれJackson、Gson、Jsonb、およびStringsに使用できます。 @JsonTestを使用する場合、テストクラスのヘルパーフィールドは @Autowired になります。次の例は、Jacksonのテストクラスを示しています。

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.*;
import org.springframework.boot.test.autoconfigure.json.*;
import org.springframework.boot.test.context.*;
import org.springframework.boot.test.json.*;

import static org.assertj.core.api.Assertions.*;

@JsonTest
class MyJsonTests {

    @Autowired
    private JacksonTester<VehicleDetails> json;

    @Test
    void testSerialize() throws Exception {
        VehicleDetails details = new VehicleDetails("Honda", "Civic");
        // Assert against a `.json` file in the same package as the test
        assertThat(this.json.write(details)).isEqualToJson("expected.json");
        // Or use JSON path based assertions
        assertThat(this.json.write(details)).hasJsonPathStringValue("@.make");
        assertThat(this.json.write(details)).extractingJsonPathStringValue("@.make")
                .isEqualTo("Honda");
    }

    @Test
    void testDeserialize() throws Exception {
        String content = "{\"make\":\"Ford\",\"model\":\"Focus\"}";
        assertThat(this.json.parse(content))
                .isEqualTo(new VehicleDetails("Ford", "Focus"));
        assertThat(this.json.parseObject(content).getMake()).isEqualTo("Ford");
    }

}
JSONヘルパークラスは、標準の単体テストで直接使用することもできます。これを行うには、@JsonTestを使用しない場合、@Before メソッドでヘルパーの initFields メソッドを呼び出します。

Spring BootのAssertJベースのヘルパーを使用して、特定のJSONパスで数値をアサートする場合、タイプによっては isEqualTo を使用できない場合があります。代わりに、AssertJの satisfies を使用して、値が指定された条件に一致することをアサートできます。たとえば、次の例では、実際の数値が 0.01のオフセット内で 0.15 に近い浮動小数点値であることを表明しています。

assertThat(json.write(message))
    .extractingJsonPathNumberValue("@.test.numberValue")
    .satisfies((number) -> assertThat(number.floatValue()).isCloseTo(0.15f, within(0.01f)));

25.3.12. 自動構成されたSpring MVCテスト

Spring MVCコントローラーが期待どおりに機能しているかどうかをテストするには、@WebMvcTest アノテーションを使用します。 @WebMvcTest は、Spring MVCインフラストラクチャーを自動構成し、スキャンされたBeanを @Controller, @ControllerAdvice, @JsonComponent, Converter, GenericConverter, Filter, HandlerInterceptor, WebMvcConfigurerおよび HandlerMethodArgumentResolverに制限します。このアノテーションを使用すると、通常の @Component Beanはスキャンされません。

@WebMvcTest によって有効にされる自動構成設定のリストは、付録に記載されています。
Jackson Moduleなどの追加コンポーネントを登録する必要がある場合は、テストで @Import を使用して追加の構成クラスをインポートできます。

多くの場合、@WebMvcTest は単一のコントローラーに限定され、@MockBean と組み合わせて使用され、必要なコラボレーターにモック実装を提供します。

@WebMvcTestMockMvcも自動構成します。Mock MVCは、完全なHTTPサーバーを起動する必要なく、MVCコントローラーをすばやくテストする強力な方法を提供します。

@AutoConfigureMockMvcでアノテーションを付けることにより、非@WebMvcTest@SpringBootTestなど)で MockMvc を自動構成することもできます。次の例では、MockMvcを使用しています。
import org.junit.jupiter.api.*;
import org.springframework.beans.factory.annotation.*;
import org.springframework.boot.test.autoconfigure.web.servlet.*;
import org.springframework.boot.test.mock.mockito.*;

import static org.assertj.core.api.Assertions.*;
import static org.mockito.BDDMockito.*;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest(UserVehicleController.class)
class MyControllerTests {

    @Autowired
    private MockMvc mvc;

    @MockBean
    private UserVehicleService userVehicleService;

    @Test
    void testExample() throws Exception {
        given(this.userVehicleService.getVehicleDetails("sboot"))
                .willReturn(new VehicleDetails("Honda", "Civic"));
        this.mvc.perform(get("/sboot/vehicle").accept(MediaType.TEXT_PLAIN))
                .andExpect(status().isOk()).andExpect(content().string("Honda Civic"));
    }

}
自動構成の要素を構成する必要がある場合(たとえば、サーブレットフィルターを適用する必要がある場合)、@AutoConfigureMockMvc アノテーションの属性を使用できます。

HtmlUnitまたはSeleniumを使用する場合、自動構成はHtmlUnit WebClient Beanおよび/またはSelenium WebDriver Beanも提供します。次の例では、HtmlUnitを使用しています。

import com.gargoylesoftware.htmlunit.*;
import org.junit.jupiter.api.*;
import org.springframework.beans.factory.annotation.*;
import org.springframework.boot.test.autoconfigure.web.servlet.*;
import org.springframework.boot.test.mock.mockito.*;

import static org.assertj.core.api.Assertions.*;
import static org.mockito.BDDMockito.*;

@WebMvcTest(UserVehicleController.class)
class MyHtmlUnitTests {

    @Autowired
    private WebClient webClient;

    @MockBean
    private UserVehicleService userVehicleService;

    @Test
    void testExample() throws Exception {
        given(this.userVehicleService.getVehicleDetails("sboot"))
                .willReturn(new VehicleDetails("Honda", "Civic"));
        HtmlPage page = this.webClient.getPage("/sboot/vehicle.html");
        assertThat(page.getBody().getTextContent()).isEqualTo("Honda Civic");
    }

}
デフォルトでは、Spring Bootは WebDriver Beanを特別な「スコープ」に入れて、各テスト後にドライバーが終了し、新しいインスタンスが挿入されるようにします。この動作が望ましくない場合は、@Scope("singleton")WebDriver @Bean 定義に追加できます。
Spring Bootによって作成された webDriver スコープは、同じ名前のユーザー定義スコープを置き換えます。独自の webDriver スコープを定義すると、@WebMvcTestを使用すると動作が停止する場合があります。

クラスパスにSpring Securityがある場合、@WebMvcTestWebSecurityConfigurer Beanもスキャンします。そのようなテストのセキュリティを完全に無効にする代わりに、Spring Securityのテストサポートを使用できます。Spring Securityの MockMvc サポートの使用方法の詳細については、このhowto.html使い方セクションを参照してください。

Spring MVCテストを書くだけでは十分でない場合があります。Spring Bootは、実際のサーバーで完全なエンドツーエンドテストを実行するのに役立ちます。

25.3.13. 自動構成されたSpring WebFluxテスト

Spring WebFluxコントローラーが期待どおりに機能していることをテストするには、@WebFluxTest アノテーションを使用できます。 @WebFluxTest はSpring WebFluxインフラストラクチャを自動構成し、スキャンされたBeanを @Controller, @ControllerAdvice, @JsonComponent, Converter, GenericConverter, WebFilterおよび WebFluxConfigurerに制限します。 @WebFluxTest アノテーションが使用されている場合、通常の @Component Beanはスキャンされません。

@WebFluxTest によって有効にされる自動構成のリストは、付録に記載されています。
Jackson Moduleなどの追加コンポーネントを登録する必要がある場合は、テストで @Import を使用して追加の構成クラスをインポートできます。

多くの場合、@WebFluxTest は単一のコントローラーに限定され、@MockBean アノテーションと組み合わせて使用され、必要なコラボレーターにモック実装を提供します。

@WebFluxTest WebTestClient も自動構成します。これにより、完全なHTTPサーバーを起動する必要なく、WebFluxコントローラーを迅速にテストする強力な方法が提供されます。

@AutoConfigureWebTestClientでアノテーションを付けることにより、非@WebFluxTest@SpringBootTestなど)で WebTestClient を自動構成することもできます。次の例は、@WebFluxTestWebTestClientの両方を使用するクラスを示しています。
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.reactive.server.WebTestClient;

@WebFluxTest(UserVehicleController.class)
class MyControllerTests {

    @Autowired
    private WebTestClient webClient;

    @MockBean
    private UserVehicleService userVehicleService;

    @Test
    void testExample() throws Exception {
        given(this.userVehicleService.getVehicleDetails("sboot"))
                .willReturn(new VehicleDetails("Honda", "Civic"));
        this.webClient.get().uri("/sboot/vehicle").accept(MediaType.TEXT_PLAIN)
                .exchange()
                .expectStatus().isOk()
                .expectBody(String.class).isEqualTo("Honda Civic");
    }

}
モックWebアプリケーションで WebTestClient を使用するのは、現時点ではWebFluxでのみ機能するため、このセットアップはWebFluxアプリケーションでのみサポートされます。
@WebFluxTest は、機能的なWebフレームワークを介して登録されたルートを検出できません。コンテキストで RouterFunction Beanをテストするには、@Import または @SpringBootTestを使用して、RouterFunction を自分でインポートすることを検討してください。
@WebFluxTest は、タイプ SecurityWebFilterChain@Bean を介して登録されたカスタムセキュリティ構成を検出できません。これをテストに含めるには、@Import 経由でBeanを登録する構成をインポートするか、@SpringBootTestを使用する必要があります。
Spring WebFluxテストを書くだけでは十分でない場合があります。Spring Bootは、実際のサーバーで完全なエンドツーエンドテストを実行するのに役立ちます。

25.3.14. 自動構成されたデータJPAテスト

@DataJpaTest アノテーションを使用して、JPAアプリケーションをテストできます。デフォルトでは、@Entity クラスをスキャンし、Spring Data JPAリポジトリを構成します。組み込みデータベースがクラスパスで使用可能な場合、それも構成します。通常の @Component Beanは ApplicationContextにロードされません。

@DataJpaTest によって有効にされる自動構成設定のリストは、付録に記載されています。

デフォルトでは、データJPAテストはトランザクションであり、各テストの終了時にロールバックされます。詳細については、Spring Frameworkリファレンスドキュメントの関連セクションを参照してください。それが望んでいない場合、次のようにテストまたはクラス全体のトランザクション管理を無効にできます。

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

@DataJpaTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class ExampleNonTransactionalTests {

}

データJPAテストは、 TestEntityManager (GitHub) Beanを挿入することもできます。これは、テスト用に特別に設計された標準のJPA EntityManager の代替を提供します。 @DataJpaTest インスタンスの外部で TestEntityManager を使用する場合は、@AutoConfigureTestEntityManager アノテーションも使用できます。 JdbcTemplate も必要な場合に利用できます。次の例は、使用中の @DataJpaTest アノテーションを示しています。

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.autoconfigure.orm.jpa.*;

import static org.assertj.core.api.Assertions.*;

@DataJpaTest
class ExampleRepositoryTests {

    @Autowired
    private TestEntityManager entityManager;

    @Autowired
    private UserRepository repository;

    @Test
    void testExample() throws Exception {
        this.entityManager.persist(new User("sboot", "1234"));
        User user = this.repository.findByUsername("sboot");
        assertThat(user.getUsername()).isEqualTo("sboot");
        assertThat(user.getVin()).isEqualTo("1234");
    }

}

メモリ内の組み込みデータベースは、高速でインストールを必要としないため、一般にテストに適しています。ただし、次の例に示すように、実際のデータベースに対してテストを実行する場合は、@AutoConfigureTestDatabase アノテーションを使用できます。

@DataJpaTest
@AutoConfigureTestDatabase(replace=Replace.NONE)
class ExampleRepositoryTests {

    // ...

}

25.3.15. 自動構成されたJDBCテスト

@JdbcTest@DataJpaTest に似ていますが、DataSource のみを必要とし、Spring Data JDBCを使用しないテスト用です。デフォルトでは、インメモリ組み込みデータベースと JdbcTemplateを構成します。通常の @Component Beanは ApplicationContextにロードされません。

@JdbcTest によって有効にされる自動構成のリストは、付録に記載されています。

デフォルトでは、JDBCテストはトランザクション対応であり、各テストの終わりにロールバックします。詳細については、Spring Frameworkリファレンスドキュメントの関連セクションを参照してください。それが望んでいない場合は、次のように、テストまたはクラス全体のトランザクション管理を無効にできます。

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.autoconfigure.jdbc.JdbcTest;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

@JdbcTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class ExampleNonTransactionalTests {

}

テストを実際のデータベースに対して実行したい場合は、DataJpaTestと同じ方法で @AutoConfigureTestDatabase アノテーションを使用できます。(「自動構成されたデータJPAテスト」を参照してください。)

25.3.16. 自動構成されたデータJDBCテスト

@DataJdbcTest@JdbcTest に似ていますが、Spring Data JDBCリポジトリを使用するテスト用です。デフォルトでは、インメモリ組み込みデータベース、JdbcTemplate、およびSpring Data JDBCリポジトリを構成します。通常の @Component Beanは ApplicationContextにロードされません。

@DataJdbcTest によって有効にされる自動構成のリストは、付録に記載されています。

デフォルトでは、データJDBCテストはトランザクションであり、各テストの終了時にロールバックされます。詳細については、Spring Frameworkリファレンスドキュメントの関連セクションを参照してください。それが望んでいない場合、JDBCの例に示すように、テストまたはテストクラス全体のトランザクション管理を無効にすることができます。

テストを実際のデータベースに対して実行したい場合は、DataJpaTestと同じ方法で @AutoConfigureTestDatabase アノテーションを使用できます。(「自動構成されたデータJPAテスト」を参照してください。)

25.3.17. 自動構成されたjOOQテスト

@JdbcTest と同様の方法で @JooqTest を使用できますが、jOOQ関連のテストに使用できます。jOOQはデータベーススキーマに対応するJavaベースのスキーマに大きく依存しているため、既存の DataSource が使用されます。メモリ内のデータベースに置き換える場合は、@AutoConfigureTestDatabase を使用してこれらの設定を上書きできます。(Spring BootでのjOOQの使用の詳細については、この章で前述した「jOOQを使用する」を参照してください。)通常の @Component Beanは ApplicationContextにロードされません。

@JooqTest によって有効にされる自動構成のリストは、付録に記載されています。

@JooqTestDSLContextを構成します。通常の @Component Beanは ApplicationContextにロードされません。次の例は、使用中の @JooqTest アノテーションを示しています。

import org.jooq.DSLContext;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.autoconfigure.jooq.JooqTest;

@JooqTest
class ExampleJooqTests {

    @Autowired
    private DSLContext dslContext;
}

JOOQテストはトランザクション対応であり、デフォルトでは各テストの終わりにロールバックします。それが望んでいない場合、JDBCの例に示すように、テストまたはテストクラス全体のトランザクション管理を無効にすることができます。

25.3.18. 自動構成されたデータMongoDBテスト

@DataMongoTest を使用して、MongoDBアプリケーションをテストできます。デフォルトでは、メモリ内の組み込みMongoDB(使用可能な場合)を構成し、MongoTemplateを構成し、@Document クラスをスキャンし、Spring Data MongoDBリポジトリを構成します。通常の @Component Beanは ApplicationContextにロードされません。(Spring BootでのMongoDBの使用の詳細については、この章で前述した「MongoDB」を参照してください。)

@DataMongoTest によって有効にされる自動構成設定のリストは、付録に記載されています。

次のクラスは、使用中の @DataMongoTest アノテーションを示しています。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.mongo.DataMongoTest;
import org.springframework.data.mongodb.core.MongoTemplate;

@DataMongoTest
class ExampleDataMongoTests {

    @Autowired
    private MongoTemplate mongoTemplate;

    //
}

メモリ内に埋め込まれたMongoDBは、高速で開発者がインストールする必要がないため、一般にテストに適しています。ただし、実際のMongoDBサーバーに対してテストを実行する場合は、次の例に示すように、組み込みのMongoDB自動構成を除外する必要があります。

import org.springframework.boot.autoconfigure.mongo.embedded.EmbeddedMongoAutoConfiguration;
import org.springframework.boot.test.autoconfigure.data.mongo.DataMongoTest;

@DataMongoTest(excludeAutoConfiguration = EmbeddedMongoAutoConfiguration.class)
class ExampleDataMongoNonEmbeddedTests {

}

25.3.19. 自動構成されたデータNeo4jテスト

@DataNeo4jTest を使用して、Neo4jアプリケーションをテストできます。デフォルトでは、メモリ内の埋め込みNeo4j(埋め込みドライバが利用可能な場合)を使用し、@NodeEntity クラスをスキャンし、Spring Data Neo4jリポジトリを構成します。通常の @Component Beanは ApplicationContextにロードされません。(Neo4JをSpring Bootで使用する方法の詳細については、この章で前述した「Neo4j」を参照してください。)

@DataNeo4jTest によって有効にされる自動構成設定のリストは、付録に記載されています。

次の例は、Spring BootでNeo4Jテストを使用するための一般的なセットアップを示しています。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.neo4j.DataNeo4jTest;

@DataNeo4jTest
class ExampleDataNeo4jTests {

    @Autowired
    private YourRepository repository;

    //
}

デフォルトでは、Data Neo4jテストはトランザクション対応であり、各テストの終わりにロールバックします。詳細については、Spring Frameworkリファレンスドキュメントの関連セクションを参照してください。それが望んでいない場合は、次のように、テストまたはクラス全体のトランザクション管理を無効にできます。

import org.springframework.boot.test.autoconfigure.data.neo4j.DataNeo4jTest;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

@DataNeo4jTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class ExampleNonTransactionalTests {

}

25.3.20. 自動構成データRedisテスト

@DataRedisTest を使用して、Redisアプリケーションをテストできます。デフォルトでは、@RedisHash クラスをスキャンし、Spring Data Redisリポジトリを構成します。通常の @Component Beanは ApplicationContextにロードされません。(RedisをSpring Bootとともに使用する方法の詳細については、この章で前述した「Redis」を参照してください。)

@DataRedisTest によって有効にされる自動構成設定のリストは、付録に記載されています。

次の例は、使用中の @DataRedisTest アノテーションを示しています。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.redis.DataRedisTest;

@DataRedisTest
class ExampleDataRedisTests {

    @Autowired
    private YourRepository repository;

    //
}

25.3.21. 自動構成データLDAPテスト

@DataLdapTest を使用して、LDAPアプリケーションをテストできます。デフォルトでは、インメモリ組み込みLDAP(使用可能な場合)を構成し、LdapTemplateを構成し、@Entry クラスをスキャンし、Spring Data LDAPリポジトリを構成します。通常の @Component Beanは ApplicationContextにロードされません。(Spring BootでのLDAPの使用の詳細については、この章で前述した「LDAP」を参照してください。)

@DataLdapTest によって有効にされる自動構成設定のリストは、付録に記載されています。

次の例は、使用中の @DataLdapTest アノテーションを示しています。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.ldap.DataLdapTest;
import org.springframework.ldap.core.LdapTemplate;

@DataLdapTest
class ExampleDataLdapTests {

    @Autowired
    private LdapTemplate ldapTemplate;

    //
}

メモリ内の組み込みLDAPは、高速であり、開発者がインストールする必要がないため、一般にテストに適しています。ただし、実際のLDAPサーバーに対してテストを実行する場合は、次の例に示すように、組み込みのLDAP自動構成を除外する必要があります。

import org.springframework.boot.autoconfigure.ldap.embedded.EmbeddedLdapAutoConfiguration;
import org.springframework.boot.test.autoconfigure.data.ldap.DataLdapTest;

@DataLdapTest(excludeAutoConfiguration = EmbeddedLdapAutoConfiguration.class)
class ExampleDataLdapNonEmbeddedTests {

}

25.3.22. 自動構成されたRESTクライアント

@RestClientTest アノテーションを使用して、RESTクライアントをテストできます。デフォルトでは、Jackson、GSON、およびJsonbサポートを自動構成し、RestTemplateBuilderを構成し、MockRestServiceServerのサポートを追加します。通常の @Component Beanは ApplicationContextにロードされません。

@RestClientTest によって有効にされる自動構成設定のリストは、付録に記載されています。

テストする特定のBeanは、次の例に示すように、@RestClientTestvalue または components 属性を使用して指定する必要があります。

@RestClientTest(RemoteVehicleDetailsService.class)
class ExampleRestClientTest {

    @Autowired
    private RemoteVehicleDetailsService service;

    @Autowired
    private MockRestServiceServer server;

    @Test
    void getVehicleDetailsWhenResultIsSuccessShouldReturnDetails()
            throws Exception {
        this.server.expect(requestTo("/greet/details"))
                .andRespond(withSuccess("hello", MediaType.TEXT_PLAIN));
        String greeting = this.service.callRestService();
        assertThat(greeting).isEqualTo("hello");
    }

}

25.3.23. 自動構成されたSpring REST Docsテスト

@AutoConfigureRestDocs アノテーションを使用して、Mock MVC、REST Assured、またはWebTestClientを使用したテストでSpring REST Docsを使用できます。Spring REST DocsのJUnit拡張機能の必要性がなくなります。

@AutoConfigureRestDocs を使用して、デフォルトの出力ディレクトリをオーバーライドできます(Mavenを使用している場合はtarget/generated-snippets、Gradleを使用している場合は build/generated-snippets )。また、ドキュメント化されたURIに表示されるホスト、スキーム、およびポートの構成にも使用できます。

Mock MVCで自動構成されたSpring REST Docsテスト

@AutoConfigureRestDocs は、Spring REST Docsを使用するように MockMvc Beanをカスタマイズします。次の例に示すように、Mock MVCおよびSpring REST Docsを使用する場合と同様に、@Autowired を使用して注入し、テストで使用できます。

import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest(UserController.class)
@AutoConfigureRestDocs
class UserDocumentationTests {

    @Autowired
    private MockMvc mvc;

    @Test
    void listUsers() throws Exception {
        this.mvc.perform(get("/users").accept(MediaType.TEXT_PLAIN))
                .andExpect(status().isOk())
                .andDo(document("list-users"));
    }

}

@AutoConfigureRestDocsの属性で提供されるよりもSpring REST Docs構成をより詳細に制御する必要がある場合は、次の例に示すように、RestDocsMockMvcConfigurationCustomizer Beanを使用できます。

@TestConfiguration
static class CustomizationConfiguration
        implements RestDocsMockMvcConfigurationCustomizer {

    @Override
    public void customize(MockMvcRestDocumentationConfigurer configurer) {
        configurer.snippets().withTemplateFormat(TemplateFormats.markdown());
    }

}

パラメータ化された出力ディレクトリのSpring REST Docsサポートを利用する場合は、RestDocumentationResultHandler Beanを作成できます。自動構成は、この結果ハンドラーを使用して alwaysDo を呼び出します。これにより、各 MockMvc 呼び出しでデフォルトのスニペットが自動的に生成されます。次の例は、定義されている RestDocumentationResultHandler を示しています。

@TestConfiguration(proxyBeanMethods = false)
static class ResultHandlerConfiguration {

    @Bean
    public RestDocumentationResultHandler restDocumentation() {
        return MockMvcRestDocumentation.document("{method-name}");
    }

}
WebTestClientで自動構成されたSpring REST Docsテスト

@AutoConfigureRestDocsWebTestClientでも使用できます。次の例に示すように、@Autowired を使用してそれを注入し、@WebFluxTest およびSpring REST Docsを使用するときに通常行うようにテストで使用できます。

import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
import org.springframework.test.web.reactive.server.WebTestClient;

import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;

@WebFluxTest
@AutoConfigureRestDocs
class UsersDocumentationTests {

    @Autowired
    private WebTestClient webTestClient;

    @Test
    void listUsers() {
        this.webTestClient.get().uri("/").exchange().expectStatus().isOk().expectBody()
                .consumeWith(document("list-users"));
    }

}

@AutoConfigureRestDocsの属性で提供されるよりもSpring REST Docs構成をより詳細に制御する必要がある場合は、次の例に示すように、RestDocsWebTestClientConfigurationCustomizer Beanを使用できます。

@TestConfiguration(proxyBeanMethods = false)
public static class CustomizationConfiguration implements RestDocsWebTestClientConfigurationCustomizer {

    @Override
    public void customize(WebTestClientRestDocumentationConfigurer configurer) {
        configurer.snippets().withEncoding("UTF-8");
    }

}
REST Assuredで自動構成されたSpring REST Docsテスト

@AutoConfigureRestDocs は、Spring REST Docsを使用するように事前構成された RequestSpecification Beanをテストで使用できるようにします。次の例に示すように、REST AssuredおよびSpring REST Docsを使用する場合と同様に、@Autowired を使用して注入し、テストで使用できます。

import io.restassured.specification.RequestSpecification;
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.boot.web.server.LocalServerPort;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.is;
import static org.springframework.restdocs.restassured3.RestAssuredRestDocumentation.document;

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureRestDocs
class UserDocumentationTests {

    @Test
    void listUsers(@Autowired RequestSpecification documentationSpec, @LocalServerPort int port) {
        given(documentationSpec).filter(document("list-users")).when().port(port).get("/").then().assertThat()
                .statusCode(is(200));
    }

}

@AutoConfigureRestDocsの属性で提供されるよりもSpring REST Docs構成をより詳細に制御する必要がある場合、次の例に示すように、RestDocsRestAssuredConfigurationCustomizer Beanを使用できます。

@TestConfiguration(proxyBeanMethods = false)
public static class CustomizationConfiguration implements RestDocsRestAssuredConfigurationCustomizer {

    @Override
    public void customize(RestAssuredRestDocumentationConfigurer configurer) {
        configurer.snippets().withTemplateFormat(TemplateFormats.markdown());
    }

}

25.3.24. 追加の自動構成とスライス

各スライスは、スライスの一部として含まれるべき自動構成を定義する1つ以上の @AutoConfigure…​ アノテーションを提供します。次の例に示すように、カスタム @AutoConfigure…​ アノテーションを作成するか、テストに @ImportAutoConfiguration を追加するだけで、追加の自動構成を追加できます。

@JdbcTest
@ImportAutoConfiguration(IntegrationAutoConfiguration.class)
class ExampleJdbcTests {

}
自動構成はSpring Bootによって特定の方法で処理されるため、通常の @Import アノテーションを使用して自動構成をインポートしないようにしてください。

25.3.25. ユーザー設定とスライス

コードを適切な方法で構成する場合、@SpringBootApplication クラスはデフォルトでテストの構成として使用されます

その場合、アプリケーションのメインクラスに、その機能の特定の領域に固有の構成設定を散らかさないことが重要になります。

Spring Batchを使用しており、自動構成に依存していると仮定します。 @SpringBootApplication は次のように定義できます。

@SpringBootApplication
@EnableBatchProcessing
public class SampleApplication { ... }

このクラスはテストのソース構成であるため、スライステストは実際にSpring Batchを開始しようとしますが、これは間違いなく実行したいことではありません。推奨されるアプローチは、次の例に示すように、アプリケーションと同じレベルの別の @Configuration クラスにそのエリア固有の構成を移動することです。

@Configuration(proxyBeanMethods = false)
@EnableBatchProcessing
public class BatchConfiguration { ... }
アプリケーションの複雑さに応じて、カスタマイズ用に単一の @Configuration クラスを用意するか、ドメイン領域ごとに1つのクラスを用意します。後者のアプローチでは、@Import アノテーションを使用して、必要に応じてテストの1つで有効にすることができます。

テストスライスは、@Configuration クラスをスキャンから除外します。例: @WebMvcTestの場合、次の構成では、テストスライスによってロードされたアプリケーションコンテキストに特定の WebMvcConfigurer Beanは含まれません。

@Configuration
public class WebConfiguration {
    @Bean
    public WebMvcConfigurer testConfigurer() {
        return new WebMvcConfigurer() {
            ...
        };
    }
}

ただし、以下の構成では、テストスライスによってカスタム WebMvcConfigurer がロードされます。

@Component
public class TestWebMvcConfigurer implements WebMvcConfigurer {
    ...
}

混乱のもう1つの原因は、クラスパススキャンです。実用的な方法でコードを構造化しながら、追加のパッケージをスキャンする必要があると仮定します。アプリケーションは次のコードのようになります。

@SpringBootApplication
@ComponentScan({ "com.example.app", "org.acme.another" })
public class SampleApplication { ... }

そうすることで、デフォルトのコンポーネントスキャンディレクティブが効果的にオーバーライドされ、選択したスライスに関係なく、これら2つのパッケージがスキャンされるという副作用があります。たとえば、@DataJpaTest は、アプリケーションのコンポーネントとユーザー構成を突然スキャンするようです。繰り返しますが、カスタムディレクティブを別のクラスに移動することは、この課題を解決するための良い方法です。

これが選択肢ではない場合は、テストの階層のどこかに @SpringBootConfiguration を作成して、代わりに使用することができます。あるいは、テストのソースを指定して、デフォルトのソースを見つける動作を無効にすることもできます。

25.3.26. Spockを使用してSpring Bootアプリケーションをテストする

Spockを使用してSpring Bootアプリケーションをテストする場合は、Spockの spock-spring モジュールへの依存関係をアプリケーションのビルドに追加する必要があります。 spock-spring は、SpringのテストフレームワークをSpockに統合します。Spock 1.2以降を使用して、SpockのSpring FrameworkおよびSpring Boot統合に対する多くの改善の恩恵を受けることをお勧めします。詳細については、SpockのSpringモジュールのドキュメントを参照して(英語) ください。

25.4. テストユーティリティ

アプリケーションのテスト時に一般的に役立ついくつかのテストユーティリティクラスは、spring-bootの一部としてパッケージ化されています。

25.4.1. ConfigFileApplicationContextInitializer

ConfigFileApplicationContextInitializer は、Spring Boot application.properties ファイルをロードするテストに適用できる ApplicationContextInitializer です。次の例に示すように、@SpringBootTestが提供する機能の完全なセットが不要な場合に使用できます。

@ContextConfiguration(classes = Config.class,
    initializers = ConfigFileApplicationContextInitializer.class)
ConfigFileApplicationContextInitializer を単独で使用しても、@Value("${…​}") インジェクションはサポートされません。その唯一のジョブは、application.properties ファイルがSpringの Environmentにロードされるようにすることです。 @Value をサポートするには、PropertySourcesPlaceholderConfigurer を追加で構成するか、@SpringBootTestを使用して自動で構成する必要があります。

25.4.2. TestPropertyValues

TestPropertyValues を使用すると、ConfigurableEnvironment または ConfigurableApplicationContextにプロパティをすばやく追加できます。次のように、key=value 文字列で呼び出すことができます。

TestPropertyValues.of("org=Spring", "name=Boot").applyTo(env);

25.4.3. OutputCapture

OutputCapture は、System.out および System.err 出力のキャプチャーに使用できるJUnit Extension です。 @ExtendWith(OutputCaptureExtension.class) を追加し、テストクラスのコンストラクターまたはテストメソッドへの引数として CapturedOutput を挿入するには、次のようにします。

@ExtendWith(OutputCaptureExtension.class)
class OutputCaptureTests {

    @Test
    void testName(CapturedOutput output) {
        System.out.println("Hello World!");
        assertThat(output).contains("World");
    }

}

25.4.4. TestRestTemplate

TestRestTemplate は、Springの RestTemplate の便利な代替手段であり、統合テストに役立ちます。vanillaテンプレートまたは基本HTTP認証を送信するテンプレート(ユーザー名とパスワード付き)を取得できます。どちらの場合でも、テンプレートはサーバー側のエラーで例外をスローしないことにより、テストに適した方法で動作します。

Spring Framework 5.0は、WebFlux統合テストおよび両方のWebFluxおよびMVCのエンドツーエンドテストで機能する新しい WebTestClient を提供します。 TestRestTemplateとは異なり、アサーションに流なAPIを提供します。

Apache HTTPクライアント(バージョン4.3.2以降)を使用することをお勧めしますが、必須ではありません。クラスパスにそれがある場合、TestRestTemplate はクライアントを適切に構成することにより応答します。ApacheのHTTPクライアントを使用する場合、いくつかの追加のテストフレンドリー機能が有効になります。

  • リダイレクトは追跡されません(したがって、応答の場所をアサートできます)。

  • Cookieは無視されます(したがって、テンプレートはステートレスです)。

TestRestTemplate は、次の例に示すように、統合テストで直接インスタンス化できます。

public class MyTest {

    private TestRestTemplate template = new TestRestTemplate();

    @Test
    public void testRequest() throws Exception {
        HttpHeaders headers = this.template.getForEntity(
                "https://myhost.example.com/example", String.class).getHeaders();
        assertThat(headers.getLocation()).hasHost("other.example.com");
    }

}

あるいは、WebEnvironment.RANDOM_PORT または WebEnvironment.DEFINED_PORT@SpringBootTest アノテーションを使用する場合、完全に構成された TestRestTemplate を注入して使用を開始できます。必要に応じて、RestTemplateBuilder Beanを通じて追加のカスタマイズを適用できます。次の例に示すように、ホストとポートを指定しないURLはすべて、組み込みサーバーに自動的に接続します。

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class SampleWebClientTests {

    @Autowired
    private TestRestTemplate template;

    @Test
    void testRequest() {
        HttpHeaders headers = this.template.getForEntity("/example", String.class).getHeaders();
        assertThat(headers.getLocation()).hasHost("other.example.com");
    }

    @TestConfiguration(proxyBeanMethods = false)
    static class Config {

        @Bean
        RestTemplateBuilder restTemplateBuilder() {
            return new RestTemplateBuilder().setConnectTimeout(Duration.ofSeconds(1))
                    .setReadTimeout(Duration.ofSeconds(1));
        }

    }

}

26. WebSockets

Spring Bootは、組み込みTomcat、Jetty、およびUndertowのWebSockets自動構成を提供します。warファイルをスタンドアロンコンテナーにデプロイする場合、Spring Bootは、コンテナーがWebSocketサポートの構成を担当していると想定します。

Spring Frameworkは、spring-boot-starter-websocket モジュールを介して簡単にアクセスできるMVC Webアプリケーションの豊富なWebSocketサポートを提供します。

WebSocketサポートは、リアクティブWebアプリケーションでも利用可能であり、spring-boot-starter-webfluxと一緒にWebSocket APIを含める必要があります。

<dependency>
    <groupId>javax.websocket</groupId>
    <artifactId>javax.websocket-api</artifactId>
</dependency>

27. Web サービス

Spring BootはWebサービスの自動構成を提供するため、Endpointsを定義するだけです。

Spring Web Servicesの機能(英語) は、spring-boot-starter-webservices モジュールで簡単にアクセスできます。

SimpleWsdl11Definition および SimpleXsdSchema Beanは、それぞれWSDLおよびXSDに対して自動的に作成できます。これを行うには、次の例に示すように、場所を構成します。

spring.webservices.wsdl-locations=classpath:/wsdl

27.1. WebServiceTemplateを使用したWebサービスの呼び出し

アプリケーションからリモート Webサービスを呼び出す必要がある場合は、 WebServiceTemplate (英語) クラスを使用できます。 WebServiceTemplate インスタンスは、使用する前にカスタマイズする必要があることが多いため、Spring Bootは単一の自動構成 WebServiceTemplate Beanを提供しません。ただし、必要に応じて WebServiceTemplate インスタンスを作成するために使用できる WebServiceTemplateBuilderを自動構成します。

次のコードは典型的な例を示しています。

@Service
public class MyService {

    private final WebServiceTemplate webServiceTemplate;

    public MyService(WebServiceTemplateBuilder webServiceTemplateBuilder) {
        this.webServiceTemplate = webServiceTemplateBuilder.build();
    }

    public DetailsResp someWsCall(DetailsReq detailsReq) {
         return (DetailsResp) this.webServiceTemplate.marshalSendAndReceive(detailsReq, new SoapActionCallback(ACTION));
    }

}

デフォルトでは、WebServiceTemplateBuilder は、クラスパスで使用可能なHTTPクライアントライブラリを使用して、適切なHTTPベースの WebServiceMessageSender を検出します。次のように、読み取りタイムアウトと接続タイムアウトをカスタマイズすることもできます。

@Bean
public WebServiceTemplate webServiceTemplate(WebServiceTemplateBuilder builder) {
    return builder.messageSenders(new HttpWebServiceMessageSenderBuilder()
            .setConnectTimeout(5000).setReadTimeout(2000).build()).build();
}

28. 独自の自動構成の作成

共有ライブラリを開発している会社で働いている場合、またはオープンソースまたは有償ライブラリで作業している場合、独自の自動構成を開発することができます。自動構成クラスは外部jarにバンドルでき、Spring Bootで引き続き取得できます。

自動構成は、自動構成コードと、使用する一般的なライブラリを提供する「スターター」に関連付けることができます。最初に、独自の自動構成を構築するために知っておく必要があることを説明し、次にカスタムスターターの作成に必要な一般的な手順に進みます

スターターを段階的に作成する方法を紹介するデモプロジェクト(GitHub) が用意されています。

28.1. 自動構成されたBeanについて

内部では、自動構成は標準の @Configuration クラスで実装されます。追加の @Conditional アノテーションは、自動構成をいつ適用するかを制限するために使用されます。通常、自動構成クラスは @ConditionalOnClass および @ConditionalOnMissingBean アノテーションを使用します。これにより、関連するクラスが見つかった場合、および独自の @Configurationを宣言していない場合にのみ、自動構成が適用されます。

spring-boot-autoconfigure (GitHub) のソースコードを参照して、Springが提供する @Configuration クラスを確認できます( META-INF/spring.factories (GitHub) ファイルを参照)。

28.2. 自動構成候補の特定

Spring Bootは、公開されたjar内の META-INF/spring.factories ファイルの存在を確認します。このファイルには、次の例に示すように、EnableAutoConfiguration キーに構成クラスがリストされている必要があります。

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.mycorp.libx.autoconfigure.LibXAutoConfiguration,\
com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration
自動構成はその方法でのみロードする必要があります。それらが特定のパッケージスペースで定義され、コンポーネントスキャンの対象にならないことを確認してください。さらに、自動構成クラスでは、追加のコンポーネントを見つけるためのコンポーネントスキャンを有効にしないでください。代わりに、特定の @Importを使用する必要があります。

構成を特定の順序で適用する必要がある場合は、 @AutoConfigureAfter (GitHub) または @AutoConfigureBefore (GitHub) アノテーションを使用できます。例:Web固有の構成を提供する場合、WebMvcAutoConfigurationの後にクラスを適用する必要がある場合があります。

相互の直接的な知識がないはずの特定の自動構成を並べ替える場合は、@AutoConfigureOrderも使用できます。そのアノテーションは、通常の @Order アノテーションと同じセマンティックを持ちますが、自動構成クラスに専用の順序を提供します。

28.3. 条件アノテーション

ほとんどの場合、1つ以上の @Conditional アノテーションを自動構成クラスに含める必要があります。 @ConditionalOnMissingBean アノテーションは、デフォルトに満足できない場合に開発者が自動構成をオーバーライドできるようにするために使用される一般的な例の1つです。

Spring Bootには、@Configuration クラスまたは個々の @Bean メソッドにアノテーションを付けることにより、独自のコードで再利用できる多数の @Conditional アノテーションが含まれています。これらのアノテーションは次のとおりです。

28.3.1. クラス Conditions

@ConditionalOnClass および @ConditionalOnMissingClass アノテーションにより、特定のクラスの有無に基づいて @Configuration クラスを含めることができます。アノテーションメタデータはASM(英語) を使用して解析されるという事実により、value 属性を使用して、実際のクラスを参照できます。ただし、そのクラスは実行中のアプリケーションクラスパスに実際には表示されない場合があります。 String 値を使用してクラス名を指定する場合は、name 属性も使用できます。

このメカニズムは、通常戻り型が条件のターゲットである @Bean メソッドに同じ方法を適用しません。メソッドの条件が適用される前に、JVMはクラスをロードし、クラスが処理されると失敗する可能性のあるメソッド参照を処理します。現在ではない。

このシナリオを処理するには、次の例に示すように、別個の @Configuration クラスを使用して条件を分離できます。

@Configuration(proxyBeanMethods = false)
// Some conditions
public class MyAutoConfiguration {

    // Auto-configured beans

    @Configuration(proxyBeanMethods = false)
    @ConditionalOnClass(EmbeddedAcmeService.class)
    static class EmbeddedConfiguration {

        @Bean
        @ConditionalOnMissingBean
        public EmbeddedAcmeService embeddedAcmeService() { ... }

    }

}
メタアノテーションの一部として @ConditionalOnClass または @ConditionalOnMissingClass を使用して独自の合成アノテーションを作成する場合、そのような場合はクラスを参照しないため、name を使用する必要があります。

28.3.2. Bean条件

@ConditionalOnBean および @ConditionalOnMissingBean アノテーションにより、特定のBeanの有無に基づいてBeanを含めることができます。 value 属性を使用して、タイプごとにBeanを指定したり、name を使用して名前ごとにBeanを指定したりできます。 search 属性を使用すると、Beanを検索するときに考慮する必要がある ApplicationContext 階層を制限できます。

@Bean メソッドに配置すると、次の例に示すように、ターゲットタイプはデフォルトでメソッドの戻り値タイプになります。

@Configuration(proxyBeanMethods = false)
public class MyAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public MyService myService() { ... }

}

上記の例では、MyService タイプのBeanが ApplicationContextに含まれていない場合、myService Beanが作成されます。

これらの条件はこれまでに処理されたものに基づいて評価されるため、Bean定義が追加される順序には非常に注意する必要があります。このため、自動構成クラスでは @ConditionalOnBean および @ConditionalOnMissingBean アノテーションのみを使用することをお勧めします(これらはユーザー定義のBean定義が追加された後にロードされることが保証されているため)。
@ConditionalOnBean および @ConditionalOnMissingBean は、@Configuration クラスの作成を妨げません。クラスレベルでこれらの条件を使用することと、含まれる各 @Bean メソッドをアノテーションでマークすることの唯一の違いは、条件が一致しない場合、前者は @Configuration クラスをBeanとして登録できないことです。

28.3.3. プロパティ条件

@ConditionalOnProperty アノテーションにより、Spring環境プロパティに基づいて構成を含めることができます。 prefix および name 属性を使用して、チェックするプロパティを指定します。デフォルトでは、存在し、false と等しくないプロパティはすべて一致します。 havingValue および matchIfMissing 属性を使用して、より高度なチェックを作成することもできます。

28.3.4. リソース条件

@ConditionalOnResource アノテーションを使用すると、特定のリソースが存在する場合にのみ構成を含めることができます。次の例に示すように、リソースは通常のSpring規則を使用して指定できます: file:/home/user/test.dat

28.3.5. Webアプリケーション条件

@ConditionalOnWebApplication および @ConditionalOnNotWebApplication アノテーションにより、アプリケーションが「Webアプリケーション」であるかどうかに応じて構成を含めることができます。サーブレットベースのWebアプリケーションは、Spring WebApplicationContextを使用するアプリケーション、session スコープを定義するアプリケーション、または ConfigurableWebEnvironmentを持つアプリケーションです。リアクティブWebアプリケーションは、ReactiveWebApplicationContextを使用するか、ConfigurableReactiveWebEnvironmentを持つアプリケーションです。

28.3.6. SpEL式の条件

@ConditionalOnExpression アノテーションにより、SpEL式の結果に基づいて構成を含めることができます。

28.4. 自動構成のテスト

自動構成は、ユーザー構成(@Bean 定義および Environment カスタマイズ)、条件評価(特定のライブラリの存在)など、多くの要因の影響を受ける可能性があります。具体的には、各テストで、これらのカスタマイズの組み合わせを表す、明確に定義された ApplicationContext を作成する必要があります。 ApplicationContextRunner はそれを達成するための素晴らしい方法を提供します。

ApplicationContextRunner は通常、基本の共通構成を収集するためのテストクラスのフィールドとして定義されます。次の例では、UserServiceAutoConfiguration が常に呼び出されるようにします。

private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
        .withConfiguration(AutoConfigurations.of(UserServiceAutoConfiguration.class));
複数の自動構成を定義する必要がある場合、宣言はアプリケーションの実行時とまったく同じ順序で呼び出されるため、宣言を順序付ける必要はありません。

各テストでは、ランナーを使用して特定のユースケースを表すことができます。たとえば、次のサンプルはユーザー構成(UserConfiguration)を呼び出し、自動構成が適切にバックオフすることを確認します。 run を呼び出すと、Assert4Jで使用できるコールバックコンテキストが提供されます。

@Test
void defaultServiceBacksOff() {
    this.contextRunner.withUserConfiguration(UserConfiguration.class).run((context) -> {
        assertThat(context).hasSingleBean(UserService.class);
        assertThat(context).getBean("myUserService").isSameAs(context.getBean(UserService.class));
    });
}

@Configuration(proxyBeanMethods = false)
static class UserConfiguration {

    @Bean
    UserService myUserService() {
        return new UserService("mine");
    }

}

次の例に示すように、Environmentを簡単にカスタマイズすることもできます。

@Test
void serviceNameCanBeConfigured() {
    this.contextRunner.withPropertyValues("user.name=test123").run((context) -> {
        assertThat(context).hasSingleBean(UserService.class);
        assertThat(context.getBean(UserService.class).getName()).isEqualTo("test123");
    });
}

ランナーを使用して ConditionEvaluationReportを表示することもできます。レポートは、INFO または DEBUG レベルで出力できます。次の例は、ConditionEvaluationReportLoggingListener を使用して自動構成テストでレポートを出力する方法を示しています。

@Test
public void autoConfigTest {
    ConditionEvaluationReportLoggingListener initializer = new ConditionEvaluationReportLoggingListener(
            LogLevel.INFO);
    ApplicationContextRunner contextRunner = new ApplicationContextRunner()
            .withInitializer(initializer).run((context) -> {
                    // Do something...
            });
}

28.4.1. Webコンテキストのシミュレーション

サーブレットまたはリアクティブWebアプリケーションコンテキストでのみ動作する自動構成をテストする必要がある場合は、それぞれ WebApplicationContextRunner または ReactiveWebApplicationContextRunner を使用します。

28.4.2. クラスパスのオーバーライド

実行時に特定のクラスやパッケージが存在しない場合に何が起こるかをテストすることもできます。Spring Bootには、ランナーが簡単に使用できる FilteredClassLoader が付属しています。次の例では、UserService が存在しない場合、自動構成が適切に無効になっていると断言します。

@Test
void serviceIsIgnoredIfLibraryIsNotPresent() {
    this.contextRunner.withClassLoader(new FilteredClassLoader(UserService.class))
            .run((context) -> assertThat(context).doesNotHaveBean("userService"));
}

28.5. 独自のスターターを作成する

ライブラリの完全なSpring Bootスターターには、次のコンポーネントが含まれる場合があります。

  • 自動構成コードを含む autoconfigure モジュール。

  • autoconfigure モジュールへの依存関係を提供する starter モジュール、ライブラリ、および通常有用な追加の依存関係。簡単に言うと、スターターを追加すると、そのライブラリの使用を開始するために必要なすべてが提供されます。

これら2つの懸念事項を分離する必要がない場合は、自動構成コードと依存関係管理を単一のモジュールに組み合わせることができます。

28.5.1. ネーミング

スターターに適切な名前空間を提供するようにしてください。別のMaven groupIdを使用している場合でも、モジュール名を spring-bootで始めないでください。将来的に自動構成するものについては、公式サポートを提供する場合があります。

経験則として、組み合わせたモジュールにはスターターにちなんで名前を付ける必要があります。例:「acme」のスターターを作成し、自動構成モジュールに acme-spring-boot-autoconfigure およびスターター acme-spring-boot-starterの名前を付けると仮定します。2つを結合するモジュールが1つしかない場合は、acme-spring-boot-starterという名前を付けます。

28.5.2. 構成キー

スターターが構成キーを提供する場合、それらに固有の名前空間を使用します。特に、Spring Bootが使用するネームスペース( server, management, springなど)にはキーを含めないでください。同じ名前空間を使用する場合、これらの名前空間をモジュールを破壊する方法で将来変更する可能性があります。経験則として、所有する名前空間(たとえば acme)をすべてのキーの前に付けます。

次の例に示すように、プロパティごとにフィールドjavadocを追加して、構成キーがドキュメント化されていることを確認します。

@ConfigurationProperties("acme")
public class AcmeProperties {

    /**
     * Whether to check the location of acme resources.
     */
    private boolean checkLocation = true;

    /**
     * Timeout for establishing a connection to the acme server.
     */
    private Duration loginTimeout = Duration.ofSeconds(3);

    // getters & setters

}
JSONに追加される前に処理されないため、@ConfigurationProperties フィールドJavadocで単純なテキストのみを使用する必要があります。

説明が一貫していることを確認するために、内部で従ういくつかのルールを次に示します。

  • 「The」または「A」で説明を始めないでください。

  • boolean タイプの場合、説明を「Whether」または「Enable」で開始します。

  • コレクションベースのタイプの場合、説明を「カンマ区切りリスト」で開始する

  • long ではなく java.time.Duration を使用し、デフォルトの単位がミリ秒と異なる場合、たとえば「期間サフィックスが指定されていない場合、秒が使用されます」。

  • 実行時に決定する必要がない限り、説明にデフォルト値を指定しないでください。

メタデータ生成をトリガーして、キーでもIDE支援が利用できるようにしてください。生成されたメタデータ(META-INF/spring-configuration-metadata.json)を確認して、キーが適切にドキュメント化されていることを確認してください。互換性のあるIDEで独自のスターターを使用することも、メタデータの品質を検証するための良いアイデアです。

28.5.3. autoconfigure モジュール

autoconfigure モジュールには、ライブラリの使用を開始するために必要なすべてのものが含まれています。また、構成キーの定義( @ConfigurationPropertiesなど)と、コンポーネントの初期化方法をさらにカスタマイズするために使用できるコールバックインターフェースも含まれている場合があります。

ライブラリへの依存関係をオプションとしてマークして、autoconfigure モジュールをプロジェクトに簡単に含めることができるようにする必要があります。そのようにすると、ライブラリは提供されず、デフォルトでSpring Bootはオフに戻ります。

Spring Bootは、アノテーションプロセッサを使用して、メタデータファイル(META-INF/spring-autoconfigure-metadata.properties)の自動構成の条件を収集します。そのファイルが存在する場合、一致しない自動構成を積極的にフィルタリングするために使用され、起動時間が改善されます。自動構成を含むモジュールに次の依存関係を追加することをお勧めします。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-autoconfigure-processor</artifactId>
    <optional>true</optional>
</dependency>

Gradle 4.5以前では、次の例に示すように、compileOnly 構成で依存関係を宣言する必要があります。

dependencies {
    compileOnly "org.springframework.boot:spring-boot-autoconfigure-processor"
}

Gradle 4.6以降では、次の例に示すように、annotationProcessor 構成で依存関係を宣言する必要があります。

dependencies {
    annotationProcessor "org.springframework.boot:spring-boot-autoconfigure-processor"
}

28.5.4. スターターモジュール

スターターは本当に空のjarです。その唯一の目的は、ライブラリを操作するために必要な依存関係を提供することです。それは、始めるために何が必要であるかについての意見に基づく見解と考えることができます。

スターターが追加されるプロジェクトについて想定しないでください。通常、自動構成するライブラリに他のスターターが必要な場合は、それらにもメンションしてください。オプションの依存関係の数が多い場合、ライブラリの通常の使用には不要な依存関係を含めることを避ける必要があるため、適切なデフォルトの依存関係のセットを提供するのは難しい場合があります。つまり、オプションの依存関係を含めないでください。

どちらの方法でも、スターターはコアSpring Bootスターター(spring-boot-starter)を直接または間接的に参照する必要があります(つまり、スターターが別のスターターに依存している場合は追加する必要はありません)。カスタムスターターのみでプロジェクトが作成された場合、Spring Bootのコア機能はコアスターターの存在によって尊重されます。

29. Kotlinサポート

Kotlin(英語) は、JVM(および他のプラットフォーム)を対象とする静的に型付けされた言語で、Javaで記述された既存のライブラリとの相互運用性(英語) を提供しながら、簡潔でエレガントなコードを記述できます。

Spring Bootは、Spring Framework、Spring Data、Reactorなどの他のSpringプロジェクトのサポートを活用することにより、Kotlinサポートを提供します。詳細については、Spring Framework Kotlinサポートドキュメントを参照してください。

Spring BootとKotlinから始める最も簡単な方法は、この包括的なチュートリアルに従うことです。start.spring.io(英語) を介して新しいKotlinプロジェクトを作成できます。サポートが必要な場合は、Kotlin Slack(英語) の#springチャンネルに参加するか、スタックオーバーフロー(英語) spring および kotlin タグで質問してください。

29.1. 要件

Spring BootはKotlin 1.3.xをサポートしています。Kotlinを使用するには、org.jetbrains.kotlin:kotlin-stdlib および org.jetbrains.kotlin:kotlin-reflect がクラスパスに存在する必要があります。 kotlin-stdlib バリアント kotlin-stdlib-jdk7 および kotlin-stdlib-jdk8 も使用できます。

Kotlinクラスはデフォルトでfinal(英語) から、kotlin-spring(英語) プラグインを構成して、Springannotatedクラスを自動的に開いてプロキシ化できるようにすることができます。

JacksonのKotlinモジュール(GitHub) は、KotlinでJSONデータをシリアライズ/デシリアライズするために必要です。クラスパスで見つかると自動的に登録されます。JacksonおよびKotlinが存在するが、Jackson Kotlinモジュールが存在しない場合、警告メッセージがログに記録されます。

これらの依存関係とプラグインは、start.spring.io(英語) でKotlinプロジェクトをブートストラップする場合にデフォルトで提供されます。

29.2. nullセーフ

Kotlinの主要な機能の1つは、null-safety(英語) です。問題を実行時まで延期して NullPointerExceptionを検出するのではなく、コンパイル時に null 値を処理します。これは、Optionalのようなラッパーのコストを支払うことなく、バグの一般的な原因を排除できます。また、Kotlinでは、Kotlinのnullの安全性に関するこの包括的なガイド(英語) で説明されているように、null可能な値を持つ関数構造を使用できます。

Javaでは、型システムでnullセーフを表現することはできませんが、Spring Framework、Spring Data、およびReactorは、ツールに優しいアノテーションを介してAPIのnullセーフを提供するようになりました。デフォルトでは、Kotlinで使用されるJava APIの型(英語) は、nullチェックが緩和されるプラットフォーム型(英語) として認識されます。KotlinによるJSR 305アノテーションのサポート(英語) とNULL可能性アノテーションを組み合わせることにより、Kotlinの関連するSpring APIにNULL安全性が提供されます。

JSR 305チェックは、-Xjsr305 コンパイラフラグに次のオプションを追加することで構成できます。-Xjsr305={strict|warn|ignore}デフォルトの動作は -Xjsr305=warnと同じです。 strict 値は、Spring APIから推測されたKotlinタイプでnullの安全性を考慮に入れる必要がありますが、Spring APIのnull可能性宣言はマイナーリリース間でも発展する可能性があり、今後さらにチェックが追加される可能性があるという知識とともに使用する必要があります)。

ジェネリック型の引数、可変引数、および配列要素のnullabilityはまだサポートされていません。最新情報については、SPR-15942(英語) を参照してください。また、Spring Bootの独自のAPIにはまだアノテーションが付けられていない(GitHub) ことに注意してください。

29.3. Kotlin API

29.3.1. runApplication

Spring Bootは、次の例に示すように、runApplication<MyApplication>(*args) でアプリケーションを実行する慣用的な方法を提供します。

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication

@SpringBootApplication
class MyApplication

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

これは SpringApplication.run(MyApplication::class.java, *args)のドロップイン代替品です。また、次の例に示すように、アプリケーションをカスタマイズできます。

runApplication<MyApplication>(*args) {
    setBannerMode(OFF)
}

29.3.2. 拡張

Kotlin 拡張機能(英語) は、追加機能を使用して既存のクラスを継承する機能を提供します。Spring Boot Kotlin APIは、これらの拡張機能を利用して、既存のAPIに新しいKotlin固有の便利な機能を追加します。

Spring Frameworkの RestOperations に対してSpring Frameworkによって提供されるものと同様のTestRestTemplate 拡張機能が提供されます。特に、拡張機能により、Kotlinの型指定されたパラメーターを利用できるようになります。

29.4. 依存関係の管理

異なるバージョンのKotlin依存関係のクラスパスへの混在を避けるために、Spring BootはKotlin BOMをインポートします。

Mavenでは、kotlin.version プロパティを介してKotlinバージョンをカスタマイズでき、kotlin-maven-pluginのプラグイン管理が提供されます。Gradleでは、Spring Bootプラグインは kotlin.version をKotlinプラグインのバージョンに自動的に合わせます。

Spring Bootは、KotlinコルーチンBOMをインポートすることにより、コルーチンの依存関係のバージョンも管理します。バージョンは、kotlin-coroutines.version プロパティを介してカスタマイズできます。

start.spring.io(英語) に少なくとも1つの事後依存関係があるKotlinプロジェクトをブートストラップする場合、org.jetbrains.kotlinx:kotlinx-coroutines-reactor 依存関係がデフォルトで提供されます。

29.5. @ConfigurationProperties

@ConstructorBinding と組み合わせて使用する場合、@ConfigurationProperties は、次の例に示すように、不変の val プロパティを持つクラスをサポートします。

@ConstructorBinding
@ConfigurationProperties("example.kotlin")
data class KotlinExampleProperties(
        val name: String,
        val description: String,
        val myService: MyService) {

    data class MyService(
            val apiToken: String,
            val uri: URI
    )
}
アノテーションプロセッサーを使用して独自のメタデータを生成するには、kaptspring-boot-configuration-processor 依存関係で構成する必要があります(英語) 。kaptが提供するモデルの制限により、一部の機能(デフォルト値の検出や非推奨のアイテムなど)が機能しないことに注意してください。

29.6. テスト

JUnit 4を使用してKotlinコードをテストすることは可能ですが、JUnit 5はデフォルトで提供されており、推奨されています。JUnit 5では、テストクラスを1回インスタンス化し、クラスのすべてのテストに再利用できます。これにより、非静的メソッドで @BeforeClass および @AfterClass アノテーションを使用できるようになり、Kotlinに適しています。

JUnit 5がデフォルトであり、VintageエンジンはJUnit 4との後方互換性のために提供されています。使用しない場合は、org.junit.vintange:junit-vintage-engineを除外してください。テストインスタンスのライフサイクルを「クラスごと」に切り替える(英語) も必要です。

Kotlinクラスをモックするには、MockK(英語) をお勧めします。Mockito固有の @MockBean および @SpyBean アノテーションに相当する Mockk が必要な場合は、同様の @MockkBean および @SpykBean アノテーションを提供するSpringMockK(GitHub) を使用できます。

29.7. リソース

29.7.2. サンプル

30. 次のステップ

このセクションで説明したクラスについて詳しく知りたい場合は、Spring Boot APIドキュメントをチェックアウトするか、ソースコードを直接(GitHub) 参照できます。特定の質問がある場合は、使い方セクションを参照してください。

Spring Bootのコア機能に慣れている場合は、引き続き本番環境向けの機能について読み進めてください。

Unofficial Translation by spring.pleiades.io. See the original content.