CicloUrbana está llena de números escritos a fuego: 0.50 de desbloqueo, 0.12 por minuto, 15 minutos gratuitos para estudiantes, 8 anclajes mínimos por estación. Cambiar cualquiera de ellos exige hoy recompilar y volver a desplegar. Eso no es aceptable: el ayuntamiento de Ribalta cambia sus tarifas cada temporada y el puerto del servidor no es el mismo en tu portátil que en el servidor de producción. La solución es externalizar la configuración, y Spring Boot tiene para eso uno de los mecanismos más completos —y más incomprendidos— del ecosistema Java. En esta lección veremos qué es el Environment y de dónde saca sus valores, el orden exacto de precedencia entre las fuentes, las diferencias reales entre .properties y .yaml, cómo Spring relaja los nombres de las propiedades para que CICLOURBANA_TARIFA_BASE y ciclourbana.tarifa-base sean lo mismo, cómo leer valores con @Value, y por qué una credencial no puede estar nunca en el repositorio.

1. El Environment y los PropertySource
2. El orden de precedencia de las fuentes
3. Demostrar la precedencia en la práctica
4. .properties frente a .yaml
5. Relajación de nombres (relaxed binding)
6. Leer propiedades con @Value
7. SpEL y valores por defecto
8. Las propiedades que usa CicloUrbana
9. Configuración externa: spring.config.import y spring.config.location
10. Secretos y credenciales
11. Errores Comunes y Consejos
12. Ejercicios

En la lección 01-05 vimos que una de las primeras fases del arranque es "preparar el Environment". Ahora podemos concretar qué significa.

El Environment es un bean de Spring que responde a dos preguntas: ¿qué valor tiene esta propiedad? y ¿qué perfiles están activos? (los perfiles se estudian en la lección 07-02). Internamente no guarda ningún valor: mantiene una lista ordenada de PropertySource y, cuando le preguntas por una clave, los recorre en orden y devuelve el primero que la tenga.

La consecuencia es fundamental: el primero que responde gana. Toda la lógica de precedencia de Spring Boot se reduce a en qué orden se colocan los PropertySource en esa lista.

Puedes inspeccionar la lista completa en tu propia aplicación:

Salida típica en CicloUrbana:

Este InspectorConfiguracion es una herramienta que merece la pena tener a mano: cuando una propiedad "no se lee", lo primero es ver qué fuente la está ganando.

Spring Boot define un orden completo y documentado. De mayor a menor prioridad, y quedándonos con lo que importa en la práctica:

Tres reglas que resumen la tabla y que conviene memorizar:

1. Lo más externo gana. Cuanto más cerca del momento de arranque se especifica un valor, más prioridad tiene. Un --server.port=9090 en la línea de comandos vence a cualquier fichero.
2. Fuera del jar gana a dentro del jar. Es lo que permite empaquetar valores por defecto razonables y que el operador los ajuste sin reconstruir nada.
3. Con perfil gana a sin perfil. application-prod.properties sobrescribe application.properties.

Las tres filas que usarás el 95 % del tiempo son la 3 (argumentos), la 8 (variables de entorno) y la 12 (application.properties del proyecto). El resto conviene conocerlo para no sorprenderse.

Nada convence como verlo funcionar. Empecemos con el fichero del proyecto:

Arranca normalmente:

Ahora sobrescribe con una variable de entorno (fila 8):

Ahora con una propiedad de sistema (fila 7, que gana a la variable de entorno):

Y finalmente con un argumento de línea de comandos (fila 3, el que gana a todos):

Fíjate en la diferencia sintáctica, que confunde a mucha gente:

Poner --server.port=9090 antes de -jar no funciona: la JVM lo interpretaría como una opción suya y fallaría. Y -Dserver.port después del jar llega como un argumento más de la aplicación, que Spring no reconoce como propiedad.

Con Maven, para pasar argumentos hay que usar la propiedad del plugin:

Spring Boot admite ambos formatos, con las mismas capacidades. La elección es de estilo... hasta que la estructura crece.

La misma configuración de CicloUrbana en los dos formatos:

Comparados:

Recomendación práctica: elige uno y sé coherente. Si tu configuración es plana y corta, .properties es más difícil de romper. En cuanto aparecen listas, mapas y tres niveles de anidamiento —el caso de CicloUrbana en cuanto lleguemos a la lección 02-05—, YAML es claramente más legible. En este curso usaremos YAML a partir de aquí.

Nunca tengas los dos ficheros a la vez: application.properties gana, y pasarás una tarde entera preguntándote por qué tu YAML no se lee.

Son el peaje del formato, y todos son silenciosos: el fichero se lee, pero las propiedades quedan en otro sitio.

El primer caso produce un error de arranque claro (server no admite un valor escalar), pero variantes más sutiles simplemente dejan la propiedad huérfana y la aplicación arranca con el valor por defecto. Regla: dos espacios por nivel, nunca tabuladores, y activa en tu IDE la visualización de caracteres invisibles.

Spring Boot no exige que el nombre de la propiedad se escriba exactamente igual en todas partes. Aplica un algoritmo de relajación que considera equivalentes varias formas:

Las cuatro se resuelven a la misma propiedad. Esto es lo que permite que en un docker-compose.yml o en un Deployment de Kubernetes escribas:

y esos valores lleguen a ciclourbana.tarifa.desbloqueo, ciclourbana.red.capacidadMinima y server.port.

Las reglas para traducir una propiedad a variable de entorno son tres:

1. Los puntos (.) se convierten en guiones bajos (_).
2. Los guiones (-) se eliminan.
3. Todo en mayúsculas.

Así, ciclourbana.red.capacidad-minima → CICLOURBANA_RED_CAPACIDADMINIMA. Ese segundo punto es el que más quebraderos de cabeza da: mucha gente escribe CICLOURBANA_RED_CAPACIDAD_MINIMA y no funciona, porque ese nombre correspondería a ciclourbana.red.capacidad.minima, con un punto de más.

Dos limitaciones importantes de la relajación:

• Solo se aplica al enlazado de @ConfigurationProperties (lección 02-05) y a las propiedades del propio Spring Boot. Con @Value la coincidencia es exacta: @Value("${ciclourbana.tarifa-base}") no encuentra una propiedad escrita ciclourbana.tarifaBase.
• Las claves de un Map no se relajan: si defines ciclourbana.tarifas-por-usuario.estudiante-becado, la clave del mapa será literalmente estudiante-becado.

Convención recomendada: escribe siempre en kebab-case en los ficheros. Es la forma canónica, la que aparece en la documentación de Spring Boot y la que evita ambigüedades.

@Value inyecta el valor de una propiedad en un campo o parámetro. Vamos a sacar por fin de las constantes los precios de TarifaEstandar:

Observa que @Value va en los parámetros del constructor, no en los campos. Así los campos siguen siendo final y la clase sigue siendo construible en un test con new TarifaEstandar(new BigDecimal("0.50"), new BigDecimal("0.12")), sin Spring de por medio. Es la misma lógica de la lección 02-02 aplicada a la configuración.

Spring convierte automáticamente el texto al tipo del parámetro:

Para que List<String> funcione con @Value, el valor debe ser una cadena separada por comas, no una lista YAML:

Esta es ya la primera grieta de @Value, y no será la última.

Si una propiedad no existe, @Value falla en el arranque:

Se evita con la sintaxis ${clave:valorPorDefecto}:

Cuidado con un caso especial: si el valor por defecto contiene : (una URL, por ejemplo), hay que tener presente que solo cuenta el primer : como separador, así que @Value("${url:http://localhost:8080}") funciona correctamente y el valor por defecto es la URL completa.

@Value admite también expresiones SpEL con la sintaxis #{...} (almohadilla, no dólar):

