失敗レポート
アプリケーションが起動できないとき、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: [...]) に渡します。起動が失敗すると:
- まずコンストラクターのアナライザーに問い合わせます (どの Bean も存在する前の失敗にも使えます)。
- 次に
FailureAnalyzerの Bean に@Orderの順で問い合わせます (コンテキストがそれらを生成するところまで進んだ場合のみ)。 - 最後に組み込みの分析を行います。
最初の 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 またはコンストラクターの引数です。