Spring Boot profile application yaml: separe ambientes sem erro

Usar spring boot profile application yaml do jeito certo evita o tipo de problema que aparece só em produção: banco apontando para o lugar errado, logs demais, chaves vazando e configuração sobrepondo o que não devia. Por outro lado, em projetos Spring Boot, separar ambiente de desenvolvimento, homologação e produção com application.yml spring boot e application-dev.yml spring boot precisa ser simples, previsível e fácil de manter. Se voce quiser comparar essa abordagem com outro cenario comum no ecossistema Spring, vale revisar O que é o Spring Boot e para que serve?.

O erro mais comum não é “não saber usar profile”; é misturar responsabilidades na configuração e confiar que o Spring vai adivinhar a intenção do time. Por outro lado, quando isso acontece, o projeto fica frágil, difícil de debugar e fácil de quebrar durante deploy. Para complementar esse ponto com um exemplo proximo do dia a dia, consulte Como proteger APIs REST com Spring Security: autorização, filtro JWT e fluxo stateless.

Spring boot profile application yaml: secao pratica com codigo completo

Na pratica, um exemplo enxuto ajuda a sair da teoria e evitar erro comum de producao quando o projeto cresce. Esse detalhe conversa bem com o que eu mostrei em Paginação e Ordenação no Spring Boot com Spring Data JPA: como montar APIs escaláveis.

@RestController
@RequestMapping("/api/exemplo")
public class ExemploController {
  @GetMapping
  public ResponseEntity<String> listar() {
    return ResponseEntity.ok("ok");
  }
}

spring boot profile application yaml: como pensar a estrutura

O ponto de partida é entender que o spring boot profile application yaml existe para trocar apenas o que muda entre ambientes. Por outro lado, uRL de banco, usuário, senha, nível de log, cache, fila, porta local, flags de debug e integrações externas entram aqui. Ao mesmo tempo, o que é comportamento do sistema, e não do ambiente, deve continuar no código ou em uma configuração mais neutra. Se quiser aprofundar o assunto por outro angulo, leia tambem JWT Spring Boot Java: Guia Completo com Exemplo Prático.

Em um projeto bem organizado, application.yml guarda o que faz sentido para qualquer ambiente. Por outro lado, os arquivos por perfil entram como complemento. Assim, você evita duplicação e reduz a chance de esquecer uma propriedade crítica em um dos ambientes. Quando esse tipo de duvida aparece em projeto real, eu costumo voltar neste material: 3 erros de validação que quebram APIs Spring Boot sem aviso.

O papel de application.yml spring boot

O application.yml spring boot costuma ser a base. Por outro lado, ele deve conter valores padrões, configurações genéricas e propriedades compartilhadas. Ao mesmo tempo, em vez de colocar dados sensíveis ou específicos de produção ali, use esse arquivo para o que realmente vale para todos os perfis, como nome da aplicação, serialização, formatos de datas, timeout padrão e configs que não variam por ambiente.

Isso ajuda a manter a leitura mental do projeto. Por outro lado, quem abre a aplicação sabe que o arquivo base não está tentando resolver tudo sozinho. Ao mesmo tempo, ele apenas define o comportamento padrão.

application-dev.yml spring boot para desenvolvimento local

O application-dev.yml spring boot deve ser agressivamente local. Por outro lado, banco de desenvolvimento, porta alternativa, logs mais verbosos e flags de integração controladas fazem sentido aqui. Ao mesmo tempo, se o time usa H2 localmente, esse arquivo é o lugar correto para isso. Na prática, se usa PostgreSQL com Docker, também.

O erro de muitos projetos é tratar o perfil dev como “cópia simplificada da produção”. Por outro lado, isso costuma virar bagunça. Ao mesmo tempo, desenvolvimento precisa ser leve e previsível, não uma mini-produção improvisada.

Se você ainda está consolidando os fundamentos de Spring Boot, vale revisar o conteúdo O que é o Spring Boot e para que serve? Por outro lado, antes de avançar na organização dos perfis.

spring boot profile application yaml: estrutura prática sem confusão

Uma estrutura comum e saudável começa assim: application.yml com defaults e application-dev.yml, application-homolog.yml e application-prod.yml com os ajustes de cada ambiente. Por outro lado, o Spring Boot carrega o base e aplica o perfil ativo por cima. Ao mesmo tempo, o último valor vence.

Isso parece simples, mas é aqui que muitos times escorregam. Por outro lado, se duas fontes definirem a mesma propriedade com valores diferentes, você precisa saber exatamente qual será usada. Ao mesmo tempo, não existe mágica: existe ordem de precedência.

