Mastering @ConditionalOnProperty: Controlling Bean Activation in Spring Boot

During development you may notice that adding or modifying entries in application.yml can cause certain configuration classes or beans to become active or inactive. The Spring Boot annotation @ConditionalOnProperty provides a declarative way to bind bean registration to specific property values.

How to use

@ConditionalOnProperty(name = "aspect.flag", havingValue = "true")
@Aspect
@Component
public class CostTimeAspect {
    // ...
}

The name attribute tells Spring to look for the property aspect.flag in the configuration file. The value found is compared with havingValue. If the two are equal, the condition evaluates to true and the annotated component is loaded; otherwise it is skipped. If name is empty, the condition always returns false, so the component never activates.

Source code analysis

@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.TYPE, ElementType.METHOD })
@Documented
@Conditional(OnPropertyCondition.class)
public @interface ConditionalOnProperty {

   String[] value() default {};

   String prefix() default "";

   String[] name() default {};

   String havingValue() default "";

   boolean matchIfMissing() default false;
}

value : an array of property names; it cannot be used together with name.

prefix : a string that is prepended to each entry in name, e.g., spring.cloud, to form the full property key.

name : an array containing full or partial property names. It can be combined with prefix to build the complete key, but must not be used together with value.

havingValue : the expected value for the property identified by name. The condition matches only when the actual property value equals this string.

matchIfMissing : when set to true, the condition evaluates to true even if the specified property is absent; otherwise the bean is not loaded.

By combining these attributes you can precisely control whether a configuration class or bean participates in the application context based on the presence and value of configuration properties.

Understanding the annotation’s source code helps avoid common pitfalls, such as using value and name together or forgetting that an empty name disables the condition.

With this knowledge you can confidently use @ConditionalOnProperty to make your Spring Boot applications more flexible and environment‑aware.