Читаємо auto-config і imports-файли

1. Сенс читання auto-config

Коли Spring Boot працює «як треба», він здається магічним. А коли поведінка розходиться з очікуванням, хочеться швидко зрозуміти три речі: хто створив цей bean, за якої умови вмикнувся цей блок і який важіль тут узагалі доречний — property, власний bean або exclusion. Добра новина: auto-configuration — це не чаклунство, а звичайні Java-класи з умовами.

Вихідні тексти auto-config корисно відкривати не заради героїчного занурення в джерельний код, а заради дуже практичного завдання: обрати мінімальне втручання. Іноді достатньо змінити property. Іноді потрібен власний bean, щоб Boot відступив. А іноді виявляється, що проблема справді в усьому блоці auto-config.

Потрібен спокійний і повторюваний алгоритм: від «дивної поведінки» дійти до конкретного auto-config класу, зрозуміти, які умови його вмикнули, і вибрати найменше втручання: property, власний bean або (у рідкісних випадках) exclusion. І читати вихідні тексти можна без болю, якщо знати, куди дивитися і де зупинитися, щоб не провалитися в нескінченне занурення в джерельний код.

Component scanning і auto-configuration imports

Дуже часта помилка початківця — думати, що Spring «усе знаходить скануванням пакетів». Так, ваші @Component, @Service, @Controller (коли вони з’являться) справді живуть у світі component scanning. Але auto-configuration живе в іншому світі: Spring Boot імпортує спеціальні конфігураційні класи із залежностей заздалегідь підготовленим списком. Тому шукати auto-config через «а в якому пакеті це просканувалося?» — усе одно що шукати кота в холодильнику: можливо, ви його там колись і замикали, але зазвичай коти там не живуть.

Давайте порівняємо це в одній табличці — вона справді допомагає тримати в голові картину, коли ви відкриваєте проєкт через тиждень і намагаєтеся згадати, «хто тут головний».

Якщо втримати це в голові, ви перестаєте «вгадувати» і починаєте діагностувати. А вгадувати в Spring Boot — заняття невдячне, бо Boot пам’ятає всі залежності на classpath краще, ніж ми.

2. Imports-файл AutoConfiguration.imports

Коли кажуть «Boot підключає auto-config», корисно мати конкретний образ. Це не містична телепортація, а читання звичайного текстового файла всередині jar-архіву. У Spring Boot 4 (як і в попередніх сучасних версіях) основний список кандидатів на auto-configuration зберігається в ресурсі: META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports.

Формат простий: по одному рядку — повне ім’я класу. Boot читає ці рядки, отримує список кандидатів і далі застосовує умови (@Conditional...), щоб зрозуміти, що реально вмикати. Тобто imports-файл відповідає на запитання: «які auto-config класи взагалі розглядаються?» — ще до того, як почнеться магія умов.

Візьмемо той самий фрагмент застосунку startup-support: StartupMessageFormatter, StartupSummaryRunner і auto-config навколо них. Невеликий навчальний приклад imports-файла (сильно скорочений, щоб мозок не втік):

com.example.catalogservice.support.startup.StartupSupportAutoConfiguration
com.example.catalogservice.support.startup.StartupReportAutoConfiguration

Важливо, що це не component scanning. Ці класи не зобов’язані лежати у ваших пакетах. Вони можуть приїхати з будь-якої залежності — хоч зі spring-boot-autoconfigure, хоч зі стороннього starterʼа.

Пошук imports-файла в IDE і терміналі

Коли ви чуєте «відкрий jar і знайди всередині META-INF/...», хочеться зробити вигляд, що у вас терміново вимкнули інтернет і ви йдете в ліс. На практиці все простіше: IDE уміє відкривати вміст залежностей, а термінал уміє показувати список файлів усередині jar.

Якщо ви в IntelliJ IDEA, найчастіше досить відкрити External Libraries, знайти spring-boot-autoconfigure-..., розкрити його як папку і пройти шляхом META-INF/spring/.... Це виглядає майже як звичайна файлова система. Нічого страшного — jar по суті і є zip із класами та ресурсами.

Якщо ви більше дружите з терміналом, то мінімальна команда має такий вигляд (приклад для Linux/macOS, концептуально):

# Показати список файлів усередині jar (без розпаковування)
jar tf ~/.gradle/caches/.../spring-boot-autoconfigure-4.0.3.jar \
  | grep "AutoConfiguration.imports"

А щоб подивитися вміст конкретного файла, зазвичай роблять jar xf (витягнути) або використовують unzip -p. Тут я не буду завалювати вас «командною магією» — думка важливіша за команду: imports-файл — це звичайний ресурс усередині jar. Його можна відкрити й прочитати як текст.

3. Алгоритм читання auto-config

Якщо підійти до auto-config як до роману на 900 сторінок — ви програєте. Якщо підійти як інженер із запитанням і коротким чек-листом — ви виграєте. Нижче — робочий алгоритм, який добре лягає на реальність Junior-розробника і не вимагає «розуміти весь Spring».