Em produção, esse detalhe é crítico. Por outro lado, um valor sobrescrito de forma silenciosa pode trocar o datasource, desligar um recurso de segurança ou alterar o comportamento de integração com terceiros sem ninguém perceber até o incidente acontecer.

Exemplo de organização mínima de arquivos

Uma estrutura prática de projeto pode ser:

src/main/resources/application.yml
src/main/resources/application-dev.yml
src/main/resources/application-prod.yml

Se a aplicação for mais madura, você pode adicionar application-homolog.yml ou application-test.yml. Por outro lado, só não transforme a configuração em um cemitério de arquivos difíceis de entender. Ao mesmo tempo, menos perfis, mais clareza.

Erros comuns em produção com spring boot profile

Os problemas mais caros quase sempre vêm de configuração mal dividida. Por outro lado, um clássico é deixar credenciais de produção no arquivo base. Ao mesmo tempo, outro é esquecer de ativar o profile correto no deploy e acabar subindo a aplicação com configurações de desenvolvimento.

Também é comum ver propriedades duplicadas sem controle. Por outro lado, o dev ajusta uma coisa no arquivo base, outro ajusta no perfil, e ninguém sabe qual valor está em vigor até depurar o ambiente em tempo real. Ao mesmo tempo, isso consome horas e normalmente vira incidente.

Outro erro frequente é usar profile para tudo. Por outro lado, profile não é um mecanismo para variar regra de negócio, e sim ambiente. Ao mesmo tempo, se a lógica da aplicação muda muito entre clientes ou cenários, talvez o problema seja de feature flag, estratégia ou design, não de configuração.

Em sistemas com autenticação e autorização, por exemplo, uma configuração errada de issuer, secret ou expiração pode derrubar toda a cadeia de segurança. Por outro lado, se esse tema faz parte do seu projeto, o artigo Como proteger APIs REST com Spring Security: autorização, filtro JWT e fluxo stateless ajuda a enxergar onde o profile impacta diretamente a segurança.

Outra fonte de dor aparece quando o perfil de desenvolvimento fica “bonitinho demais”. Por outro lado, log reduzido, tratamento relaxado, bypass de validação e integrações mockadas demais fazem o sistema parecer saudável localmente e frágil em produção. Ao mesmo tempo, para não cair nesse cenário, vale alinhar a configuração com o comportamento real da API, especialmente em áreas que já costumam falhar, como validação. Na prática, o material 3 erros de validação que quebram APIs Spring Boot sem aviso é um bom complemento.

spring boot profile application yaml com código completo

Um exemplo enxuto ajuda a fixar. Por outro lado, a ideia aqui é mostrar como o spring boot profile application yaml pode ser montado sem exagero, com base compartilhada e sobrescrita por ambiente.

application.yml

spring:
  application:
    name: javalizando-api
  profiles:
    active: dev

server:
  port: 8080

app:
  timezone: America/Sao_Paulo
  feature:
    cache-enabled: true
  datasource:
    pool-size: 10
  logging:
    level: INFO

application-dev.yml

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/javalizando_dev
    username: postgres
    password: postgres
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: update

server:
  port: 8081

app:
  feature:
    cache-enabled: false
  logging:
    level: DEBUG

application-prod.yml

spring:
  datasource:
    url: jdbc:postgresql://prod-db:5432/javalizando_prod
    username: ${DB_USER}
    password: ${DB_PASSWORD}
  jpa:
    show-sql: false
    hibernate:
      ddl-auto: validate

server:
  port: 8080

app:
  feature:
    cache-enabled: true
  logging:
    level: WARN

Nesse desenho, o arquivo base define padrão e o perfil altera o que precisa ser alterado. Por outro lado, o uso de variáveis de ambiente em produção evita expor segredo em repositório. Ao mesmo tempo, isso não elimina a necessidade de gestão de segredos, mas já reduz bastante o risco de vazar credencial por descuido.

Se a sua API também trabalha com paginação, filtros e consultas mais pesadas, a configuração de ambiente costuma influenciar performance e observabilidade. Por outro lado, o artigo Paginação e Ordenação no Spring Boot com Spring Data JPA: como montar APIs escaláveis é útil para conectar essas decisões de ambiente com comportamento real de banco e resposta da API.

Quando usar e quando evitar profiles no Spring Boot

