Java e Spring:
a plataforma que
mudou por baixo

1.1 O argumento honesto

Java não é escolhido por ser elegante. É escolhido por três coisas que quase nenhuma alternativa oferece ao mesmo tempo:

• Compatibilidade que raia o absurdo. Um jar compilado em 2011 corre hoje. Nenhuma outra plataforma grande leva a compatibilidade tão a sério, e é isso que sustenta sistemas com vinte anos que ninguém pode dar-se ao luxo de reescrever.
• Um tempo de execução que se explica sozinho. A JVM sabe dizer onde gastou memória, que thread ficou presa, que método aqueceu. Isso está incluído, não é um produto à parte.
• Quantidade de gente. É a pilha onde é mais fácil contratar, e onde é mais provável que o problema que tem já tenha resposta escrita por alguém.

Nada disto é entusiasmante. Tudo isto importa mais aos cinco anos de um sistema do que aos cinco meses — e é exactamente por isso que Java domina onde o horizonte é longo: banca, seguros, saúde, logística, retalho, administração pública.

1.2 A cadência, que decide mais do que parece

Sai uma versão de seis em seis meses, em Março e Setembro. De duas em duas anos, uma delas é LTS — a que recebe actualizações durante anos e a única que faz sentido pôr em produção num sistema que ninguém quer tocar todos os semestres.

1.3 Quando não escolher Java

Uma apostila que só diz bem da sua matéria não é útil. Casos em que a escolha é outra:

Repare no padrão: Java troca arranque lento e cerimónia inicial por previsibilidade a longo prazo. Quando não há longo prazo, está a pagar sem receber.

1.4 O que esta apostila é

Não é uma referência da linguagem — essa existe e é melhor que qualquer apostila. É o percurso do que distingue quem escreve Java que se aguenta de quem escreve Java que funciona no primeiro dia: o que a linguagem passou a permitir, o que a JVM exige que se saiba, o que o Spring está a decidir por si, e as três ou quatro armadilhas que aparecem sempre em produção e nunca no manual.

Pressupõe que já programa em alguma linguagem. Não pressupõe Java.

2.1 record: o fim do objecto de dados com oitenta linhas

O DTO clássico — campos privados, construtor, getters, equals, hashCode, toString — era cinquenta a cem linhas para dizer «isto tem três coisas lá dentro». Hoje:

// tudo o que estava acima, numa linha
public record Pedido(Long id, String cliente, BigDecimal total) {}

O compilador gera o construtor, os acessores, equals, hashCode e toString. É imutável por omissão, que é a parte que interessa: um record não pode ser alterado por engano três camadas abaixo.

public record Pedido(Long id, String cliente, BigDecimal total) {
  public Pedido {
    if (total.signum() < 0)
      throw new IllegalArgumentException("total negativo: " + total);
  }
}

2.2 sealed e correspondência de padrões: a alternativa à hierarquia aberta

A herança tradicional deixa qualquer pessoa estender a sua classe. sealed permite dizer exactamente quem pode — e, a partir daí, o compilador sabe que a lista está completa:

sealed interface Pagamento permits Cartao, Transferencia, Referencia {}

record Cartao(String ultimos4, int parcelas) implements Pagamento {}
record Transferencia(String iban) implements Pagamento {}
record Referencia(String entidade, String numero) implements Pagamento {}

// sem "default": se acrescentar um quarto tipo, ISTO DEIXA DE COMPILAR
String recibo(Pagamento p) {
  return switch (p) {
    case Cartao c        -> "Cartão terminado em " + c.ultimos4();
    case Transferencia t -> "Transferência de " + t.iban();
    case Referencia r    -> "Referência " + r.entidade() + " / " + r.numero();
  };
}

2.3 O resto do ruído que desapareceu

2.4 A cerimónia que ainda segura, e a que é entulho

3.1 A memória do processo não é a memória do heap

É a confusão que mais reinícios causa em contentores. O heap — onde vivem os objectos — é apenas uma parte do que a JVM consome:

3.2 O recolector de lixo: quando mexer (quase nunca)