Якщо хочеться зовсім коротко, то це можна запам’ятати як: хто → чому → де відступає → чим керується.

4. Читання auto-config зверху вниз

Головна порада для читання auto-config: не починайте із середини. Починайте з анотацій класу й перших рядків — там зазвичай лежить «правило вмикання». Лише потім спускайтеся до @Bean методів. Це як читати договір: спочатку дізнаємося, що ви взагалі підписали, а потім уже вивчаємо пункт 7.4.12 про штраф за пізню доставку.

Ось мінімальний навчальний auto-config, який зручно читати (він схожий на реальні, але не перевантажений деталями):

package com.example.catalogservice.support.startup;

import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;

// Цей клас бере участь у механізмі Spring Boot auto-configuration
@AutoConfiguration
// Увімкнути конфігурацію лише тоді, коли потрібний клас справді є на classpath
@ConditionalOnClass(StartupMessageFormatter.class)
public class StartupSupportAutoConfiguration {

    @Bean
    // Boot «відступає», якщо ви оголосили власний bean такого типу
    @ConditionalOnMissingBean
    StartupMessageFormatter startupMessageFormatter() {
        // Реалізація за замовчуванням: просте форматування повідомлення
        return appName -> "Запущено: " + appName;
    }
}

Тут «зверху вниз» читається буквально як людський текст. Спочатку ми бачимо, що це @AutoConfiguration, отже клас бере участь у механізмі auto-configuration. Потім бачимо @ConditionalOnClass(StartupMessageFormatter.class) — тобто цей блок має сенс лише тоді, коли такий клас узагалі є на classpath. І лише потім доходимо до @Bean, який створюється, лише якщо в застосунку немає іншого StartupMessageFormatter (@ConditionalOnMissingBean).

Найкорисніше, що ви можете винести з читання подібних класів: Boot майже завжди прямо каже, де він відступить. Якщо ви бачите @ConditionalOnMissingBean, це часто означає: «хочеш по-своєму — оголоси власний bean».

5. Мінікейс: форматування стартового повідомлення

Візьмемо той самий фрагмент застосунку startup-support. Контракт тут той самий: StartupMessageFormatter — інтерфейс із методом format(String appName). А прикладний код залежить від нього через StartupSummaryRunner.

package com.example.catalogservice.catalog.bootstrap;

import com.example.catalogservice.support.startup.StartupMessageFormatter;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.stereotype.Component;

@Component
public class StartupSummaryRunner implements ApplicationRunner {

    // Залежність від абстракції: реалізація може прийти з auto-config
    private final StartupMessageFormatter formatter;

    public StartupSummaryRunner(StartupMessageFormatter formatter) {
        // Інжектуємо bean через конструктор (так простіше тестувати і читати)
        this.formatter = formatter;
    }

    @Override
    public void run(ApplicationArguments args) {
        // У реальному проєкті тут частіше буде логер, але для прикладу достатньо println
        System.out.println(formatter.format("catalog-service"));
        // Очікуваний вивід (якщо активувалася типова реалізація):
        // Запущено: catalog-service
    }
}

Якщо ви не створювали StartupMessageFormatter явно, то логічне запитання: «хто його створив?». І ось тут ми перестаємо гадати і переходимо до алгоритму.

Ми дивимося на тип: StartupMessageFormatter. Далі в нас два реалістичні сценарії. Або це наш код (і тоді ми легко знайдемо, де його створюють), або він приїхав з auto-config (наприклад, ви підключили бібліотеку чи стартер, або у вас є внутрішній модуль). Тоді ми шукаємо auto-config клас, який створює bean цього типу. У навчальному прикладі це StartupSupportAutoConfiguration.

Наступне запитання: «як цей auto-config узагалі підключився?». Відповідь: через imports-файл усередині jar, де перелічено StartupSupportAutoConfiguration. Тобто ми читаємо не «магічну реальність», а конкретний ланцюжок: imports → auto-config клас → @Conditional... → @Bean.

6. Читання auto-config як шлях до рішення

Дуже типова пастка початківця — відкрити auto-config клас, побачити всередині двадцять рядків і почати читати кожен як священне писання. У результаті мозок перегрівається, а рішення все ще немає. Щоб цього уникнути, корисно тримати в голові «запитання-фільтри», які ви ставите коду.

Їх зручно тримати прямо у вигляді короткого коментаря (це не список у сенсі «давайте випишемо 40 пунктів», а радше шпаргалка, яку можна повторювати як мантру):

// Швидке читання auto-config:
// 1) Що це за блок і як він називається?
// 2) За якими умовами він узагалі вмикається?
// 3) Який bean він створює (тип важливіший за імʼя)?
// 4) Де він відступає (OnMissingBean / OnProperty)?
// 5) Що менше за масштабом: property, власний bean чи exclude?

Якщо ви відповідаєте на ці 5 запитань, то майже завжди знаходите нормальний шлях кастомізації без «захоплення фреймворком». І це якраз і є доросла мета: не стати людиною, яка в будь-якій незрозумілій ситуації пише exclude = Everything.class.

7. @ConditionalOnProperty як перемикач

