Виключення: вимикаємо автоконфігурацію

1. Виключення — це не «налаштування», а вимикач

Зазвичай розробник-початківець починає налаштовувати Boot із внутрішньої фрази: «Схоже, він робить якусь магію… Вимкну-но я її». І рука тягнеться до exclude, бо все виглядає просто: написав один рядок — і «зайве» зникає. Проблема в тому, що exclude — це не косметика, а сокира.

Важлива думка: виключення вимикає не конкретний бін, а цілий клас автоконфігурації. А клас автоконфігурації — це, по суті, «пакунок рішень»: кілька @Bean-методів, умови, інколи — імпорти інших конфігурацій. Тобто ви вимикаєте не лампочку, а висмикуєте запобіжник, який живить половину кімнати. У побутовому сенсі це інколи дуже корисно. В інженерному — завжди ризик, бо ви грубо змінюєте збирання застосунку.

Після точкової підміни одного біну й невеликих тематичних @Configuration природно виникає наступний за силою інструмент — виключення. До нього варто тягнутися не тоді, коли дратує один компонент, а тоді, коли цілий блок автоконфігурації справді не має брати участі в збиранні застосунку.

У контексті нашого catalog-service це виглядає так. Якщо ми хочемо замінити один інфраструктурний компонент (наприклад, форматувач стартового повідомлення або умовного «репортера старту»), майже завжди правильніше зробити це через власний бін або через умову за властивістю. Виключення ж стає виправданим лише тоді, коли ви можете чесно сказати: «Цей цілий блок поведінки нам узагалі не потрібен, і ми точно розуміємо наслідки».

2. Що відбувається в Boot під час exclude

Щоб не сприймати exclude як заклинання, корисно уявляти, на якому етапі Boot його застосовує. І тут хороша новина: жодної містики, просто етап збирання. Boot спочатку збирає список кандидатів на автоконфігурацію, а потім вирішує, які з них справді вмикати, залежно від умов. Виключення втручається дуже рано — ще до того, як починають діяти умови.

На «людському» рівні це можна уявити так:

