失敗レポート

アプリケーションが起動できないとき、spring_boot_dart はスタックトレースの代わりに、何が問題で何をすべきかを示すレポートを出力します。Spring Boot の失敗分析 (failure analysis) に当たります。

使う理由

Bean がない、同じ型の Bean が二つある、プロパティのタイプミス。これらは起動が失敗するよくある理由ですが、コンテナのスタックトレースからはなかなか分かりません。レポートは Bean、キー、ファイルを名指しし、修正方法を提案します。

例

サービスが PaymentGateway を必要としているのに、どこにも宣言されていない場合:

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

Description:

Bean 'checkout' required a bean of type PaymentGateway that could not be found.

Action:

Declare a bean of that type (a @Component class or a @Bean method), check its @Profile / conditions, or make the injection point nullable.

説明される失敗

組み込みの分析は、エラーと、それがラップする原因を、最も内側のものから順に調べます。

失敗 説明 対処
Bean がない Bean 'x' required a bean of type T that could not be found (生成の経路付き) 宣言する、その @Profile や条件を確認する、または注入ポイントを nullable にする
候補が複数ある 名前付きで required a single bean of type T, but 2 were found @Primary、List<T>、または @Qualifier
循環 The dependencies of some of the beans form a cycle: a → b → a 一つの注入ポイントに @Lazy()、ObjectProvider<T>、または 3 つ目の Bean
解決できないプレースホルダー Could not resolve placeholder 'shop.url' 設定ファイル、コマンドライン、変数で定義するか、デフォルトを与える
二重に定義された Bean 名 The bean 'x' ... could not be registered どちらかの名前を変えるか、spring.main.allow-bean-definition-overriding=true
設定ファイルがない Config data resource '...' via location '...' does not exist ロケーションを確認するか、optional: を前に付ける
設定ロケーションがない Config data location '...' does not exist 同上
不正なプロパティ名 不正な文字付きで Configuration property name 'x' is not valid ケバブケース、小文字、英字で始める
不正なプロパティ キーごとに Binding to target properties under 'shop' failed: 設定を修正する
名前が変わったプロパティ 新しい名前付きで These properties have been renamed: 新しい名前を使う
使用中のポート (Web スターター) Web server failed to start. Port 8080 was already in use. 他のプロセスを止めるか、server.port を変える

それ以外の失敗は、エラーとそのスタックトレースとともに Application run failed としてログに出されます。

独自のアナライザー

予測できる形で失敗するライブラリ (到達できないデータベース、ないライセンスキー) は、その失敗を説明できます。

class LicenceFailureAnalyzer implements FailureAnalyzer {
  @override
  FailureAnalysis? analyze(Object failure) => failure is MissingLicenceException
      ? FailureAnalysis(
          'No licence key was found for ${failure.product}.',
          'Set neon.licence.key, or start with the community profile.',
          failure,
        )
      : null;
}

Bean として登録するか (スターターは自動構成に置きます)、SpringApplication(failureAnalyzers: [...]) に渡します。起動が失敗すると:

  1. まずコンストラクターのアナライザーに問い合わせます (どの Bean も存在する前の失敗にも使えます)。
  2. 次に FailureAnalyzer の Bean に @Order の順で問い合わせます (コンテキストがそれらを生成するところまで進んだ場合のみ)。
  3. 最後に組み込みの分析を行います。

最初の null でない答えが報告されます。analyze はスローされたとおりのエラーを受け取ります。Bean の生成中に起きたエラーは BeanCreationException にラップされていることが多いため、必要に応じて cause のチェーンをたどってください。

analyzeFailure(error, analyzers: [...]) は同じ分析を手で実行します。アナライザーをテストしたり、ツールで失敗を同じ形で報告したりするのに使います。

レポートの出力先

設定 レポート
デフォルト spring_boot_dart.diagnostics.LoggingFailureAnalysisReporter のもとに ERROR でログに出される。その他の失敗は spring_boot_dart.SpringApplication のもとに Application run failed として
SpringApplication(out: (line) => ...) 関数に渡される: レポートのテキスト、または Application run failed: <error>

spring_boot_starter_logging がある場合、ロギングシステムは失敗がログに出されるまでインストールされたままなので、レポートはログファイルにも届きます。レポートの後には ApplicationFailedEvent が発行済みで、エラーが再スローされます。

条件評価レポート

自動構成された Bean がなぜあるのか、あるいはないのかを知るには、--debug 付きで起動します。ConditionEvaluationReport (一致したものと一致しなかったもの) が、リフレッシュの後、または起動の失敗の後に INFO でログに出されます。条件 を参照してください。

Spring (Java) との対応

class LicenceFailureAnalyzer extends AbstractFailureAnalyzer<MissingLicenceException> {
  protected FailureAnalysis analyze(Throwable root, MissingLicenceException ex) {
    return new FailureAnalysis("No licence key...", "Set neon.licence.key...", ex);
  }
}
// META-INF/spring.factories

アナライザーは spring.factories のエントリーではなく、Bean またはコンストラクターの引数です。

関連項目