Друга золота анотація для читання — @ConditionalOnProperty. Вона зазвичай означає: «цю поведінку можна вмикати або вимикати налаштуванням». Тобто замість того, щоб писати власний bean або виключати auto-config, ви можете просто задати property. Це майже завжди найдешевший спосіб.

У тому самому шарі startup-support можна зустріти й інший важіль: bean не замінюється своїм, а вмикається і вимикається property. Навчальний приклад:

package com.example.catalogservice.support.startup;

import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;

@AutoConfiguration
public class StartupReportAutoConfiguration {

    @Bean
    @ConditionalOnProperty(
            // Імʼя властивості, яке керує вмиканням біна
            name = "app.catalog.startup-report-enabled",
            // Увімкнути бін лише за явного значення "true"
            havingValue = "true",
            // Якщо властивості немає, вважаємо, що вона true (поведінка "увімкнено за замовчуванням")
            matchIfMissing = true
    )
    StartupReportSink startupReportSink() {
        // Типовий sink: просто друкуємо повідомлення (у реальному світі буде логер/метрики)
        return message -> System.out.println(message); // аудит
    }
}

Читаємо це так: «створи StartupReportSink, якщо властивість app.catalog.startup-report-enabled дорівнює true; якщо властивості немає — вважай, що вона true». Важливо, що тут уже видно рішення: якщо ви хочете вимкнути звіт — не потрібно виключати auto-config. Достатньо поставити app.catalog.startup-report-enabled=false у application.yaml.

Так, ми ще не в модулі externalized configuration і не підемо в precedence та профілі. Але вже зараз видно: вихідні тексти auto-config прямо показують вам «ручку керування». І це дуже Boot-центричний спосіб мислення: спочатку шукаємо готовий перемикач, а вже потім ліземо в зв’язування.

8. Auto-config із чужих залежностей

Іноді ви відкриваєте клас в IDE, а там «decompiled code», і все виглядає так, ніби його писав робот, який ненавидить людей. Нормальна ситуація: вихідні тексти залежностей можуть не завантажитися автоматично. У більшості IDE є дія на кшталт “Download Sources” для Gradle-залежностей. Після цього auto-config класи стають читабельними, і життя поліпшується.

Якщо вихідних текстів усе одно немає, у вас залишаються два безпечні шляхи. Перший — дивитися на анотації та сигнатури методів навіть у декомпільованому вигляді: @ConditionalOnMissingBean і тип поверненого значення видно майже завжди. Другий — у крайньому разі не читати весь клас, а знайти поруч клас *Properties (або хоча б зрозуміти ім’я property зі @ConditionalOnProperty) і використовувати це як «ручку» поведінки.

Сенс у тому, що навіть без ідеальних вихідних текстів вам достатньо зрозуміти дві речі: який тип bean створюється і за яких умов. Цього вистачає, щоб ухвалити рішення «власний bean vs property vs exclude». А внутрішнє налаштування конкретної бібліотеки (з її 300 опціями) майже завжди виходить за межі завдання дня.

9. Типові помилки під час читання auto-config

Помилка №1: плутати imports-файл із component scanning.
Початківець бачить, що auto-config клас лежить у якомусь пакеті, і починає шукати, чому цей пакет «сканується». У результаті він змінює @ComponentScan, рухає main-клас, і проєкт стає ще дивнішим. Правильна модель інша: auto-config береться з imports-файла, а не зі сканування.

Помилка №2: читати auto-config «із середини», пропускаючи умови класу.
Дуже легко відкрити клас, промотати вниз до @Bean і почати розбирати, що там створюється. Але умови на рівні класу можуть повністю пояснити, чому цей блок узагалі вмикнувся (наприклад, через наявність певного класу на classpath). Якщо пропустити верх, ви ризикуєте вирішити не ту проблему.

Помилка №3: «потонути в деталях» усередині @Bean методу.
У реальному Boot-коді @Bean методи іноді виглядають громіздко: там створюються builder-и, підмішуються properties, ідуть optional-гілки. Початківець намагається зрозуміти все, включно з кожним if. На рівні курсу вам зазвичай достатньо зрозуміти тип створюваного bean, ключові умови (OnMissingBean, OnProperty) і місце, де Boot дає вам точку підміни.

Помилка №4: побачити @ConditionalOnProperty і все одно зробити exclusion.
Це класика: у вас є готовий вимикач поведінки, але ви вимикаєте весь блок через exclude, а потім дивуєтеся, що разом із ним зникло ще щось корисне. Якщо є property — майже завжди починайте з нього, бо це мінімальне втручання.

Помилка №5: зробити висновок «Boot — магія», замість висновку «у Boot є правила».
Найшкідливіша думка після читання вихідних текстів — «там усе занадто складно, я нічого не розумію». Корисніша думка — «я бачу правила вмикання і бачу точки відступу». Вам не потрібно розуміти весь фреймворк, щоб зрозуміти, чому з’явився конкретний bean і як його замінити. Це як з автомобілем: щоб замінити колесо, не треба знати термодинаміку двигуна.