Regra: mudar de recolector ou afinar as suas opções é das últimas coisas a tentar, não das primeiras. A esmagadora maioria dos problemas de pausa é lixo a mais a ser criado — e isso corrige-se no código, não na linha de comando. Um recolector afinado a esconder alocação desnecessária é uma dívida com juros.

3.3 Arranque lento, regime rápido — e o que isso implica

A JVM começa por interpretar, e vai compilando para código nativo o que vê ser usado. Consequência: a mesma função é dez vezes mais lenta nos primeiros segundos do que dez minutos depois.

3.4 A observabilidade que já pagou e quase ninguém usa

O Flight Recorder vem incluído na JVM e grava alocações, pausas do recolector, contenção de bloqueios, E/S e excepções, com um custo em regime da ordem de um por cento:

# gravar 60 segundos de um processo já a correr
jcmd <pid> JFR.start duration=60s filename=perfil.jfr

# e, no momento em que algo corre mal:
jcmd <pid> Thread.print        # onde está cada thread, agora
jcmd <pid> GC.heap_info        # estado do heap

Porque é que isto importa mais do que parece: na maior parte das pilhas, descobrir «que thread está bloqueada e à espera de quê» exige instalar alguma coisa antes de o problema acontecer. Aqui não exige. É a vantagem mais subestimada da plataforma, e existe desde antes de metade dos manuais que a ignoram.

4.1 O problema que resolvem

Uma thread de plataforma é uma thread do sistema operativo: custa cerca de um megabyte e alguns milissegundos a criar. Por isso ninguém cria uma por pedido — cria-se um reservatório de duzentas e reutilizam-se. E daí vem tudo:

Uma thread virtual é gerida pela JVM, custa alguns kilobytes, e quando bloqueia em E/S liberta a thread do sistema em vez de a ocupar. Podem existir milhões. O modelo passa a ser uma thread por pedido, que é o modelo que sempre foi mais fácil de ler — código sequencial, pilhas de chamadas que fazem sentido, depuração normal.

No Spring Boot, activar é uma linha:

# application.properties
spring.threads.virtual.enabled=true

4.2 A armadilha que não é a que avisam

O reservatório de threads não estava só a limitar threads. Estava, sem ninguém decidir isso, a limitar tudo o que estava a jusante:

4.3 Quando não valem a pena

5.1 O que a auto-configuração realmente faz

Não há magia. Há centenas de classes de configuração, cada uma protegida por condições que o Spring avalia no arranque. Todas se resumem à mesma pergunta:

Pôr o starter de JDBC no projecto faz aparecer no classpath uma classe de reservatório de ligações. A condição «existe essa classe e o utilizador não definiu um DataSource» passa a verdadeira, e o Spring cria um. Foi a dependência que configurou a aplicação — é esse o modelo mental inteiro.

# application.properties
debug=true

5.2 Substituir em vez de lutar

Como quase todas as condições incluem «e o utilizador ainda não definiu um», a forma de sair da omissão é definir o seu — não desligar nada:

@Bean
DataSource dataSource() {
  // a partir daqui, a auto-configuração do DataSource desiste sozinha
  return ...;
}

Desligar explicitamente (com exclude) é a excepção, não a regra — e quando aparece em muitos sítios costuma ser sinal de que se está a lutar contra o framework em vez de o usar.

5.3 As versões, e porque as fixa uma só linha

Repare na terceira linha: o mínimo é o Java 17, não a LTS actual. É deliberado — o Spring não obriga a empresa a saltar de versão de Java para receber correcções. Mas «suportado» não é «recomendado»: as threads virtuais do capítulo 4 exigem 21, e a correcção que muda o conselho exige 24.

5.4 Perfis e propriedades

# application.properties — comum a tudo
spring.application.name=pedidos

# application-dev.properties — só no perfil dev
# application-prod.properties — só no perfil prod

A ordem de precedência tem uma dúzia de níveis, mas o que interessa é a ponta: argumentos da linha de comando e variáveis de ambiente ganham sempre aos ficheiros. É isso que permite ter a mesma imagem de contentor em todos os ambientes, com a configuração injectada de fora (cap. 11.4).

