APRENDER. PRATICAR. EVOLUIR.O valor escrito não é necessariamente o valor usado
Spring Boot combina fontes como ficheiros, variáveis de ambiente e argumentos. Entre essas fontes, na configuração normal, argumentos de linha de comando podem substituir variáveis de ambiente, que podem substituir dados de configuração. Uma pergunta com esse conjunto delimitado deve explicitar que não há fontes adicionais nem código a alterar a ordem.
Se delivery.batch-size continua a 60 apesar de a variável ter sido alterada para 25, procura um argumento antigo antes de reconstruir o jar. Regista a origem e o valor efetivo, evitando publicar segredos na evidência. Não presumas que o ficheiro mais recentemente editado tem maior precedência; o instante da edição não é a regra de resolução.
Um tipo de propriedades precisa de registo
@ConfigurationProperties agrupa propriedades segundo um prefixo e permite ligá-las a uma estrutura. Um record com construtor canónico pode usar binding por construtor. O tipo tem de ser registado através de EnableConfigurationProperties ou de scan de propriedades apropriado. Anotar o prefixo não substitui essa decisão de composição.
O binding por construtor de propriedades também não é a mesma operação que injetar beans de negócio num Component. Mantém a configuração centrada nos valores do ambiente e passa-a aos serviços que a utilizam. @DefaultValue fornece um valor textual convertido quando a propriedade está em falta; não deve ser interpretado como autorização para ignorar um valor explicitamente inválido.
Nomes e unidades pertencem ao contrato
Para transformar o nome canónico delivery.batch-size numa variável de ambiente segundo a regra documentada, o ponto torna-se underscore, o hífen é removido e as letras passam a maiúsculas: DELIVERY_BATCHSIZE. Não acrescentes um separador onde a regra remove o hífen. Uma variável com aspeto plausível pode não representar a propriedade que querias alterar.
Na ligação a Duration, um número sem unidade usa milissegundos por defeito, salvo uma unidade indicada por DurationUnit. O texto 5s comunica cinco segundos; PT5S também representa uma duração explícita. Escolher um tipo Duration melhora o contrato, mas a política ainda precisa de definir quais durações são aceitáveis para a operação.
Conversão e validação são decisões diferentes
Converter texto para int demonstra que a representação pode ser interpretada como esse tipo. Não demonstra que 0 seja uma dimensão de lote válida. No exemplo, Min e Max delimitam batchSize, e NotBlank limita destination. Validated ativa a validação das propriedades com uma implementação Jakarta Validation compatível presente.
Uma violação deve impedir a aceitação de uma configuração que o serviço não pode usar. Retirar a anotação para permitir arranque não corrige o valor. Também não basta existir um texto de destino: NotBlank não verifica rede, autorização ou disponibilidade. Cada regra deve conservar o seu alcance, e os efeitos da aplicação só devem começar depois de as condições necessárias estarem satisfeitas.
Perfis selecionam configuração, sem substituir a precedência
Um perfil pode delimitar partes da configuração ou a inclusão de componentes. spring.profiles.active segue a ordem normal das fontes e pode ser substituído por uma fonte de maior prioridade. Um ficheiro empacotado que declara dev não prova, por si só, que dev seja o perfil efetivamente ativo.
spring.profiles.active tem de ficar num documento não específico de perfil; não pode ser colocado num documento já ativado por spring.config.activate.on-profile. Para agrupar perfis relacionados, um grupo declarado na configuração não específica pode representar a intenção. A ativação de um perfil não comprova que as credenciais e destinos desse ambiente sejam válidos.
Listas e ficheiros importados têm regras próprias
Uma lista fornecida por uma fonte de maior prioridade substitui a lista anterior. Se o perfil define apenas o nome do primeiro elemento, não deves presumir que herda a url desse elemento nem os elementos restantes. Para uma lista operacional completa, fornece os dados que a política exige ou escolhe conscientemente outro modelo de configuração.
Um ficheiro importado por spring.config.import pode substituir valores do documento que o importa, independentemente da posição da linha de importação nesse documento. optional permite que uma localização falte; não prova que os valores indispensáveis estejam disponíveis. Se um ficheiro é obrigatório, torna essa exigência observável no arranque e valida também o seu conteúdo.
Leitura guiada da configuração de entrega
DeliveryConfiguration regista explicitamente DeliveryProperties. O record liga delivery.batch-size e delivery.destination através do construtor, com defaults apenas para ausências. Segue três casos: ausência de batch-size produz 20; zero falha o mínimo; 25 satisfaz os limites. Estes resultados pressupõem a origem efetiva já identificada e o provider de validação presente.
O destino predefinido archive é um identificador lógico ilustrativo. O exemplo não inicia entregas nem demonstra acesso a um serviço externo. Uma revisão completa conserva a distinção entre configuração bem formada, configuração autorizada e operação bem-sucedida. Aqui, a aprendizagem centra-se na primeira barreira e na capacidade de justificar a decisão de aceitar ou rejeitar valores.
// Separate files under the application's component-scan root.
// Spring Boot 4.1.1 / Java 25; compatible Jakarta Validation provider present.
// DeliveryProperties.java
package com.acme.dispatch;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.NotBlank;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.bind.DefaultValue;
import org.springframework.validation.annotation.Validated;
@ConfigurationProperties("delivery")
@Validated
public record DeliveryProperties(
@DefaultValue("20") @Min(1) @Max(100) int batchSize,
@DefaultValue("archive") @NotBlank String destination) { }
// DeliveryConfiguration.java
package com.acme.dispatch;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;
@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(DeliveryProperties.class)
public class DeliveryConfiguration { }Lê os resultados para batch-size ausente, 0 e 25, com uma origem efetiva conhecida. O default só trata ausência; zero viola o limite. destination exige texto não vazio, mas não confirma a existência ou autorização de um destino externo.
Armadilhas comuns
Confundir default com substituição de valores inválidos; supor fusão de listas; colocar ativação num documento de perfil; permitir ausência de um ficheiro que o contrato exige.
Tópicos relacionados: Contexto da aplicação e dependências · Validação, erros e contratos de resposta · Saúde, observabilidade e diagnóstico
Configuração aceite exige origem conhecida, conversão adequada e regras válidas. A precedência explica o valor observado; a validação decide se pode ser usado.
Referência: External configuration ordering · Spring Boot 4.1.1 / Spring Framework 7.0.9 / Java 25