Formations — 1 037 leçons en français

Accueil › Spring Boot › Les annotations @Conditional en détail

Les annotations @Conditional en détail

Auto-configuration en profondeuravance

Toutes les annotations @ConditionalOnXxx de Spring Boot (@ConditionalOnClass, @ConditionalOnBean, @ConditionalOnProperty…) reposent sur la même mécanique Spring : la méta-annotation @Conditional, associée à une implémentation de l'interface Condition. Une classe de configuration (ou une méthode @Bean) n'est retenue que si toutes ses conditions renvoient true.

@AutoConfiguration
@ConditionalOnClass(RedisTemplate.class)
@ConditionalOnMissingBean(CacheManager.class)
public class RedisCacheAutoConfiguration {
    @Bean
    public CacheManager cacheManager(RedisConnectionFactory factory) { ... }
}

Point clé pour un usage avancé : @ConditionalOnBean et @ConditionalOnMissingBean interrogent les définitions de beans déjà enregistrées au moment où la condition est évaluée, pas l'état final du contexte. Spring Boot garantit que toutes les classes @Configuration de l'application (les vôtres) sont traitées avant l'ensemble des classes d'auto-configuration : c'est ce qui permet à @ConditionalOnMissingBean, dans une auto-configuration, de voir fiablement vos beans et de s'effacer devant eux. En revanche, rien ne garantit l'ordre de traitement entre vos propres classes @Configuration : y poser un @ConditionalOnBean qui dépend d'une autre de vos classes est fragile. C'est pourquoi ces deux conditions sont réservées, en pratique, aux classes d'auto-configuration, où l'ordre se maîtrise explicitement avec @AutoConfiguration(before/after).

D'autres conditions ciblent le classpath (@ConditionalOnClass), la configuration (@ConditionalOnProperty), le type d'application (@ConditionalOnWebApplication) ou une expression arbitraire (@ConditionalOnExpression).

Les termes à connaître

Condition

Interface (org.springframework.context.annotation.Condition) avec une seule méthode, matches(ConditionContext, AnnotatedTypeMetadata). Elle renvoie true pour activer l'élément conditionné. Toutes les annotations @ConditionalOnXxx de Spring Boot sont construites au-dessus de @Conditional, associée à une implémentation de cette interface.

@ConditionalOnClass / @ConditionalOnMissingClass

Activent (ou désactivent) une configuration selon la présence d'une classe dans le classpath, identifiée par référence (ObjectMapper.class) ou par nom complet en chaîne (utile si la classe elle-même peut être absente sans faire échouer la compilation).

@ConditionalOnBean / @ConditionalOnMissingBean

Activent (ou désactivent) un bean selon qu'un bean d'un type donné est déjà enregistré au moment de l'évaluation. Réservées en pratique aux classes d'auto-configuration : l'ordre de traitement entre vos propres classes @Configuration n'est pas garanti, contrairement à l'ordre entre auto-configurations, contrôlable explicitement.

@ConditionalOnProperty

Active une configuration selon une propriété : prefix + name (ou name complet), havingValue (valeur attendue, sinon toute valeur non false suffit) et matchIfMissing (comportement si la propriété est absente, false par défaut).

@ConditionalOnWebApplication

Active une configuration selon le type d'application : Type.SERVLET (web classique), Type.REACTIVE (WebFlux) ou Type.ANY. Son pendant @ConditionalOnNotWebApplication cible les applications non web.

@ConditionalOnResource / @ConditionalOnExpression

@ConditionalOnResource(resources = "classpath:...") teste la présence d'un fichier. @ConditionalOnExpression évalue une expression SpEL, la plus générique mais la plus coûteuse et la plus difficile à lire — à réserver aux cas que les autres conditions ne couvrent pas.

@AutoConfiguration(before/after)

Attributs (before, beforeName, after, afterName) de l'annotation @AutoConfiguration qui imposent un ordre relatif entre classes d'auto-configuration, indispensable dès qu'une condition (@ConditionalOnBean notamment) dépend d'un bean défini par une autre auto-configuration.

@AutoConfigureOrder

Donne un ordre global (au sens de @Order) à une classe d'auto-configuration, plus large qu'un before/after ciblé. Influence l'ordre de définition des beans, pas l'ordre de leur création (piloté par leurs dépendances).

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.