サンプルコードで身につける: 自動構成は候補を条件でふるいにかける

解説で学んだ概念を、5つの具体例で確認します。素朴な例から実務寄りの例へと進みます。

1素の Java で条件つき登録を真似る

候補の一覧を回し、があるか、同じ型のがまだ無いかを調べて登録するだけのプログラムです。は使っていません。自分で List の Bean を先に入れておくと、候補のほうは登録されずに引っ込みます。がやっていることの骨組みはこの形です。

Java

import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.function.Supplier;

// 自動構成の「候補」1件ぶん。条件2つと、Bean の作り方を持つ
record Candidate(String name, String requiredClass, Class<?> beanType, Supplier<Object> factory) {}

class Main {
    // @ConditionalOnClass に当たる判定: その名前のクラスがクラスパスにあるか
    static boolean classPresent(String className) {
        try {
            Class.forName(className, false, Main.class.getClassLoader());
            return true;
        } catch (ClassNotFoundException e) {
            return false;
        }
    }

    // @ConditionalOnMissingBean に当たる判定: 同じ型の Bean がまだ無いか
    static boolean beanMissing(Map<String, Object> beans, Class<?> type) {
        return beans.values().stream().noneMatch(type::isInstance);
    }

    static void start(String label, Map<String, Object> userBeans) {
        // imports ファイルに当たる「候補の一覧」
        List<Candidate> candidates = List.of(
                new Candidate("listAutoConfiguration", "java.util.ArrayList", List.class, ArrayList::new),
                new Candidate("pdfAutoConfiguration", "com.example.pdf.PdfWriter", Object.class, Object::new));

        Map<String, Object> beans = new LinkedHashMap<>(userBeans); // 自分で定義した Bean が先
        System.out.println("--- " + label);
        for (Candidate c : candidates) {
            if (!classPresent(c.requiredClass())) {
                System.out.println(c.name() + ": did not match (class not found: " + c.requiredClass() + ")");
            } else if (!beanMissing(beans, c.beanType())) {
                System.out.println(c.name() + ": did not match (bean of type " + c.beanType().getSimpleName() + " already defined)");
            } else {
                beans.put(c.name(), c.factory().get());
                System.out.println(c.name() + ": matched");
            }
        }
        System.out.println("beans = " + beans.keySet());
    }

    public static void main(String[] args) {
        start("no user beans", Map.of());
        start("user defines a List bean", Map.of("myList", new ArrayList<String>()));
    }
}

import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.function.Supplier;

// 自動構成の「候補」1件ぶん。条件2つと、Bean の作り方を持つ
record Candidate(String name, String requiredClass, Class<?> beanType, Supplier<Object> factory) {}

class Main {
    // @ConditionalOnClass に当たる判定: その名前のクラスがクラスパスにあるか
    static boolean classPresent(String className) {
        try {
            Class.forName(className, false, Main.class.getClassLoader());
            return true;
        } catch (ClassNotFoundException e) {
            return false;
        }
    }

// @ConditionalOnMissingBean に当たる判定: 同じ型の Bean がまだ無いか
    static boolean beanMissing(Map<String, Object> beans, Class<?> type) {
        return beans.values().stream().noneMatch(type::isInstance);
    }

static void start(String label, Map<String, Object> userBeans) {
        // imports ファイルに当たる「候補の一覧」
        List<Candidate> candidates = List.of(
                new Candidate("listAutoConfiguration", "java.util.ArrayList", List.class, ArrayList::new),
                new Candidate("pdfAutoConfiguration", "com.example.pdf.PdfWriter", Object.class, Object::new));

Map<String, Object> beans = new LinkedHashMap<>(userBeans); // 自分で定義した Bean が先
        System.out.println("--- " + label);
        for (Candidate c : candidates) {
            if (!classPresent(c.requiredClass())) {
                System.out.println(c.name() + ": did not match (class not found: " + c.requiredClass() + ")");
            } else if (!beanMissing(beans, c.beanType())) {
                System.out.println(c.name() + ": did not match (bean of type " + c.beanType().getSimpleName() + " already defined)");
            } else {
                beans.put(c.name(), c.factory().get());
                System.out.println(c.name() + ": matched");
            }
        }
        System.out.println("beans = " + beans.keySet());
    }

public static void main(String[] args) {
        start("no user beans", Map.of());
        start("user defines a List bean", Map.of("myList", new ArrayList<String>()));
    }
}

2imports ファイルの実物

