Índice

1. Descripción general

Los perfiles de Spring permiten segmentar partes de la configuración de una aplicación y hacerlas disponibles únicamente en ciertos entornos. Cualquier @Component, @Configuration o @ConfigurationProperties puede marcarse con @Profile para condicionar su carga.

La anotación pertenece al paquete org.springframework.context.annotation (Spring Framework 7.0.6) y está disponible desde Spring 3.1.

2. Marcar componentes con @Profile

@Profile puede aplicarse de las siguientes formas:

  • Como anotación de tipo sobre cualquier clase anotada directa o indirectamente con @Component, incluyendo clases @Configuration.
  • Como meta-anotación para componer anotaciones estereotipo personalizadas.
  • Como anotación de método sobre métodos @Bean.
@Configuration(proxyBeanMethods = false)
@Profile("production")
public class ProductionConfiguration {
    // beans activos solo en el perfil "production"
}

Cuando una clase @Configuration está marcada con @Profile, todos sus métodos @Bean y sus anotaciones @Import son ignorados a menos que al menos uno de los perfiles especificados esté activo.

Consideración con @ConfigurationProperties

Si los beans @ConfigurationProperties se registran mediante @EnableConfigurationProperties en lugar de escaneo automático, @Profile debe aplicarse sobre la clase @Configuration que contiene @EnableConfigurationProperties, no sobre la clase @ConfigurationProperties en sí. En el caso de escaneo automático, @Profile puede aplicarse directamente sobre la clase @ConfigurationProperties.

Nota sobre métodos @Bean sobrecargados

Con @Profile en métodos @Bean, si existen métodos sobrecargados con el mismo nombre Java, la condición @Profile debe declararse de forma consistente en todos los métodos sobrecargados. Si las condiciones son inconsistentes, solo aplica la condición de la primera declaración. Para definir beans alternativos con distintas condiciones de perfil, se recomienda usar nombres de método Java distintos apuntando al mismo nombre de bean.

3. Activar perfiles

Mediante propiedades

La propiedad spring.profiles.active controla qué perfiles están activos:

# application.properties
spring.profiles.active=dev,hsqldb

# línea de comandos
--spring.profiles.active=dev,hsqldb

La propiedad sigue las mismas reglas de precedencia que el resto de propiedades en Spring Boot: la fuente con mayor prioridad gana. Esto permite definir perfiles en application.properties y sobreescribirlos desde la línea de comandos.

Perfil por defecto

Si ningún perfil está activo, se habilita el perfil default. Su nombre puede cambiarse con:

spring.profiles.default=none

Restricción importante

spring.profiles.active y spring.profiles.default solo pueden usarse en documentos no específicos de perfil. No pueden incluirse en archivos activados por spring.config.activate.on-profile. El siguiente ejemplo es inválido:

spring.profiles.active=prod
#---
spring.config.activate.on-profile=prod
spring.profiles.active=metrics

Activación programática

SpringApplication app = new SpringApplication(MyApp.class);
app.setAdditionalProfiles("dev", "local");
app.run(args);

También es posible activar perfiles mediante la interfaz ConfigurableEnvironment.

Validación de nombres

Por defecto, los nombres de perfil en Spring Boot pueden contener letras, números y los caracteres -, _, ., +, @, y deben comenzar y terminar con una letra o número. Para permitir nombres más flexibles:

spring.profiles.validate=false

4. Agregar perfiles sin reemplazar los activos

spring.profiles.include agrega perfiles adicionales sobre los ya activos, sin reemplazarlos:

spring.profiles.include[0]=common
spring.profiles.include[1]=local

Los perfiles incluidos se agregan antes que los activados por spring.profiles.active. La propiedad se procesa por cada fuente de propiedades, por lo que no aplican las reglas habituales de fusión de listas para tipos complejos.

Al igual que spring.profiles.active, spring.profiles.include no puede usarse en documentos específicos de perfil.

5. Profile Groups

Cuando los perfiles son demasiado granulares, Spring Boot permite agruparlos bajo un nombre lógico:

spring.profiles.group.production[0]=proddb
spring.profiles.group.production[1]=prodmq

Al activar el perfil production, se activan automáticamente proddb y prodmq:

--spring.profiles.active=production

spring.profiles.group también está restringido a documentos no específicos de perfil.

6. Expresiones de perfil

El valor de @Profile acepta expresiones para lógica más compleja. Los operadores disponibles son:

Operador Sintaxis Comportamiento
AND lógico "p1 & p2" Activo si ambos perfiles están activos
OR lógico "p1 | p2" Activo si al menos uno está activo
NOT "!p1" Activo si el perfil no está activo 
@Profile("p1 & p2")
@Configuration
public class BothActiveConfig { }

@Profile({"p1", "!p2"})
@Configuration
public class P1ActiveOrP2InactiveConfig { }

En el segundo ejemplo con array, los elementos se evalúan con OR: el componente se registra si p1 está activo o si p2 no está activo.

Si @Profile se omite, el componente se registra independientemente de qué perfiles estén activos.

7. Archivos de configuración por perfil

Spring Boot carga automáticamente archivos de propiedades específicos por perfil. Para un perfil llamado dev, buscará:

application-dev.properties
application-dev.yaml

Estos archivos se cargan además del application.properties base. Las propiedades definidas en archivos de perfil tienen mayor precedencia que las del archivo base.

También es posible usar spring.config.activate.on-profile dentro de un mismo archivo multi-documento:

spring:
  datasource:
    url: jdbc:h2:mem:testdb
---
spring:
  config:
    activate:
      on-profile: production
  datasource:
    url: jdbc:postgresql://prod-host/mydb

8. Conclusión

Los perfiles de Spring proveen un mecanismo declarativo para segmentar la configuración por entorno. @Profile controla la carga de beans y configuraciones. spring.profiles.active e spring.profiles.include gestionan la activación desde distintas fuentes. Los Profile Groups simplifican la activación de conjuntos de perfiles relacionados. Los archivos específicos por perfil permiten separar propiedades sin duplicar la configuración base.