6.1 A ideia, em duas linhas

Uma classe não constrói aquilo de que depende; recebe-o. O Spring mantém um registo de objectos geridos e, ao construir cada um, entrega-lhe o que ele pede. É só isto.

6.2 As três formas, e a que se usa

@Service
class ServicoPedidos {
  private final RepoPedidos repo;
  private final Pagamentos pag;

  ServicoPedidos(RepoPedidos repo,
                 Pagamentos pag) {
    this.repo = repo;
    this.pag = pag;
  }
}

@Service
class ServicoPedidos {
  @Autowired
  private RepoPedidos repo;
  @Autowired
  private Pagamentos pag;
}

6.3 Âmbitos, e o erro que daí vem

@Service
class ServicoRelatorio {
  private List<Linha> linhas = new ArrayList<>();  // ← partilhado por TODOS

  public Relatorio gerar(Pedido p) {
    linhas.clear();          // ← limpa o de outra pessoa
    ...
  }
}

6.4 Quando o Spring se queixa de um ciclo

A resolver A → B → A, o Spring desiste com um erro. A tentação é partir o ciclo com @Lazy ou uma propriedade que o permita. É quase sempre a resposta errada: um ciclo é o framework a detectar um problema de desenho que já lá estava.

As duas saídas boas: extrair para uma terceira classe a parte de que ambas precisam, ou inverter a dependência com um evento. A saída má é silenciar o aviso e ficar com duas classes que não podem existir uma sem a outra e ninguém consegue testar em separado. Se isto lhe aparece com frequência, Arquitetura e System Design trata do problema de fundo.

7.1 O controlador magro, e porquê

@RestController
@RequestMapping("/pedidos")
class ControladorPedidos {
  private final ServicoPedidos servico;

  ControladorPedidos(ServicoPedidos servico) { this.servico = servico; }

  @GetMapping("/{id}")
  RespostaPedido porId(@PathVariable Long id) {
    return RespostaPedido.de(servico.porId(id));
  }

  @PostMapping
  @ResponseStatus(HttpStatus.CREATED)
  RespostaPedido criar(@Valid @RequestBody CriarPedido corpo) {
    return RespostaPedido.de(servico.criar(corpo));
  }
}

Três responsabilidades e nenhuma mais: receber, validar, traduzir. A regra a fio de prumo — se o método tem um if de negócio, está no ficheiro errado.

7.2 Validar na fronteira

record CriarPedido(
    @NotBlank String cliente,
    @NotEmpty List<@Valid LinhaPedido> linhas,
    @Positive BigDecimal total) {}

Com @Valid no parâmetro, o Spring rejeita antes de chamar o serviço. O ganho: o serviço deixa de precisar de verificar se o cliente está preenchido — o tipo já garante isso. É a mesma ideia do record com construtor compacto do capítulo 2.1, aplicada à entrada HTTP.

7.3 Erros: um formato só, e normalizado

Sem tratamento central, cada erro sai de uma maneira: uns em JSON, outros em HTML, alguns com a pilha de chamadas exposta. O tratador global resolve isso, e o formato certo já é norma — Problem Details for HTTP APIs (RFC 7807):

@RestControllerAdvice
class TratadorErros {

  @ExceptionHandler(PedidoNaoExiste.class)
  ProblemDetail naoExiste(PedidoNaoExiste e) {
    var pd = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);
    pd.setTitle("Pedido não encontrado");
    pd.setDetail(e.getMessage());
    return pd;
  }
}

7.4 Duas coisas que o Spring Boot 4 trouxe e vale a pena conhecer

Versionamento de API deixou de ser artesanal. Há configuração automática para ele, tanto em MVC como em WebFlux, com propriedades dedicadas — em vez de cada equipa inventar o seu esquema de prefixos ou cabeçalhos.

Clientes HTTP declarativos: declara-se uma interface e o Spring implementa-a para chamar o serviço remoto:

interface ClientePagamentos {
  @PostExchange("/cobrancas")
  Cobranca cobrar(@RequestBody PedidoCobranca p);
}