の中の spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports の全文を2つ並べました(# の行は見出しとして足したもの)。中身は構成クラスの名前が1行に1つあるだけです。4.1.1 ではこのファイルが JAR ごとにあり、だけのでは6つの JAR に合計 30 行でした。

AutoConfiguration.imports(Spring Boot 4.1.1)設定ファイル

# spring-boot-webmvc-4.1.1.jar(6行)
org.springframework.boot.webmvc.autoconfigure.DispatcherServletAutoConfiguration
org.springframework.boot.webmvc.autoconfigure.WebMvcAutoConfiguration
org.springframework.boot.webmvc.autoconfigure.WebMvcObservationAutoConfiguration
org.springframework.boot.webmvc.autoconfigure.actuate.endpoint.web.WebMvcHealthEndpointExtensionAutoConfiguration
org.springframework.boot.webmvc.autoconfigure.actuate.web.mappings.WebMvcMappingsAutoConfiguration
org.springframework.boot.webmvc.autoconfigure.error.ErrorMvcAutoConfiguration
 
# spring-boot-jackson-4.1.1.jar(1行)
org.springframework.boot.jackson.autoconfigure.JacksonAutoConfiguration

3条件評価レポートを読む

を付けて起動すると出るレポートの抜粋です。Positive matches には通った条件とその理由が、Negative matches には通らなかった理由が出ます。JacksonAutoConfiguration は JsonMapper のクラスが見つかったので通り、CBOR や XML 用の入れ子の構成は必要なクラスが無いので外れています。この最小アプリでは Positive が 52 件、Negative が 39 件でした。

java ... l17.plain.PlainApp --debug(Jackson の周辺だけ抜粋)コマンド出力

============================
CONDITIONS EVALUATION REPORT
============================
 
 
Positive matches:
-----------------
 
   ...
   JacksonAutoConfiguration matched:
      - @ConditionalOnClass found required class 'tools.jackson.databind.json.JsonMapper' (OnClassCondition)
 
   JacksonAutoConfiguration#jacksonJsonMapper matched:
      - @ConditionalOnMissingBean (types: tools.jackson.databind.json.JsonMapper; SearchStrategy: all) did not find any beans (OnBeanCondition)
   ...
 
Negative matches:
-----------------
 
   ...
   JacksonAutoConfiguration.CborConfiguration:
      Did not match:
         - @ConditionalOnClass did not find required class 'tools.jackson.dataformat.cbor.CBORMapper' (OnClassCondition)
 
   JacksonAutoConfiguration.XmlConfiguration:
      Did not match:
         - @ConditionalOnClass did not find required class 'tools.jackson.dataformat.xml.XmlMapper' (OnClassCondition)
   ...

4自分で Bean を定義する前と後の diff

JsonMapper の Bean を自分で定義する前(<)と後(>)で、レポートを比べた結果です。jacksonJsonMapper が Positive 側から消えて Negative 側に移り、理由が did not find any beans から found beans ... myJsonMapper に変わっています。件数の差も 52→51、39→40 のこの1件だけでした。リファレンスはこの性質を、自動構成は non-invasive(押しつけない)と表現しています。

$ diff(定義前のレポート定義後のレポート)コマンド出力

70,72d69
<    JacksonAutoConfiguration#jacksonJsonMapper matched:
<       - @ConditionalOnMissingBean (types: tools.jackson.databind.json.JsonMapper; SearchStrategy: all) did not find any beans (OnBeanCondition)
<
85c82
<       - @ConditionalOnBean (types: tools.jackson.databind.json.JsonMapper; SearchStrategy: all) found bean 'jacksonJsonMapper' (OnBeanCondition)
---
>       - @ConditionalOnBean (types: tools.jackson.databind.json.JsonMapper; SearchStrategy: all) found bean 'myJsonMapper' (OnBeanCondition)
201a199,202
>
>    JacksonAutoConfiguration#jacksonJsonMapper:
>       Did not match:
>          - @ConditionalOnMissingBean (types: tools.jackson.databind.json.JsonMapper; SearchStrategy: all) found beans of type 'tools.jackson.databind.json.JsonMapper' myJsonMapper (OnBeanCondition)

5依存を足すと候補そのものが増える

web だけのプロジェクトと、data-jpa と h2 を足したプロジェクトで、imports ファイルの行数を JAR ごとに数えた表です。DataSourceAutoConfiguration は spring-boot-jdbc の JAR の imports に載っているので、web だけのほうでは --debug の出力にその名前が1回も出ません。条件で外れたのではなく、候補に入っていないということです。

AutoConfiguration.imports の行数(Spring Boot 4.1.1)表