Lección 4 de 8: configuración y perfiles. Vas a aprender a sacar del código todo lo que cambia entre tu computadora y el servidor (puertos, nombres, impuestos, contraseñas), a leerlo con un record validado, a tener un archivo por ambiente con los perfiles y a entender qué valor gana cuando el mismo ajuste aparece en dos lugares.
Por qué la configuración va afuera del código
Tu aplicación va a correr en varios lugares: en tu computadora mientras la programas, en un servidor de pruebas y en producción. En cada uno cambian cosas: la dirección de la base de datos, la contraseña, el puerto, cuánto detalle escribe el registro. Si esos datos estuvieran en el código, habría que compilar una versión distinta para cada lugar. Spring Boot los saca del código: el mismo .jar se comporta distinto según la configuración que encuentra al arrancar.
Piénsalo así
El código es la receta; la configuración, los ajustes del horno. La misma receta de pan sirve en la Ciudad de México y en Cancún, pero allá ajustas la temperatura por la humedad. No reescribes la receta: mueves la perilla.
application.properties
El archivo src/main/resources/application.properties ya venía en el proyecto con una sola línea. Cada línea es clave=valor. Hay cientos de claves que Spring Boot entiende de fábrica, como server.port para el puerto o logging.level.* para el detalle del registro, y puedes inventar las tuyas. Para una tienda:
spring.application.name=tienda tienda.nombre=Abarrotes La Esperanza tienda.iva=0.16 tienda.envio-gratis-desde=999 tienda.sucursales=CDMX,Guadalajara,Monterrey
Las claves que empiezan con tienda. son nuestras. Las listas se escriben separadas por comas. Ahora hay que leerlas desde el código, y hay dos formas.
Ojo con los acentos. Spring Boot lee los archivos .properties con la codificación ISO-8859-1, no con UTF-8, así que una «ó» escrita tal cual en el archivo llega convertida en dos caracteres raros. Lo comprobamos en las rarezas. Si tus valores llevan acentos o eñes, usa application.yaml, que sí se lee en UTF-8, o escribe el carácter como \u00f3.
Un valor suelto: @Value
Para un dato aislado, @Value en un parámetro del constructor. Entre ${ } va la clave, y después de los dos puntos, el valor por omisión si la clave no existe. Lo verás en el controlador de abajo: @Value("${tienda.moneda:MXN}") da MXN, porque no escribimos tienda.moneda en el archivo.
Un grupo de valores: @ConfigurationProperties
Cuando los ajustes forman un grupo, conviene juntarlos en un record. Spring Boot llena cada componente con la clave del mismo nombre bajo el prefijo, convierte los tipos (texto a BigDecimal, la lista separada por comas a List) y, con @Validated, revisa las reglas al arrancar:
package com.ejemplo.tienda;
import jakarta.validation.constraints.DecimalMax;
import jakarta.validation.constraints.DecimalMin;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotEmpty;
import java.math.BigDecimal;
import java.util.List;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;
@ConfigurationProperties(prefix = "tienda")
@Validated
public record TiendaProperties(
@NotBlank String nombre,
@DecimalMin("0") @DecimalMax("0.5") BigDecimal iva,
BigDecimal envioGratisDesde,
@NotEmpty List<String> sucursales) {
}Fíjate en envioGratisDesde: en el archivo se escribe envio-gratis-desde, en minúsculas con guiones (el estilo recomendado), y Spring Boot lo empata igual con el nombre de Java. Las anotaciones @NotBlank, @DecimalMin y compañía vienen de Bean Validation; necesitan la dependencia Validation de start.spring.io (spring-boot-starter-validation), y las verás a fondo en la lección 6. Para que Spring Boot encuentre el record, agrega @ConfigurationPropertiesScan a la clase principal:
package com.ejemplo.tienda;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
@SpringBootApplication
@ConfigurationPropertiesScan
public class TiendaApplication {
public static void main(String[] args) {
SpringApplication.run(TiendaApplication.class, args);
}
}Y el record se inyecta como cualquier bean. Este controlador enseña la configuración y calcula un precio con el IVA configurado:
package com.ejemplo.tienda;
import java.math.BigDecimal;
import java.math.RoundingMode;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class ConfigController {
private static final Logger log = LoggerFactory.getLogger(ConfigController.class);
private final TiendaProperties tienda;
private final String moneda;
public ConfigController(TiendaProperties tienda, @Value("${tienda.moneda:MXN}") String moneda) {
this.tienda = tienda;
this.moneda = moneda;
}
@GetMapping("/config")
public TiendaProperties config() {
log.debug("Alguien consultó la configuración");
return tienda;
}
public record Precio(BigDecimal base, BigDecimal iva, BigDecimal total, String moneda) {
}
@GetMapping("/precio")
public Precio precio(@RequestParam BigDecimal base) {
BigDecimal total = base.add(base.multiply(tienda.iva())).setScale(2, RoundingMode.HALF_UP);
return new Precio(base, tienda.iva(), total, moneda);
}
}terminal$ curl -s localhost:8080/config
{"nombre":"Abarrotes La Esperanza","iva":0.16,"envioGratisDesde":999,"sucursales":["CDMX","Guadalajara","Monterrey"]}
$ curl -s "localhost:8080/precio?base=100"
{"base":100,"iva":0.16,"total":116.00,"moneda":"MXN"}Un record de configuración es más seguro que diez @Value regados: los nombres se revisan en un solo lugar, el compilador te avisa si escribes mal un componente y la validación detiene el arranque si un valor no tiene sentido, en vez de dejarte descubrirlo con el primer cliente.
YAML: lo mismo, con sangrías
Si en vez de application.properties usas application.yaml, las claves se escriben en árbol. Es cuestión de gusto: muchos equipos prefieren YAML porque no repite los prefijos. Esta es la misma configuración; arrancamos el proyecto con ella y respondió igual:
spring:
application:
name: tienda
tienda:
nombre: Abarrotes La Esperanza
iva: 0.16
envio-gratis-desde: 999
sucursales:
- CDMX
- Guadalajara
- Monterreyterminal$ curl -s localhost:8080/config
{"nombre":"Abarrotes La Esperanza","iva":0.16,"envioGratisDesde":999,"sucursales":["CDMX","Guadalajara","Monterrey"]}En YAML la sangría es parte de la sintaxis: dos espacios, nunca tabuladores. Un espacio de más mueve la clave a otro nivel y Spring Boot no la encuentra. Si tienes los dos archivos, se leen los dos, y es fácil perder de vista cuál manda: elige uno por proyecto.
Perfiles: un archivo por ambiente
Un perfil es un nombre (como dev, pruebas o prod) que activa un archivo extra de configuración. El archivo application-dev.properties solo se lee cuando el perfil dev está activo, y sus valores se ponen encima de los de application.properties. Lo que no menciona se queda igual:
server.port=8081 tienda.nombre=Tienda de pruebas logging.level.com.ejemplo.tienda=DEBUG
El perfil se activa al arrancar, con un argumento o con la variable de entorno SPRING_PROFILES_ACTIVE:
java -jar target/tienda-0.0.1-SNAPSHOT.jar --spring.profiles.active=dev # o, con el wrapper: ./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
registro con el perfil dev2026-11-22T10:10:30.920-06:00 DEBUG 277 --- [tienda] [ main] com.ejemplo.tienda.TiendaApplication : Running with Spring Boot v4.2.0, Spring v7.1.0 2026-11-22T10:10:30.921-06:00 INFO 277 --- [tienda] [ main] com.ejemplo.tienda.TiendaApplication : The following 1 profile is active: "dev" 2026-11-22T10:10:32.269-06:00 INFO 277 --- [tienda] [ main] o.s.boot.tomcat.TomcatWebServer : Tomcat started on port 8081 (http) with context path '/' 2026-11-22T10:10:32.854-06:00 DEBUG 277 --- [tienda] [nio-8081-exec-1] com.ejemplo.tienda.ConfigController : Alguien consultó la configuración
terminal$ curl -s localhost:8081/config
{"nombre":"Tienda de pruebas","iva":0.16,"envioGratisDesde":999,"sucursales":["CDMX","Guadalajara","Monterrey"]}El registro avisa qué perfil está activo, el puerto cambió a 8081 y el nombre es el de pruebas, pero el IVA y las sucursales vienen del archivo general. La última línea del registro es el log.debug del controlador: con logging.level.com.ejemplo.tienda=DEBUG se ve, y sin el perfil no aparece, porque el nivel por omisión es INFO.
Variables de entorno y argumentos
En los servidores y en los contenedores, lo más común es configurar con variables de entorno. Spring Boot las lee sin que hagas nada, con una regla de traducción: mayúsculas, guion bajo en lugar del punto y sin guiones. A esto le llaman relaxed binding:
En la frontera norte de México, el IVA es de 8 % en la región fronteriza. Arrancamos el mismo jar con TIENDA_IVA=0.08, y luego con esa variable y además el argumento --tienda.iva=0:
terminal (con TIENDA_IVA=0.08)$ curl -s "localhost:8080/precio?base=100"
{"base":100,"iva":0.08,"total":108.00,"moneda":"MXN"}
# con TIENDA_IVA=0.08 y --tienda.iva=0
$ curl -s "localhost:8080/precio?base=100"
{"base":100,"iva":0,"total":100.00,"moneda":"MXN"}La variable de entorno le ganó al archivo, y el argumento le ganó a la variable. Ese orden tiene lógica: lo más cercano al momento de arrancar manda, para que puedas corregir algo sin tocar los archivos. Spring Boot revisa más de diez fuentes; estas son las que vas a usar casi siempre:
El error que te ahorra: un valor que no pasa la validación
Alguien escribió el IVA como porcentaje, tienda.iva=16, en vez de 0.16. Gracias a @DecimalMax("0.5"), la aplicación se niega a arrancar y dice exactamente qué valor, de qué archivo y en qué línea:
registro: la aplicación no arranca***************************
APPLICATION FAILED TO START
***************************
Description:
Binding to target com.ejemplo.tienda.TiendaProperties failed:
Property: tienda.iva
Value: "16"
Origin: class path resource [application.properties] from tienda-iva-mal-0.0.1-SNAPSHOT.jar - 3:12
Reason: must be less than or equal to 0.5
Action:
Update your application's configurationSin la validación habría arrancado, y cada precio saldría 17 veces más caro. Que un error de configuración tumbe el arranque es bueno: lo ves al desplegar, no cuando se queja un cliente. Lo mismo pasa si falta una clave que se usa con @Value y no tiene valor por omisión, como @Value("${tienda.moneda}"):
registro: la aplicación no arrancaCaused by: org.springframework.util.PlaceholderResolutionException: Could not resolve placeholder 'tienda.moneda' in value "${tienda.moneda}"Ojo con la seguridad: las contraseñas no van en application.properties
El archivo application.properties viaja con tu código al repositorio, y de ahí a cualquier persona con acceso. Las contraseñas de la base de datos, las llaves de APIs y los secretos van en variables de entorno, o en el gestor de secretos de tu nube. En el archivo puedes dejar la clave apuntando a la variable, sin el valor:
spring.datasource.password=${DB_PASSWORD}Si la variable no existe, la aplicación no arranca, que es lo que quieres. Y si alguna vez subiste un secreto a git, no basta con borrarlo en el siguiente commit: sigue en el historial. Hay que cambiar la contraseña.
Retos
Reto 1. Crea un perfil prod que use el puerto 9000, agregue « – produccion» al nombre de la tienda (sin acento: enseguida verás por qué) y deje el registro solo con advertencias (WARN) para todo. Arráncalo y consulta /config.
Ver la solución
server.port=9000 tienda.nombre=Abarrotes La Esperanza - produccion logging.level.root=WARN
terminal (arrancado con --spring.profiles.active=prod)$ curl -s localhost:9000/config
{"nombre":"Abarrotes La Esperanza - produccion","iva":0.16,"envioGratisDesde":999,"sucursales":["CDMX","Guadalajara","Monterrey"]}registro completo . ____ _ __ _ _ /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ \\/ ___)| |_)| | | | | || (_| | ) ) ) ) ' |____| .__|_| |_|_| |_\__, | / / / / =========|_|==============|___/=/_/_/_/ :: Spring Boot :: (v4.2.0)
Con logging.level.root=WARN desaparecen todas las líneas INFO del arranque, incluida la de Started: del registro solo queda el logotipo. En producción suele bastar con advertencias y errores, y que no aparezca nada más es buena señal: no hubo nada que advertir.
Reto 2. Sin ejecutarlo: con el perfil dev activo y la variable de entorno SERVER_PORT=7000, ¿en qué puerto arranca? ¿Y si además pasas --server.port=7500?
Ver la solución
En el 7000: la variable de entorno le gana a application-dev.properties, que dice 8081. Con el argumento, en el 7500, porque los argumentos ganan a todo lo demás. Es el orden del esquema de arriba.
Reto 3. ¿Por qué TiendaProperties es un record y no una clase con setters? ¿Qué ganarías y qué perderías?
Ver la solución
Un record es inmutable: una vez que Spring Boot lo llenó al arrancar, nadie puede cambiar el IVA a la mitad del día desde otra parte del código, lo cual evita errores difíciles de rastrear. Spring Boot llena los records por su constructor. Una clase con setters también funciona y era lo común antes; solo tiene sentido si de verdad necesitas cambiar valores en vivo, y para eso hay mejores herramientas.
Cada proyecto de esta lección se compiló con Spring Boot 4.2.0, Java 25 (Temurin 25.0.5.1) y Maven 3.10.1 en un contenedor limpio y sin acceso a la red, se arrancó y se le hicieron las peticiones que ves con curl antes de publicar la lección; los registros, las respuestas y los errores están copiados de esa ejecución. Las horas de los registros son de la Ciudad de México.
