Understanding Spring Boot Auto‑Configuration and @ConditionalOn Annotations

Spring Boot minimizes manual configuration by automatically instantiating beans based on conditional annotations, primarily the @ConditionalXXX family. When the container scans configuration classes, it evaluates the associated Condition implementations to decide whether to register each bean.

The framework provides many built‑in @ConditionalOn variants (e.g., @ConditionalOnClass , @ConditionalOnMissingBean ) that developers can use to express environment‑specific requirements. These annotations are themselves meta‑annotated with @Conditional , linking them to concrete Condition classes such as org.springframework.context.annotation.Condition .

During startup, Spring Boot follows these steps:

Scan configuration classes and detect any @ConditionalOn annotations.

Retrieve the corresponding org.springframework.context.annotation.Condition instance defined by the annotation.

Invoke org.springframework.context.annotation.ConditionEvaluator#shouldSkip , which ultimately calls Condition#matches to determine if the bean should be registered.

Key internal classes that drive this process include AnnotatedBeanDefinitionReader , ClassPathScanningCandidateComponentProvider , ConfigurationClassBeanDefinitionReader , and ConfigurationClassParser . Each holds a ConditionEvaluator instance responsible for the conditional logic.

Example: the WebSocketServletAutoConfiguration class is only registered when both Servlet.class and ServerContainer.class are present on the classpath. The class is annotated with @ConditionalOnClass , which internally uses OnClassCondition ( org.springframework.boot.autoconfigure.condition.OnClassCondition ) to perform the check.

Code snippet illustrating the condition interface:

org.springframework.context.annotation.Condition

Code snippet showing the specific condition class for @ConditionalOnClass :

org.springframework.boot.autoconfigure.condition.OnClassCondition

In summary, as long as the container discovers a configuration class, parses its @Conditional annotations, obtains the related Condition , and the condition evaluates to true, the bean is conditionally instantiated, enabling flexible and environment‑aware auto‑configuration.