flowchart TD
    A["Classpath + файл imports
список кандидатів на автоконфігурацію"] --> B["Застосовуємо exclude
(анотація та/або властивості)"]
    B --> C["Оцінюємо умови
@ConditionalOnClass/@ConditionalOnProperty/..."]
    C --> D["Реєструємо @Bean
в ApplicationContext"]

Тобто виключення — це команда: «Не розглядай цей клас автоконфігурації взагалі». У результаті для виключеного класу не виконуються навіть його умови (їх просто не перевірятимуть), і його @Bean-методи не потраплять у контекст.

Це важливо з двох причин. По-перше, коли ви виключаєте автоконфігурацію, ви втрачаєте не лише конкретний незручний бін, а й усі інші, які цей клас міг створити «заодно». По-друге, інші класи автоконфігурації часто пишуться з логікою «якщо в контексті є X, тоді налаштуємо Y». Якщо ви вимкнули блок, який створював X, то Y теж може не піднятися. Причому не обов’язково з помилкою — інколи просто «тихо не ввімкнеться».

Тому виключення не можна сприймати як «видалити один зайвий компонент». Це більше схоже на «прибрати цілу коробку деталей із набору LEGO, а потім дивуватися, чому дах не тримається».

3. exclude, свій бін і @ConditionalOnProperty

Перед тим як узагалі обговорювати «коли виправдано вимикати», корисно вибудувати в голові шкалу сили інструментів. У Spring Boot є кілька способів вплинути на поведінку, і вони відрізняються масштабом дії. Якщо вибрати занадто сильний інструмент для маленького завдання, ви отримаєте крихкий проєкт, який складно пояснювати й підтримувати.

Порівняймо три найчастіші важелі (у таблиці — без фанатизму, лише на рівні курсу):

Якщо перекласти це на просте правило (без списків, але з ідеєю): починайте з найменшого втручання. Якщо завдання можна розв’язати властивістю — розв’язуйте властивістю. Якщо треба замінити один компонент — створіть свій бін. І тільки якщо ви чесно розумієте, що цілий блок автоконфігурації вам не потрібен, тоді exclude стає варіантом.

Невелика «блок-схема вибору» теж допомагає голові не панікувати:

flowchart TD
    A["Мене не влаштовує поведінка Boot"] --> B{"Це один бін
чи цілий блок?"}
    B -->|Один бін| C{"Можна оголосити свій бін?"}
    C -->|Так| D["Створюємо свій бін
Boot відступає"]
    C -->|Ні| E["Шукаємо властивість/налаштування"]
    B -->|Цілий блок| F{"Блок справді не потрібен
і ми розуміємо наслідки?"}
    F -->|Ні| G["Спочатку розберіться, що саме ввімкнулося
(залежність? умова?)"]
    F -->|Так| H["Робимо exclude
точково й усвідомлено"]

У цій лекції ми якраз про нижню гілку — коли блок справді не потрібен.

4. Виключення в реальному житті: три сценарії

Зараз буде важливий момент: виключення — не «погана практика» саме по собі. Це просто потужний інструмент. Проблеми починаються, коли його застосовують не за призначенням. Щоб у вас не було відчуття «ну тоді взагалі не можна», розберімо кілька сценаріїв, де виключення справді трапляється в реальному житті — і виглядає логічним навіть для початківця.

Сценарій A: у проєкт випадково підтягнулася підсистема

Класика жанру: ви додали залежність «заради однієї дрібниці», а разом із нею підтягнулася ціла підсистема. Boot її побачив на classpath, умови збіглися — і автоконфігурація почала намагатися підняти інфраструктуру, яка вашому сервісу взагалі не потрібна.

На практиці це часто виглядає так: застосунок стартує і раптово падає з помилкою, схожою на цю (формулювання може відрізнятися, але зміст упізнаваний):

Failed to configure a DataSource: 'url' attribute is not specified
and no embedded datasource could be configured.

Для catalog-service це особливо показово, бо за ТЗ проєкту в нас немає бази даних. Отже, якщо Boot узагалі почав намагатися налаштовувати DataSource, це майже напевно симптом того, що в дереві залежностей зʼявилися JDBC- або JPA-залежності.

Що робити правильно? В ідеальному світі — повернутися до build.gradle.kts і розібратися, хто приніс цю залежність, а потім видалити або замінити її. Але бувають ситуації, коли ви не можете легко прибрати бібліотеку (наприклад, вона потрібна заради іншого функціоналу, а JDBC підтягнувся транзитивно). І ось тоді виключення стає тимчасовим заглушувальним рішенням, щоб сервіс бодай стартував.

Приклад (показовий, не означає «робіть так завжди»):

package com.example.catalogservice;

import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;

@SpringBootApplication(exclude = DataSourceAutoConfiguration.class) // Вимикаємо цілу автоконфігурацію джерела даних
public class CatalogServiceApplication {
    // Важливо: це НЕ "видалити один бін", а вимкнути весь блок, який піднімає DataSource та пов'язану з ним поведінку.
    // Тримайте в голові запитання: чому JDBC взагалі опинився на classpath у сервісі без БД?
}

Так, це може розблокувати старт. Але якщо ви зловили себе на думці «о, зручно, залишу назавжди», варто зупинитися й запитати: а чому в проєкті без БД узагалі зʼявився JDBC-шар? У більшості випадків краще лікувати причину, а виключення вважати костилем, який ви собі чесно визнаєте костилем.

Сценарій B: підсистема не потрібна взагалі

Іноді підсистема справді не потрібна взагалі, і це не помилка залежності, а архітектурне рішення. Наприклад, ви підключили зовнішній стартер/модуль, а він додав блок автоконфігурації, який вам не підходить (або дублює те, що ви робите у своєму коді). Ви не хочете жодного біну з цього блоку, бо він у принципі про «чужу політику».

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

Тоді виключення виглядає чесно: «цього блоку в збиранні застосунку бути не повинно».

package com.example.catalogservice;

import com.example.catalogservice.support.startup.StartupReportAutoConfiguration;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication(exclude = StartupReportAutoConfiguration.class) // Повністю прибираємо чужу "політику" з контексту
public class CatalogServiceApplication {
    // Тут виключення логічне лише тоді, якщо справді НЕ потрібен жоден бін із цього класу.
}

Тут важливе застереження: це рішення має сенс лише якщо ви точно розумієте, що вимикаєте цілком, і не очікуєте часткової поведінки. Якщо вам потрібно «вмикати/вимикати звіт» за прапорцем — це історія для @ConditionalOnProperty, а не для exclude.

Сценарій C: аварійний старт

Звучить як виправдання, але в реальних проєктах таке трапляється постійно. Буває, що застосунок має запускатися (хоча б локально), щоб ви могли подивитися логи, перевірити зв’язування або просто не блокувати команду. А автоконфігурація ламає старт із причини, яку ви поки не можете швидко виправити (наприклад, немає доступу до середовища, не готові секретні дані або «на цьому ноутбуці сьогодні не буде VPN»).

У такому разі виключення може бути тимчасовою «кнопкою аварійного старту». Але тут дуже легко скотитися у звичку: «просто виключимо ще ось це, і ще ось те — і все запрацює». Це вже прямий шлях до захоплення фреймворку (про це ми поговоримо пізніше в курсі), коли Boot перестає бути платформою, а ви вручну збираєте все підряд.

Тому якщо ви використовуєте виключення як тимчасовий захід, корисно тримати дисципліну: одне виключення — одна причина — і бажано короткий коментар поруч, щоб через два тижні ви не гадали, що це було.

5. Вимкнення автоконфігурації: анотація і властивість

Коли ми говоримо «зробити виключення», технічно є кілька способів. Для розробника-початківця важливо не запам’ятати всі варіанти, а зрозуміти головне: де це пишеться, як читається і чому має бути максимально помітним. Бо виключення впливає на збирання застосунку — це як змінити схему електрики: ви хочете, щоб це було видно відразу.

Варіант 1: exclude на @SpringBootApplication

Найчастіше виключення пишуть прямо на main-класі. Це логічно: main-клас — точка збирання застосунку. Там уже живе @SpringBootApplication, а отже там же найпомітніше місце для «ми вимикаємо блок автоконфігурації».

package com.example.catalogservice;

import com.example.catalogservice.support.startup.StartupSupportAutoConfiguration;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication(exclude = StartupSupportAutoConfiguration.class) // Вимикаємо блок автоконфігурації цілком
public class CatalogServiceApplication {

    public static void main(String[] args) {
        // Це точка старту застосунку: якщо вимикач стоїть тут — його одразу видно.
        SpringApplication.run(CatalogServiceApplication.class, args);
    }
}

Плюс цього варіанта — читабельність. Відкрили main-клас і відразу побачили: «ага, ось цей клас автоконфігурації вимкнено».

Варіант 2: spring.autoconfigure.exclude у конфігурації

Іноді потрібно вимкнути автоконфігурацію не через код, а через конфігурацію. Наприклад, ви хочете швидко перевірити гіпотезу «що буде, якщо вимкнути блок», або не хочете перезбирати JAR заради експерименту. Тоді можна використати властивість spring.autoconfigure.exclude.

У YAML це виглядає так:

spring:
  autoconfigure:
    exclude:
      # Те саме, що й exclude у @SpringBootApplication, але "сховано" в конфігурації.
      # Зручно для експериментів і тимчасових обхідних шляхів без перезбирання.
      - com.example.catalogservice.support.startup.StartupSupportAutoConfiguration

Цей спосіб працює, але в нього є тонкість: налаштування стає «менш помітним». Якщо хтось дивиться лише на Java-код, він може не зрозуміти, чому частина поведінки «зникла». Тому як постійне рішення для застосунку я віддаю перевагу анотації в main-класі, а конфігураційне виключення використовую як тимчасовий інструмент або як дуже усвідомлену стратегію.

Важливе уточнення: це не Gradle exclude

Слово exclude трапляється і в Gradle, але це інший світ. Gradle exclude — це про залежності (що потрапить на classpath). Spring Boot exclude — це про автоконфігурацію (що буде ввімкнено в контекст). Іноді правильне рішення — виключити залежність, а не виключати автоконфігурацію. І, чесно кажучи, у половині випадків «виключення автоконфігурації» — це спроба виправити те, що треба було виправити на рівні керування залежностями.

6. Виключення як симптом: спочатку залежність, потім вимикач

На цьому місці зазвичай хочеться дати універсальний рецепт, але правильніше дати дисципліну мислення. Spring Boot вмикає автоконфігурацію не тому, що вона «шкідлива», а тому, що бачить на classpath потрібні бібліотеки й чесно намагається допомогти. Якщо допомога стала проблемою, часто проблема не в Boot, а в тому, що ви випадково принесли не ту технологію.

Для catalog-service це особливо важливо, бо проєкт за ТЗ легкий: без бази, без security, без важких інтеграцій. Тому якщо раптово зʼявилося автоналаштування DataSource або security-фільтрів, це майже напевно означає: ви або колега додали залежність не туди.

Тут добре працює старе інженерне правило: якщо у вас загоряється лампочка «Check Engine», можна, звісно, заклеїти її ізолентою — це буде наш аналог виключення, — але краще все-таки відкрити капот. У нашому курсі «відкрити капот» — це згадати навички роботи з деревом залежностей: подивитися, який стартер або яка бібліотека принесли зайвий модуль, і прибрати проблему на рівні залежностей. Виключення варто застосовувати тоді, коли ви вже перевірили classpath і все одно усвідомлено вирішили: «так, модуль залишається, але його автоконфігурація нам не потрібна».

І ще один нюанс: іноді Boot дає офіційний «м’який вимикач» через властивості. Якщо вам потрібно вимкнути частину поведінки, спочатку шукайте властивість. Виключення — це коли м’якого вимикача немає або він вам не підходить, бо ви хочете прибрати блок цілком.

Перевірка: виключення не ламає застосунок

Після виключення не можна просто сказати «компілюється — значить ок». У Boot інколи все компілюється, але ламається під час старту (і це нормально: зв’язування та умови перевіряються під час виконання). Тому після того, як ви вимкнули блок, треба хоча б мінімально переконатися, що застосунок стартує і що ви отримали саме ту поведінку, яку очікували.

Найчастіший результат невдалого виключення — помилка про відсутній бін. Наприклад, у нас був компонент, який залежав від біну за замовчуванням, а ми вимкнули автоконфігурацію, яка цей бін створювала. Тоді старт упаде приблизно так (скорочено):

Parameter 0 of constructor in ...StartupSummaryRunner required a bean of type
'StartupMessageFormatter' that could not be found.

Це, до речі, хороший сценарій для навчання: він показує, що виключення — не «видалення зайвого», а зміна збирання. Якщо ви хочете вимкнути автоконфігурацію, але залишити застосунок робочим, вам потрібно або надати альтернативний бін (це шлях лекції 1), або змінити залежність на optional (ми це обговорювали в темі про зв’язування), або визнати, що компонент більше не потрібен.

У catalog-service зручно тримати просту дисципліну: якщо ви додали виключення, ви маєте вміти одним реченням відповісти на три запитання. Який блок вимкнули, чому вимкнули, що залишилося працювати за замовчуванням. Якщо хоча б на одне з питань відповідь виходить у стилі «ну… щоб не заважало», значить рішення поки що сире.

7. Типові помилки під час роботи з виключеннями

Перед тим як закрити тему виключень, корисно проговорити кілька помилок, які майже гарантовано трапляються в початківців. Вони не про «криві руки», а про природне бажання спростити собі життя й вимкнути те, чого не розумієш. Boot реагує на це передбачувано: інколи мовчить, інколи ламається, а інколи «працює, але дивно» — і це найнеприємніший варіант.

Помилка № 1: cargo-cult виключення («взяв із інтернету й вставив»).
Це ситуація, коли розробник не зрозумів причину проблеми, але знайшов у чужому репозиторії рядок exclude і просто скопіював. Небезпека тут у тому, що ви вимикаєте блок, який міг давати не лише «небажане», а й корисне. У підсумку застосунок стартує, але далі ламається в іншому місці, і ви починаєте нарощувати список виключень, як снігову кулю.

Помилка № 2: виключення для заміни одного-єдиного біну.
Дуже часта історія: «Мені не подобається конкретний бін, отже вимкну весь клас автоконфігурації». Це як викинути весь холодильник, бо вам не сподобався один йогурт. Якщо мета — замінити один компонент, найчастіше правильніше оголосити власний бін правильного типу й дозволити Boot «відступити» через @ConditionalOnMissingBean.

Помилка № 3: довгий список виключень у main-класі.
Одне виключення ще може бути усвідомленим рішенням. Десять виключень — майже завжди ознака того, що ви вже не використовуєте Boot як платформу, а вручну перескладаєте його шар. У такій конфігурації ви втрачаєте головну цінність Boot: підібрані значення за замовчуванням і передбачуване автозбирання. Далі буде лише гірше: кожне оновлення залежностей почне «стріляти» неочікуваними побічними ефектами.

Помилка № 4: плутанина між виключенням у Boot та виключенням у Gradle.
Іноді розробник намагається розв’язати проблему залежностей через @SpringBootApplication(exclude=...), хоча треба було прибрати зайву бібліотеку з classpath. Це призводить до дивної картини: бібліотека залишається в проєкті, але її автоналаштування вимкнене, і частина коду може почати працювати в «напівзібраному» режимі. Якщо проблема почалася після додавання залежності — спочатку перевірте дерево залежностей, а вже потім думайте про exclude.

Помилка № 5: виключення через конфігурацію і забули, що воно взагалі є.
Коли виключення задано через spring.autoconfigure.exclude у YAML, воно легко губиться з поля зору. Потім ви дивитеся на Java-код і дивуєтеся: «чому Boot не створив бін за замовчуванням?». Тому якщо це не тимчасовий експеримент, краще тримати виключення максимально явно, поруч із main-класом, або хоча б документувати причину (хай навіть коротким коментарем).