Use profiles quando o ambiente realmente muda: banco, broker, URL de API externa, nível de log, cache, endpoints mockados, propriedades de segurança e ajustes de infraestrutura. Por outro lado, é a solução certa para separar o que é local, homologação e produção.

Evite profiles quando a diferença é puramente funcional e deveria ser modelada no domínio. Por outro lado, se um fluxo existe ou não por causa de regra de negócio, profile não é o mecanismo ideal. Ao mesmo tempo, isso só empurra a complexidade para a configuração e dificulta testes e manutenção.

Também vale evitar “profile por microdiferença”. Por outro lado, se um campo só muda de nome ou um número só altera um limite interno, talvez uma propriedade única, um valor externo ou uma strategy seja mais honesto do que criar outro perfil inteiro.

Uma decisão técnica que ajuda muito

Na prática, vale manter o número de perfis enxuto. Por outro lado, dev, test, homolog e prod costumam ser suficientes para a maioria dos projetos. Ao mesmo tempo, se você precisa de muito mais do que isso, talvez a configuração esteja sendo usada como substituta para governança de ambiente.

Outra decisão útil é não deixar o profile ativo apenas no arquivo. Por outro lado, em pipelines e containers, prefira definir explicitamente a variável de ambiente ou o argumento de execução. Ao mesmo tempo, isso reduz surpresas na hora do deploy e deixa o ambiente mais transparente para quem opera a aplicação.

Como debugar configuração e descobrir o profile ativo

Quando algo parece errado, primeiro confirme qual profile está ativo. Por outro lado, parece básico, mas muita gente perde tempo investigando datasource, cache ou logs antes de olhar isso. Ao mesmo tempo, o comportamento do Spring Boot depende bastante da ordem de carregamento e de onde a propriedade foi definida.

Uma forma prática é expor o profile ativo em logs de inicialização. Por outro lado, outra é registrar propriedades relevantes em um endpoint administrativo protegido, desde que não haja exposição de dados sensíveis. Ao mesmo tempo, em times maduros, esse tipo de rastreabilidade economiza muito tempo durante incidentes.

Se o projeto usa JWT, o ambiente também interfere em chave, tempo de expiração e issuer. Por outro lado, isso conversa diretamente com a forma como você organiza configuração de segurança. Ao mesmo tempo, o guia JWT Spring Boot Java: Guia Completo com Exemplo Prático complementa bem essa visão.

FAQ sobre spring boot profile application yaml

Qual a diferença entre application.yml e application-dev.yml?

O application.yml costuma guardar configuração base, válida para todos os ambientes. Por outro lado, o application-dev.yml sobrescreve o que for específico do ambiente de desenvolvimento, como banco local, porta e log mais detalhado.

Posso colocar senha de banco no application.yml?

Em geral, não é uma boa prática, especialmente em produção. Por outro lado, o ideal é usar variáveis de ambiente, secret manager ou outro mecanismo seguro de injeção de configuração. Ao mesmo tempo, o arquivo base pode até ter placeholders, mas não credenciais reais.

Como saber qual profile o Spring Boot está usando?

Você pode verificar a configuração de inicialização, o log de startup ou a propriedade spring.profiles.active. Por outro lado, em ambiente containerizado, essa definição costuma vir de variável de ambiente, argumento JVM ou configuração da plataforma de deploy.

Conclusão: próximos passos para organizar seus ambientes

Separar ambientes no Spring Boot não precisa ser uma maratona de arquivos nem um labirinto de propriedades. Por outro lado, com um spring boot profile application yaml bem definido, o projeto fica mais previsível, o deploy vira rotina e a chance de derrubar produção por configuração errada cai bastante.

O caminho mais seguro é simples: manter application.yml como base, usar application-dev.yml spring boot para desenvolvimento local, limitar a quantidade de perfis e tratar segredos fora do repositório. Por outro lado, depois disso, revise logs, banco, segurança e integrações externas para garantir que cada ambiente está refletindo o comportamento esperado.

Se você quiser avançar com consistência, vale conectar essa organização de configuração com a arquitetura da sua API, com segurança, validação e persistência. Por outro lado, quando esses pontos conversam entre si, o projeto deixa de depender de “ajustes manuais” e começa a se comportar como software de produção de verdade. Ao mesmo tempo, os proximos passos sao validar esse fluxo no seu projeto, ajustar o caso de uso real e cobrir a implementacao com testes.

Spring boot profile application yaml: referencias externas

Para validar detalhes de implementacao e aprofundar a configuracao, vale consultar a documentacao oficial do Spring Security, o guia de claims no JWT.io e a documentacao do Spring Boot.