O Spring Boot 4 não é um update qualquer. Ele muda o baseline da plataforma inteira — e quem tentar migrar no modo "atualizei a versão e rezei" vai descobrir isso da pior forma possível: em produção, numa sexta-feira à noite, com o time de plantão tentando entender por que a API parou de subir.
Neste guia, eu separo o que realmente muda, o que é só barulho de release notes, e o passo a passo que sigo para migrar APIs em produção sem susto. Se você é responsável por um sistema que fatura dinheiro de verdade, leia até o fim — a diferença entre uma migração tranquila e um incidente está quase sempre na ordem das etapas, não na dificuldade técnica.
Por que essa versão é diferente das anteriores
Migrações de minor version (3.2 → 3.3, por exemplo) são quase transparentes. O Boot 4 é diferente porque ele é um marco de plataforma: muda a versão mínima do Java, sobe o Spring Framework para a versão 7, atualiza o Jakarta EE e — o ponto mais perigoso — remove tudo que foi marcado como deprecated durante todo o ciclo do 3.x.
Isso significa que o seu código pode compilar perfeitamente no Boot 3.5 e quebrar em dezenas de pontos no Boot 4. A boa notícia: quase tudo quebra em compile time ou na inicialização, não no meio de uma requisição. Com o processo certo, você descobre os problemas no seu computador, não no dashboard de monitoramento.
O que muda de verdade
1. Baseline Java 25
O Spring Boot 4 exige Java 25 como versão mínima. Se seu projeto ainda roda em Java 17 ou 21, esse é o primeiro degrau da escada — e não dá para pular.
A boa notícia é que o Java 25 já está maduro o suficiente para uso real em produção: virtual threads estáveis, pattern matching consolidado, records, sealed classes e melhorias significativas de performance no GC. Na prática, muitos times descobrem que o maior ganho da migração não vem do Boot em si, mas do Java novo que ele obriga você a adotar.
2. Spring Framework 7 por baixo
O Boot 4 sobe no Spring Framework 7, que traz mudanças estruturais:
Suporte de primeira classe a virtual threads em todo o stack — não só no Tomcat, mas em agendamento, mensageria e clientes HTTP
API modular mais enxuta, com menos JARs no classpath e inicialização mais rápida
Melhorias profundas em AOT e compilação nativa com GraalVM, aproximando o desempenho nativo do fluxo de desenvolvimento comum
Remoção de APIs antigas do próprio Framework, o que afeta quem usa integrações menos comuns
3. Jakarta EE 11
Se você passou pela dor do javax → jakarta no Boot 3, respira: essa parte já está resolvida no seu código. O Boot 4 sobe para Jakarta EE 11, o que impacta principalmente quem usa Servlets, Bean Validation e JPA em versões defasadas. A migração aqui é mais sobre subir dependências do que reescrever código.
4. Deprecações finalmente viraram remoção
Aqui mora o perigo real da migração. Tudo que foi marcado como deprecated no ciclo do Boot 3.x foi removido no 4:
Propriedades de configuração antigas pararam de funcionar
Classes utilitárias e extensões de teste sumiram do classpath
Configurações automáticas substituídas por novas abordagens não existem mais
Seu build vai quebrar — e isso é bom. Quebra em compile time, com mensagem clara, no seu ambiente. O cenário alternativo é descobrir em produção que uma propriedade silenciosamente parou de ter efeito.
5. Observabilidade e teste
O stack de observabilidade foi atualizado para versões mais recentes do Micrometer e do OpenTelemetry, com melhor suporte a tracing distribuído nativo. No lado de testes, o suporte a versões antigas do JUnit 4 foi removido — se seu projeto ainda tem testes legados em JUnit 4, esse é um trabalho extra que precisa entrar no plano.
O checklist de migração que uso em produção
Passo 1 — Estabilize no 3.5.x primeiro. Suba para a última versão 3.5.x e rode a suíte completa de testes. Se algo quebra aqui, o problema não é o Boot 4 — e você acabou de descobrir isso de graça. Resolva todas as deprecações reportadas nesse estágio: cada warning do 3.5 é um futuro erro de compilação no 4.
Passo 2 — Suba o Java antes do Boot. Atualize para Java 25 mantendo o Boot 3.5. Assim você isola os problemas: se quebrar, você sabe exatamente qual camada causou. Valide dependências nativas (drivers JDBC, bibliotecas com bytecode) nessa etapa.
Passo 3 — Atualize o ecossistema Spring. Spring Security, Spring Data, Spring Cloud e drivers de banco precisam estar em versões compatíveis com o Framework 7 antes do próprio Boot subir. Ordem importa: dependência desatualizada é a causa número 1 de falha de migração.
Passo 4 — Use o properties migrator. Adicione o spring-boot-properties-migrator como dependência durante a migração. Ele identifica propriedades renomeadas e reporta no log durante a inicialização. Remova a dependência quando terminar — ela é temporária por design.
Passo 5 — Rode com modo estrito de deprecações. Execute os testes com flags que tratam deprecações como erro e capture tudo que aponta para APIs removidas. Cada item dessa lista é trabalho real: estime tempo para ele.
Passo 6 — Migre em branch, valide com canary. Nunca migre direto na main de produção. Faça o upgrade em branch separado, rode a suíte completa, valide em ambiente de staging com dados realistas e faça deploy canary: 5% do tráfego primeiro, monitorando latência, taxa de erro e consumo de memória por 48 horas antes de expandir.
O erro mais comum que vejo em migração
Times tentam migrar Boot, Java e refatorações ao mesmo tempo. Resultado: ninguém sabe o que quebrou o quê, o PR tem 400 arquivos alterados e o review vira inviável.
A regra é simples: uma mudança por vez, sempre com testes verdes entre cada passo. Migração é trabalho de engenharia, não de sorte. Se sua suíte de testes é fraca, o primeiro investimento da migração é fortalecê-la — porque ela é sua única rede de proteção.
Vale a pena migrar agora?
Se sua API está em Boot 3.3+ com Java 21, a migração é tranquila e os ganhos principais são performance com virtual threads nativos, inicialização mais rápida e preparação para o futuro do ecossistema — novas features do Spring vão nascer no 4, não no 3.
Se você está em Boot 2.x ainda, o caminho é: 2.7 → 3.x → 3.5 → 4. Sem atalhos. Cada salto tem seu próprio conjunto de breaking changes, e pular etapas multiplica o custo de diagnóstico.
E você, já começou a migração? Conta nos comentários qual foi o maior obstáculo que encontrou — provavelmente alguém aqui já passou pelo mesmo problema e pode te poupar horas.
