15 de agosto de 2026 • Java

07 - Spring Bean `@ConditionalOnProperty` Anotação

Pré-requisitos

Antes de usar @ConditionalOnProperty, você deve estar familiarizado com:

  • Auto Configuração do Spring Boot
  • Spring Beans
  • Injeção de Dependência (DI)
  • application.properties ou application.yml
  • @Configuration e @Bean (opcional, mas recomendado)

Por que @ConditionalOnProperty?

Por padrão, o Spring cria todo Bean encontrado durante a varredura de componentes ou declarado em classes de configuração.

No entanto, em aplicações do mundo real, alguns Beans só devem ser criados quando uma funcionalidade ou configuração específica está habilitada.

Por exemplo:

  • Habilitar ou desabilitar uma funcionalidade (Feature Flag)
  • Habilitar integrações com serviços externos
  • Criar diferentes implementações dependendo da configuração
  • Habilitar cache apenas em produção
  • Habilitar jobs agendados apenas quando necessário

Sem @ConditionalOnProperty, os desenvolvedores geralmente precisam escrever lógica condicional dentro das classes de configuração, tornando o código mais difícil de manter.

@ConditionalOnProperty permite que o Spring Boot decida se um Bean deve existir com base nas propriedades de configuração.

O que é @ConditionalOnProperty?

@ConditionalOnProperty é uma anotação do Spring Boot que registra condicionalmente um Bean no Spring Application Context com base no valor de uma ou mais propriedades de configuração.

Se a condição configurada for satisfeita, o Bean é criado.

Caso contrário, o Bean é ignorado durante a inicialização da aplicação.

Ele pertence ao pacote Spring Boot:

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;

Atributos principais

AtributoDescrição
nameNome da propriedade a ser avaliada.
havingValueValor esperado da propriedade.
matchIfMissingDefine se o Bean deve ser criado quando a propriedade não existe. O padrão é false.
prefixPrefixo opcional usado para evitar repetir nomes de propriedades.

Casos de uso?

Feature Flags

Habilitar ou desabilitar novas funcionalidades sem alterar o código.

feature.checkout.enabled=true

Integrações Externas

Habilitar integrações apenas quando configuradas.

Exemplo:

  • Stripe
  • PayPal
  • Kafka
  • RabbitMQ

Componentes Específicos do Ambiente

Criar Beans apenas para certas configurações, em vez de criá-los em todos os ambientes.

Módulos Opcionais

Aplicações com módulos opcionais podem criar Beans apenas quando esse módulo está habilitado.

Múltiplas Implementações

Escolher uma implementação com base na configuração.

Exemplo:

notification.provider=email

ou

notification.provider=sms

Implementação?

Passo 1 — Configurar uma propriedade

notification.email.enabled=true

Passo 2 — Criar o Bean

@Service
@ConditionalOnProperty(
    name = "notification.email.enabled",
    havingValue = "true"
)
public class EmailNotificationService implements NotificationService {

}

Se a propriedade for:

notification.email.enabled=true

O Spring cria o Bean.

Se:

notification.email.enabled=false

O Spring ignora o Bean.

Usando matchIfMissing

@Service
@ConditionalOnProperty(
    name = "notification.email.enabled",
    havingValue = "true",
    matchIfMissing = true
)
public class EmailNotificationService {

}

Se a propriedade estiver completamente ausente, o Spring ainda criará o Bean.

Usando prefix

Em vez de escrever:

@ConditionalOnProperty(
    name = "notification.email.enabled"
)

Você pode escrever:

@ConditionalOnProperty(
    prefix = "notification.email",
    name = "enabled",
    havingValue = "true"
)

Que verifica:

notification.email.enabled=true

Vantagens x Desvantagens?

Vantagens

  • Configuração limpa e declarativa.
  • Sem instruções if/else dentro das classes de configuração.
  • Fácil de implementar Feature Flags.
  • Beans são criados apenas quando necessários.
  • Melhora a modularidade da aplicação.
  • Torna as aplicações mais fáceis de configurar em diferentes ambientes.
  • Integra-se perfeitamente com a Auto Configuração do Spring Boot.

Desvantagens

  • As condições são avaliadas apenas durante a inicialização da aplicação.
  • A alteração de uma propriedade em tempo de execução não cria ou destrói Beans automaticamente.
  • Nomes de propriedades incorretos podem impedir silenciosamente a criação do Bean.
  • O uso excessivo pode tornar a configuração da aplicação mais difícil de entender.
  • Não deve substituir @Profile quando o objetivo é a separação de ambientes.

Exemplo

feature.cache.enabled=true
@Service
@ConditionalOnProperty(
    name = "feature.cache.enabled",
    havingValue = "true"
)
public class CacheService {

}

Comportamento da aplicação:

Valor da PropriedadeBean Criado
true✅ Sim
false❌ Não
Ausente❌ Não (comportamento padrão)
Ausente + matchIfMissing=true✅ Sim

Resumo

@ConditionalOnProperty é uma anotação do Spring Boot usada para criar Beans condicionalmente com base em propriedades de configuração.

É comumente usada para feature flags, módulos opcionais, integrações externas e comportamento de aplicação configurável, permitindo que os desenvolvedores habilitem ou desabilitem funcionalidades sem modificar o código da aplicação.

← Voltar para o blog