É a mesma ideia que os repositórios de dados aplicam há anos: declarar a forma, deixar o framework escrever o corpo. O ganho real é ter um tipo em vez de uma cadeia de texto a montar um pedido — e, com isso, um sítio óbvio para pôr tempos limite e um teste.

8.1 O modelo mental que falta

A JPA faz parecer que se está a mexer em objectos. Não se está — está-se a dar instruções a uma coisa que emite SQL mais tarde, e mais SQL do que se pensa. Enquanto a transacção está aberta, as entidades estão geridas: o que lhes muda é registado e escrito no fim, sem ninguém chamar save. Fora dela, são objectos vulgares.

Quase tudo o que surpreende em JPA cabe numa frase: o SQL não sai onde está escrito o código.

8.2 O N+1, que é responsável pela maioria dos casos

List<Pedido> pedidos = repo.findAll();          // 1 consulta
for (Pedido p : pedidos) {
  System.out.println(p.getCliente().getNome());  // +1 consulta CADA
}

Com 47 pedidos: 48 consultas em vez de uma. Cada uma custa pouco; juntas, custam a página. Em desenvolvimento, com três registos de teste, é invisível.

# mostra o SQL que sai mesmo
spring.jpa.show-sql=true
logging.level.org.hibernate.orm.jdbc.bind=TRACE   # e os parâmetros

8.3 Carregamento preguiçoso e o momento em que a sessão fecha

Uma associação preguiçosa não traz dados; traz uma promessa. Se essa promessa for tocada depois de a transacção fechar — tipicamente durante a serialização da resposta — rebenta com LazyInitializationException.

Há uma opção que faz o erro desaparecer mantendo a sessão aberta durante a resposta. É a pior correcção possível: esconde o sintoma, mantém ligações à base de dados ocupadas durante a escrita da resposta HTTP, e transforma um erro claro numa fuga lenta de reservatório de ligações.

A correcção real é a do 7.1: converter para um objecto de resposta dentro da transacção. Aí, o que não foi carregado nunca é tocado depois, e o erro deixa de poder existir.

8.4 Transacções: onde acabam

8.5 Quando descer ao SQL

A JPA é boa a carregar e gravar agregados por identificador. É má em relatórios, agregações sobre muitas linhas e escritas em massa. Nesses casos, o caminho não é lutar com ela — é usar SQL directamente para essa consulta e manter a JPA no resto.

Não é derrota nem inconsistência. É reconhecer que são ferramentas diferentes: uma tem o modelo de domínio, a outra tem o poder da base de dados. Quem escolhe bases de dados por carga encontra o assunto em NoSQL e Bases de Dados Modernas.

10.1 A pergunta que decide o tipo de teste

«Preciso mesmo do Spring para este teste?» Na maioria dos casos a resposta é não, e responder honestamente é o que separa uma suíte de trinta segundos de uma de vinte minutos.

É a pirâmide de sempre, com os nomes do Spring. O capítulo 6.2 já tinha dado a chave: injecção por construtor faz com que a primeira linha desta tabela seja possível — new ServicoPedidos(repoFalso, pagamentosFalsos) e mais nada.

10.2 As fatias

@WebMvcTest(ControladorPedidos.class)
class ControladorPedidosTest {

  @Autowired MockMvc mvc;
  @MockitoBean ServicoPedidos servico;   // só o que o controlador precisa

  @Test
  void devolve404QuandoNaoExiste() throws Exception {
    given(servico.porId(9L)).willThrow(new PedidoNaoExiste(9L));

    mvc.perform(get("/pedidos/9"))
       .andExpect(status().isNotFound())
       .andExpect(jsonPath("$.title").value("Pedido não encontrado"));
  }
}

Levanta a camada web e nada mais: sem base de dados, sem clientes HTTP, sem o resto do contexto. É rápido porque é pequeno, e é preciso porque falha por uma razão só.

10.3 Testcontainers: a base de dados a sério, descartável

Testar contra uma base de dados em memória e correr contra PostgreSQL em produção significa testar outro sistema. Os dialectos divergem exactamente onde dói — tipos, datas, bloqueios, JSON.

