Spring Bootの「自動」を追跡する ― autoconfigurationとActuatorで起動後を観測する

starterを追加したら動いた。しかし、別の依存関係を足したらBeanが二つになった。Spring Bootの自動設定を「便利な魔法」とだけ捉えていると、こうした変化を追えません。

自動設定は、クラスパス、既存Bean、設定値などの条件を見て、必要な構成を追加する仕組みです。この回では、すべての自動設定クラスを読む代わりに、成立した条件と登録結果を観測します。

図は代表的な流れです。設定値条件（@ConditionalOnPropertyなど）は図では省略しているため、実際の条件は--debugかconditionsエンドポイントで確認します。

starterは依存関係の入口

spring-boot-starter-webを追加すると、Spring MVC、JSON変換、組み込みWebサーバーなど、Webアプリに必要な依存関係がまとまって入ります。

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

starter自身がWebサーバーを起動するのではありません。クラスパスに必要なクラスが揃うことで、自動設定の条件が成立します。

`--debug`で条件評価を見る

最初の確認方法は、デバッグモードでの起動です。

java -jar target/order-sample-0.0.1-SNAPSHOT.jar --debug

起動ログにCondition Evaluation Reportが出ます。見る場所は二つです。

Positive matches：条件が成立した自動設定
Negative matches：成立しなかった自動設定（ログには他にExclusions・Unconditional classesも出ます。詳細はconditionsエンドポイントのpositiveMatches / negativeMatches / unconditionalClassesで確認します）

ログ全体を上から暗記する必要はありません。問題になっている機能名、たとえばDataSourceやWebMvcで検索し、「どの条件が成立しなかったか」を読みます。

Spring Boot 3.5.16の検証プロジェクトでDataSourceを検索すると、次のように出ます（Java 25.0.3で確認）。

Positive matches:
-----------------

   DataSourceAutoConfiguration matched:
      - @ConditionalOnClass found required classes 'javax.sql.DataSource', 'org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseType' (OnClassCondition)

   DataSourceConfiguration.Hikari matched:
      - @ConditionalOnClass found required class 'com.zaxxer.hikari.HikariDataSource' (OnClassCondition)
      - @ConditionalOnProperty (spring.datasource.type=com.zaxxer.hikari.HikariDataSource) matched (OnPropertyCondition)
      - @ConditionalOnMissingBean (types: javax.sql.DataSource; SearchStrategy: all) did not find any beans (OnBeanCondition)

Negative matches:
-----------------

   DataSourceConfiguration.Tomcat:
      Did not match:
         - @ConditionalOnClass did not find required class 'org.apache.tomcat.jdbc.pool.DataSource' (OnClassCondition)

   DataSourceConfiguration.Dbcp2:
      Did not match:
         - @ConditionalOnClass did not find required class 'org.apache.commons.dbcp2.BasicDataSource' (OnClassCondition)

読み方はこうです。DataSourceConfiguration.HikariがPositiveなのは、クラスパスにHikariDataSourceがあり、他のDataSource Beanがまだ無いから。DataSourceConfiguration.Tomcatと.Dbcp2がNegativeなのは、対応するプール実装のクラスがクラスパスに無いからです。コネクションプールをHikariCPからTomcatへ変えたいなら、依存関係を足すだけでは足りません。既存のHikariCP依存を除外しないと、@ConditionalOnMissingBeanでTomcat側が後退したままになります。

Actuatorで起動後の状態を見る

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

確認用に公開するエンドポイントを限定します。

management.endpoints.web.exposure.include=health,conditions,mappings
management.endpoint.health.show-details=when-authorized

curl.exe http://localhost:8080/actuator/health
curl.exe http://localhost:8080/actuator/conditions
curl.exe http://localhost:8080/actuator/mappings

エンドポイント	確認すること
`health`	集約statusがUPか（未認証では詳細・コンポーネントは出ない）
`conditions`	どの自動設定条件が一致・不一致だったか
`mappings`	`/orders`などがどのControllerメソッドへ割り当てられたか

conditionsのJSONでは、対象の自動設定名を検索し、positiveMatches / negativeMatches（negative側はnotMatched・matched配列）のメッセージを読みます。mappingsでは、期待したURLとHTTPメソッドが登録されているかを確認します。

Spring Boot 3.5.16の検証プロジェクトでは、次の最小応答を確認しました。

{"status":"UP"}

未認証アクセスのため詳細・コンポーネントは出ず、集約statusのみが返ります。認証済みなら詳細が出ます。mappingsには/orders/ping、/orders/{orderId}、POST /ordersが登録されていました。conditionsには成立・不成立の双方が含まれます。出力は大きいので、記事や問い合わせへ丸ごと貼らず、対象の自動設定名へ絞ります。

Actuatorは、公開範囲を決めてから使います

conditionsやmappingsは内部構成を示します。インターネットへ無条件に公開するものではありません。管理ネットワーク、認証、公開エンドポイントの限定を設計してください。

自動設定を上書きする前に確認する

Spring Bootでは、@ConditionalOnMissingBeanを使う自動設定において、利用者が自分のBeanを定義すると既定の自動設定が後退します。期待と違うときに、すぐBeanを追加すると二重定義や設定競合を招きます。

starterと依存関係を確認する
--debugまたはconditionsで条件を見る
既存Beanと設定値を確認する
そのうえで必要な部分だけ明示設定する

この順番なら、「何となく設定クラスを追加したら直った」から抜けられます。

実務ではこうなる

自動設定の不具合に見えて、実際は利用者が定義したBeanによって既定構成が後退していることがあります。設定クラスを追加した時点の差分、conditionsのnotMatched理由、Bean名をセットで確認します。

ActuatorのHealthも、すべてを一つのUPへ押し込めばよいわけではありません。外部通知サービスが一時停止しただけで注文APIまで再起動すべきか、注文を受け付けてよいかは別の判断です。第9回でlivenessとreadinessを分けます。

conditionsやmappingsは内部構成を多く含むため、本番で公開する場合は管理ポートの分離、認証、ネットワーク制限を組み合わせます。障害時だけ一時的に露出する運用でも、誰がいつ変更し、戻したかを記録します。

公式リファレンス

参考文献・参照資料

Somnath Musib, Spring Boot in Practice, Manning, ISBN 9781617298813：第4章のautoconfigurationとActuatorを参照。
Mark Heckler, Spring Boot：立ち上げて実行する、ISBN 9798341626911（AI翻訳版）：第5章の設定とアプリケーション状態の調査を補助参照。

書籍のコード・出力例は転載せず、Spring Boot 3.5.16の注文受付サンプルで実行結果を取り直しました。

次回は、単体テスト、スライステスト、全体テストを「何を保証するか」で分けます。

シリーズ内リンク