
# 失敗レポート

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

## 使う理由

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

## 例

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

```text
***************************
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` としてログに出されます。

## 独自のアナライザー

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

```dart
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 でログに出されます。[条件](conditions.md#条件評価レポート) を参照してください。

## Spring (Java) との対応

```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 またはコンストラクターの引数です。

## 関連項目

- [SpringApplication](spring-application.md)
- [条件](conditions.md)
- [イベント](events.md)