Y una que sí es realmente práctica: valores aleatorios, para puertos o identificadores en pruebas.

@Value es cómodo para uno o dos valores sueltos, pero se queda corto en cuanto la configuración crece. Sus problemas:

Todas ellas las resuelve @ConfigurationProperties, que es el tema de la lección siguiente. La regla que aplicaremos en CicloUrbana: @Value para valores aislados y ocasionales; @ConfigurationProperties para todo lo demás.

Esta es la configuración base del proyecto, con explicación de cada bloque:

Las propiedades del servidor y de la aplicación más útiles:

Un aviso sobre server.servlet.context-path: si lo pones a /ciclourbana, la URL de nuestro endpoint pasa a ser http://localhost:8080/ciclourbana/api/v1/estaciones. Es un cambio que rompe todos los clientes y todos los ficheros .http de la lección 01-02, así que en CicloUrbana lo dejaremos en /.

Verifica que la configuración se aplica:

Todo lo anterior vive dentro del jar. En un despliegue real hace falta configuración que no se empaquete.

Spring Boot busca application.yaml automáticamente, y por este orden de prioridad, en:

1. ./config/ (subdirectorio config junto al jar)
2. ./ (directorio actual)
3. classpath:/config/
4. classpath:/ (dentro del jar)

Es decir, basta con dejar un fichero junto al jar para sobrescribir los valores empaquetados:

Permite incluir otros ficheros desde la configuración principal. Es la forma moderna y preferida frente a @PropertySource:

El prefijo optional: es clave: sin él, si el fichero no existe el arranque falla. Esto tiene su lógica —quieres saber si falta un fichero imprescindible— pero en desarrollo es incómodo, y por eso los ficheros propios de un entorno concreto se marcan casi siempre como opcionales.

spring.config.import admite también otros orígenes:

El formato configtree: merece una nota: en Kubernetes y en Docker Swarm los secretos se montan como ficheros, uno por clave, dentro de un directorio. Con configtree: Spring Boot lee ese árbol y convierte cada fichero en una propiedad. Es el mecanismo idiomático para secretos en contenedores, y lo retomaremos en la lección 07-04.

Sustituye por completo las ubicaciones por defecto, en lugar de añadirse a ellas:

Y spring.config.additional-location añade ubicaciones conservando las por defecto, que suele ser lo que realmente quieres:

Este apartado no es opcional. Es la parte de la lección con consecuencias más graves si se ignora.

Nunca, bajo ninguna circunstancia, escribas contraseñas, claves de API, tokens o certificados en un fichero que vaya al repositorio de código.

Lo que no debes hacer, aunque lo veas en tutoriales:

Por qué es tan grave, más allá de lo evidente:

• Git no olvida. Borrar la línea en un commit posterior no elimina el secreto: sigue en el historial, accesible con git log -p. Rotar la credencial es obligatorio, no opcional.
• El repositorio se copia. Forks, clones en portátiles, copias de seguridad, integraciones de CI, el ordenador de un becario. Un secreto en Git está, en la práctica, en muchos más sitios de los que crees.
• Los repositorios cambian de visibilidad. Un repositorio privado que se hace público filtra todo su historial de golpe. Es un accidente sorprendentemente frecuente.
• Los robots rastrean. Existen bots que escanean GitHub buscando patrones de claves; una clave de un proveedor cloud publicada por error se explota en minutos.

Qué hacer en su lugar:

1. Variables de entorno con marcador y sin valor por defecto. El fichero versionado declara qué necesita, no cuánto vale:

Fíjate en el detalle: la clave de la pasarela no tiene valor por defecto. Si alguien despliega sin definirla, el arranque falla inmediatamente con un mensaje claro. Eso es mucho mejor que arrancar y fallar en el primer pago.

2. Fichero externo fuera del árbol del proyecto, con permisos restringidos:

3. Un gestor de secretos, que es lo correcto en producción seria: HashiCorp Vault, AWS Secrets Manager, Azure Key Vault o los Secret de Kubernetes montados como configtree:. Se tratan en el módulo 8.

4. Protege el repositorio. Añade al .gitignore cualquier fichero local de secretos y considera un hook de pre-commit que detecte patrones sospechosos:

5. Si un secreto se filtra, rótalo. No lo borres del fichero y sigas. Invalida la credencial y emite una nueva. Es la única acción que realmente cierra el agujero.

Una última nota: en la lección 02-05 veremos cómo evitar además que un secreto acabe accidentalmente en los logs, y en el módulo 7, cómo Actuator oculta los valores sensibles en el endpoint /actuator/env.

Tener a la vez application.properties y application.yaml. Gana el .properties y el YAML parece ignorado. Borra uno.

Escribir mal el nombre de la variable de entorno. CICLOURBANA_RED_CAPACIDAD_MINIMA no es ciclourbana.red.capacidad-minima: los guiones se eliminan, no se convierten en guion bajo. El nombre correcto es CICLOURBANA_RED_CAPACIDADMINIMA.

Usar tabuladores en YAML. El fichero se rechaza con un error de análisis que no siempre señala la línea correcta. Configura tu editor para insertar espacios.

Poner --server.port antes del -jar. La JVM no lo entiende. Los -- van después del jar; los -D van antes.

Esperar relajación de nombres con @Value. No la hay. Con @Value la clave debe coincidir carácter a carácter.

Confundir ${...} con #{...}. El primero resuelve propiedades; el segundo evalúa SpEL. @Value("#{ciclourbana.ciudad}") intenta evaluar ciclourbana.ciudad como expresión y falla; lo correcto es ${ciclourbana.ciudad}.

Poner una contraseña en application.yaml. Repetido a propósito: es el error más caro de esta lección.

Consejo: nombra tus propiedades con un prefijo propio. Todo lo de CicloUrbana empieza por ciclourbana.. Así nunca colisionas con una propiedad de Spring Boot o de una librería, y grep -r "ciclourbana\." src/ te dice de un vistazo qué configura la aplicación.

Consejo: usa server.port=0 en las pruebas. Asigna un puerto libre y evita fallos cuando dos pruebas se ejecutan a la vez. Volveremos a ello en el módulo 6.

Consejo: documenta cada propiedad con un comentario. Quien despliegue tu aplicación dentro de un año lo agradecerá, y no necesitará leer el código para saber si umbral-bateria va en porcentaje o en voltios.

Consejo: en desarrollo, no dependas de la línea de comandos. Un application-dev.yaml con perfil (lección 07-02) es más reproducible que un comando largo que solo está en tu memoria.

Define ciclourbana.ciudad=Ribalta en application.yaml. Escribe un componente AvisoCiudad que registre su valor al arrancar. Después arranca la aplicación cuatro veces —normal, con variable de entorno, con propiedad de sistema y con argumento de línea de comandos— dando un valor distinto en cada una, y anota qué gana. Añade al componente el volcado de la fuente que aportó el valor.

TarifaEstudiante tiene todavía sus constantes escritas a fuego. Externalízalas a ciclourbana.tarifa.estudiante.precio-minuto y ciclourbana.tarifa.estudiante.minutos-gratis, con valores por defecto en el propio @Value para que la aplicación arranque aunque falten. Verifica que el importe de un alquiler de 45 minutos cambia al sobrescribir las propiedades por línea de comandos.

Prepara un despliegue realista: empaqueta el jar, crea un directorio config/ junto a él con un application.yaml que cambie el puerto a 9090, suba el desbloqueo a 0,60 € y lea la contraseña de la base de datos de una variable de entorno sin valor por defecto. Comprueba que la aplicación falla al arrancar si la variable no está definida, y que arranca correctamente cuando sí lo está.

Solución 1

Las cuatro ejecuciones:

Comentario: el método fuenteQueGana() implementa literalmente el algoritmo del Environment descrito en el apartado 1 —recorrer la lista ordenada y quedarse con la primera coincidencia— y por eso su resultado coincide siempre con el valor inyectado. Es un buen diagnóstico para tener a mano.

Nota sobre la fuente configurationProperties que aparece la primera en el listado: es una fuente sintética que Spring Boot usa internamente para el enlazado; no aporta valores propios.

Solución 2

Verificación con el DemostracionTarifas de la lección 02-02:

Comentario y error frecuente: si escribes @Value("${ciclourbana.tarifa.estudiante.minutosGratis:15}") —en camelCase— no enlazará con la propiedad minutos-gratis del fichero: tomará siempre el valor por defecto 15, en silencio y sin ningún error. Es exactamente la ausencia de relajación de nombres del apartado 5, y es una de las razones de peso para migrar a @ConfigurationProperties en la próxima lección.

Consejo: fíjate en que los precios se declaran como BigDecimal, no como double. En dinero, double produce errores de redondeo inaceptables (0.1 + 0.2 no es 0.3). Es una regla que no debe romperse nunca en un dominio con importes.

Solución 3

Primer intento, sin la variable de entorno:

Segundo intento, con ella definida:

Comentario: el fallo del primer intento es deseable. Un marcador sin valor por defecto convierte un olvido de despliegue en un error inmediato y evidente, en lugar de un fallo silencioso a las tres de la madrugada cuando alguien intente pagar. Es la misma filosofía de "fallar pronto y en voz alta" que vimos con la creación anticipada de singletons en la lección 02-03.

Consejo de despliegue: en un servidor real, la contraseña no se escribe en la línea de comandos —quedaría visible en ps aux y en el historial de la shell— sino en el fichero de unidad de systemd, en el EnvironmentFile correspondiente con permisos 600, o en el gestor de secretos de la plataforma. En Docker se pasa por variable de entorno del contenedor o, mejor, por secreto montado como fichero y leído con configtree: (lección 07-04).

La configuración de CicloUrbana ha salido del código. Sabes que el Environment no guarda valores sino una lista ordenada de PropertySource, y que toda la lógica de precedencia se reduce a en qué orden está esa lista: lo más externo gana, fuera del jar gana a dentro, y con perfil gana a sin perfil. Lo has comprobado tú mismo arrancando la misma aplicación con fichero, variable de entorno, propiedad de sistema y argumento de línea de comandos, y sabes distinguir la sintaxis de cada uno. Conoces las diferencias reales entre .properties y YAML —y por qué a partir de aquí el curso usa YAML— junto con la trampa de la indentación. Entiendes la relajación de nombres y las tres reglas que traducen ciclourbana.red.capacidad-minima a CICLOURBANA_RED_CAPACIDADMINIMA, incluida la eliminación de los guiones que tantos despliegues rompe. Sabes leer propiedades con @Value, darles valores por defecto, usar SpEL cuando aporta algo... y también conoces las siete limitaciones que hacen de @Value una herramienta de uso puntual. Sabes importar configuración externa con spring.config.import y spring.config.additional-location. Y, sobre todo, sabes que una credencial nunca va al repositorio, por qué el daño es permanente y cuáles son las alternativas reales.

Los precios de la red de Ribalta ya se pueden cambiar sin recompilar. Pero la solución tiene grietas evidentes: las claves están desperdigadas por varias clases, un camelCase mal escrito falla en silencio, nadie valida que el precio por minuto sea positivo y el IDE no ayuda a escribir las propiedades. La siguiente lección, Propiedades de Spring Boot, resuelve las cuatro cosas con @ConfigurationProperties: configuración tipada, agrupada en objetos inmutables, validada con Bean Validation, con conversión automática de Duration y DataSize, y con autocompletado en el IDE. Convertiremos toda la configuración de tarifas y de la red de Ribalta a esa forma, que es la que el proyecto mantendrá hasta el final del curso.