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.