@SpringBootTest
@Testcontainers
class PedidosIT {
  @Container @ServiceConnection
  static PostgreSQLContainer<?> bd = new PostgreSQLContainer<>("postgres:17");
  // @ServiceConnection liga a aplicação ao contentor sozinho
}

Um contentor real, criado para a suíte e deitado fora no fim. Custa alguns segundos de arranque e elimina a classe inteira de erros «passava nos testes, falhou em produção». É a troca mais fácil de justificar deste capítulo. Fundamentos de contentores em DevOps, Docker e Kubernetes; a disciplina de testes em Testing e Automação.

11.1 Um ficheiro, sem servidor a instalar

O Spring Boot produz um jar executável com a aplicação, as dependências e o servidor web lá dentro. Corre-se com java -jar. Não há Tomcat a instalar nem war a implantar — o modelo antigo, e a fonte de metade da má fama da pilha.

11.2 Contentor em camadas, e porquê

Copiar o jar inteiro para uma imagem torna cada compilação uma camada nova de dezenas de megabytes, mesmo que só tenha mudado uma linha. As dependências mudam raramente e o seu código muda sempre — separá-los faz a camada que muda ser pequena:

# extrai o jar em camadas por frequência de alteração
java -Djarmode=tools -jar app.jar extract --layers --launcher

Resultado prático: dependências em cache, e cada nova versão a transferir alguns megabytes em vez de algumas dezenas. Em implantações frequentes, é a diferença entre segundos e minutos.

11.3 Nativo com GraalVM: quando compensa mesmo

11.4 Configuração e segredos

A mesma imagem em todos os ambientes, com a configuração vinda de fora. Como as variáveis de ambiente ganham aos ficheiros (cap. 5.4), isto sai de graça:

# spring.datasource.url  ←→  SPRING_DATASOURCE_URL
docker run -e SPRING_DATASOURCE_URL=... -e SPRING_PROFILES_ACTIVE=prod app:1.4.2

11.5 Sondas: dizer a verdade sobre o estado

12.1 As doze regras

1. Compile para a LTS actual, e salte de LTS em LTS. A dívida de plataforma paga-se a prestações ou de uma vez.
2. Antes de optimizar, meça. O processador a 12% com latência alta significa espera, não falta de capacidade.
3. Conte as consultas de um pedido. Duas linhas de configuração; é o diagnóstico mais rentável desta apostila.
4. Nada de chamadas de rede dentro de uma transacção. Segura uma ligação à base de dados durante o tempo de outro sistema.
5. Carregamento é decisão por consulta, nunca por entidade.
6. Nunca devolva a entidade JPA na resposta HTTP. Converta dentro da transacção.
7. Injecte por construtor. É o que impede o objecto incompleto e mantém pressão sobre o desenho.
8. Um @Service não tem estado. A omissão é uma instância partilhada por todos os pedidos.
9. Ao ligar threads virtuais, mude o limite de sítio — não o deixe desaparecer.
10. Não fixe -Xmx em contentores, e lembre-se de que o heap não é a memória do processo.
11. Liveness não toca em dependências externas. Senão transforma uma avaria em reinício geral.
12. Pergunte se precisa mesmo do Spring nesse teste. Quase sempre não precisa.

12.2 Catálogo: onde verificar, e com que reservas

As cinco primeiras ligações foram verificadas em Setembro de 2026. A última bloqueia acesso automatizado, e por isso não foi possível confirmá-la da mesma maneira — o que, sendo irrelevante para quem a abre no navegador, é a razão pela qual não se diz aqui que foi verificada.

12.3 O que vem a seguir

12.4 A última ideia

Java tem trinta anos e a maior parte do que se diz sobre ele descreve uma versão que já não existe. Isso é irritante para quem o defende e conveniente para quem o ataca — mas o problema prático é outro: também descreve as bases de código onde vai trabalhar. Elas são antigas, foram escritas contra restrições reais, e a maioria das pessoas que as escreveu tinha razão na altura.

O ofício não é limpar tudo. É saber, para cada pedaço de cerimónia, se ainda segura alguma coisa — e ter a paciência de descobrir isso antes de apagar.