Cesar Schutz

Java 29 (próxima LTS) — o que o Java 26 e o 27 já trouxeram

Wed, 16 Sep 2026 00:00:00 GMT

Última atualização: 16/09/2026. Cobre o Java 26 (lançado em 17/03/2026) e o Java 27 (lançado em 15/09/2026). O Java 28 ainda está em desenvolvimento, e o conteúdo do Java 29 ainda não foi definido.

A série “Atualizações do Java” acompanha só as versões LTS. Entre uma LTS e outra saem versões intermediárias a cada seis meses, e cada uma pode trazer recursos novos, promover um preview a final ou remover algo antigo. Este post junta o que já saiu desde o Java 25 e diz em qual versão cada coisa chegou e em qual status ela está hoje. Ele será atualizado quando o Java 28 e o Java 29 saírem.

O Java 26 chegou à disponibilidade geral (GA, a versão final para produção) em 17 de março de 2026 (JDK 26), e o Java 27, em 15 de setembro de 2026 (JDK 27). A próxima LTS prevista é o Java 29, em setembro de 2027.

Essa previsão vem do Oracle Java SE Support Roadmap (atualizado em 15/09/2026). Ele classifica o 26, o 27 e o 28 como não LTS e avisa que essa classificação e as datas ainda podem mudar. Nesse roadmap, cada versão não LTS tem Premier Support só até a seguinte sair: setembro de 2026 para o 26 e março de 2027 para o 27. Para o Java 25, a Oracle informa Premier Support até setembro de 2030; para o Java 29, prevê até setembro de 2032. Outros fornecedores de builds do OpenJDK publicam seus próprios prazos. Na data desta atualização, o OpenJDK ainda não tinha publicado a página do projeto JDK 29.

O post é para quem está no Java 25 e quer acompanhar o que muda até o 29. O ponto de partida é o post do Java 25; quem vem do Java 21 deve ler os dois. Para a visão geral de ciclo de releases, distribuições e estratégia de migração, veja o guia de atualizações do Java.

Como o post está organizado. Primeiro, uma linha do tempo com todas as trilhas. Depois, os recursos que já são definitivos, agrupados por tema: concorrência, APIs, JVM, ferramentas, segurança e remoções. Em seguida vêm os recursos que continuam em preview ou incubadora, uma lista do que pode quebrar na migração vindo do Java 25 e, por fim, a tabela de todas as JEPs de cada versão, incluindo o que já tem alvo no Java 28. Cada recurso traz a linha Chegou em, com a versão e a JEP (a proposta formal de mudança do OpenJDK) em que ele apareceu.

Preview e incubadora não são definitivos. Pela JEP 12, um recurso em preview está completo, mas não é permanente: numa versão futura ele pode virar final, com ou sem ajustes, ou ser removido. Para usá-lo é preciso --enable-preview na compilação e na execução, e uma JVM não carrega classes compiladas com os previews de outra versão. Já as APIs em incubadora (JEP 11) ficam em módulos jdk.incubator.*, precisam de --add-modules e podem mudar ou sumir com a mesma liberdade. Os exemplos de preview abaixo refletem o Java 27 e podem precisar de ajuste no Java 28 ou no 29.

Os exemplos que só dependem do Java 26 foram compilados e executados no Temurin 26.0.2. Os que usam recursos exclusivos do 27 (Set.ofLazy, o StructuredTaskScope do 27, o mascaramento de dados do JFR e -XX:AOTMode=required) seguem as assinaturas do código-fonte do JDK 27 (tag jdk-27-ga) e as notas de release.

Linha do tempo#

O diagrama mostra cada trilha versão a versão. A linha vermelha marca a data desta atualização: à direita dela, tudo é previsão.

Java 26 (página do projeto), 10 JEPs: HTTP/3 no HttpClient, cache AOT com qualquer coletor, G1 com menos sincronização, avisos para quem altera campos final por reflexão e a remoção da Applet API.
Java 27 (página do projeto), 9 JEPs: G1 como padrão em qualquer ambiente, compact object headers por padrão, TLS 1.3 com troca de chaves pós-quântica e mascaramento de dados sensíveis nas gravações do JFR.
Java 28 (página do projeto), 6 JEPs com alvo até agora, entre elas a API PEM final e o primeiro preview de Value Objects (detalhes).

Os recursos em preview e incubadora (Structured Concurrency, primitivos em patterns, Lazy Constants, API PEM e Vector API) estão reunidos em Ainda em preview ou incubadora.

Concorrência#

Virtual threads liberam a carrier enquanto esperam a inicialização de uma classe#

Chegou em: Java 26 (final, JDK-8369238)

Uma virtual thread não tem thread do sistema operacional própria: ela é executada em cima de uma carrier thread, uma thread de plataforma de um pool compartilhado pela JVM. Quando a virtual thread bloqueia, a JVM a “desmonta” da carrier, que fica livre para executar outra virtual thread. Se ela não pode ser desmontada, fica presa (pinned) e ocupa a carrier durante toda a espera. O Java 24 resolveu esse problema para synchronized (veja synchronized não prende mais virtual threads, no post do Java 25), mas ainda havia outros casos.

O problema. Até o Java 25, uma virtual thread que precisava de uma classe que outra thread ainda estava inicializando (rodando o bloco static, por exemplo) ficava presa à carrier enquanto esperava. No pior caso, todas as carriers ficavam presas nessa espera enquanto o inicializador dependia de uma virtual thread para terminar, e a aplicação inteira travava.

O que mudou. Segundo as notas de release do Java 26, na maioria dos casos a virtual thread agora é desmontada durante essa espera e libera a carrier. A mudança não é uma JEP e não exige nenhuma alteração no código: basta rodar no Java 26 ou posterior.

APIs da biblioteca padrão#

HTTP/3 no HttpClient#

Chegou em: Java 26 (final, JEP 517)

O problema. O java.net.http.HttpClient (JEP 321, Java 11, HTTP Client no post do Java 11) falava HTTP/1.1 e HTTP/2. O HTTP/3, padronizado pela IETF em 2022, troca o TCP pelo QUIC, um protocolo de transporte que roda sobre UDP. A JEP cita as vantagens: handshakes (a negociação inicial da conexão) potencialmente mais rápidos, menos problemas de congestionamento, como o head-of-line blocking (quando um pacote perdido atrasa todas as requisições da conexão), e transporte mais confiável em redes que perdem muitos pacotes.

O que mudou. O HTTP/3 é opt-in: o padrão continua sendo HTTP/2. Você escolhe HttpClient.Version.HTTP_3 no cliente ou em cada requisição. Por padrão, se o servidor não fala HTTP/3, o cliente volta para HTTP/2 ou HTTP/1.1 sem erro (a exceção é o modo HTTP_3_URI_ONLY, na tabela abaixo). Como não dá para saber de antemão se o servidor fala HTTP/3, a JEP descreve quatro estratégias de descoberta:

Configuração	Comportamento
`HTTP_3` como versão preferida da requisição	Tenta HTTP/3 primeiro e cai para HTTP/2 ou HTTP/1.1 se a conexão não abrir em tempo razoável.
`HTTP_3` só no cliente, sem versão na requisição	Tenta HTTP/3 e HTTP/2 ou HTTP/1.1 em paralelo e usa a conexão que abrir primeiro.
`HttpOption.H3_DISCOVERY` com `Http3DiscoveryMode.ALT_SVC`	Começa em HTTP/2 ou HTTP/1.1 e passa a usar HTTP/3 nas requisições seguintes se o servidor anunciar o serviço alternativo.
`HttpOption.H3_DISCOVERY` com `Http3DiscoveryMode.HTTP_3_URI_ONLY`	Usa só HTTP/3 e falha se o servidor não responder por ele.

As duas últimas estratégias usam a opção de requisição H3_DISCOVERY e exigem HTTP_3 como versão preferida no cliente ou na requisição.

O exemplo abaixo usa a terceira estratégia (ALT_SVC). Ele acessa um servidor externo, www.google.com, e só chega ao HTTP/3 porque esse servidor anuncia suporte no cabeçalho Alt-Svc da resposta. Com um servidor que não anuncia HTTP/3, as duas chamadas saem em HTTP_2; sem acesso à internet, send lança exceção.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpOption;
import java.net.http.HttpOption.Http3DiscoveryMode;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse.BodyHandlers;

public class ClienteHttp3 {
    public static void main(String[] args) throws Exception {
        // Preferência por HTTP/3 em todas as requisições deste cliente
        HttpClient client = HttpClient.newBuilder()
                .version(HttpClient.Version.HTTP_3)
                .build();

        // Servidor externo: o resultado depende de ele anunciar HTTP/3 (Alt-Svc)
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://www.google.com/"))
                .setOption(HttpOption.H3_DISCOVERY, Http3DiscoveryMode.ALT_SVC)
                .GET()
                .build();

        // 1ª chamada: sai por HTTP/2 e lê o Alt-Svc da resposta
        var primeira = client.send(request, BodyHandlers.discarding());
        IO.println(primeira.version());   // HTTP_2

        // 2ª chamada: já usa HTTP/3, se o servidor anunciou
        var segunda = client.send(request, BodyHandlers.discarding());
        IO.println(segunda.version());    // HTTP_3
    }
}

No Temurin 26.0.2, com acesso à internet em 16/09/2026, esse programa imprimiu HTTP_2 e depois HTTP_3.

Quando usar e cuidados. Vale testar o HTTP/3 com servidores e CDNs que já o oferecem, principalmente em redes com perda de pacotes. Limitações da primeira versão, segundo a JEP: só funciona com o provider TLS padrão (SunJSSE), não há API pública de QUIC nem servidor HTTP/3, e o java.net.URL continua só em HTTP/1.1.

APIs menores sem JEP#

Nem toda mudança de API passa por uma JEP. As notas de release registram várias adições pequenas e úteis.

Java 26 (notas de release):

Process implementa AutoCloseable (e Closeable): fechar o processo garante que ele terminou e libera streams e recursos, então dá para usá-lo em try-with-resources.
Comparator ganhou os métodos default min(T, T) e max(T, T).
UUID.ofEpochMillis(long) cria UUIDs versão 7, que começam pelo timestamp, em milissegundos, e por isso ficam ordenados pelo instante de criação.
Instant.plusSaturating(Duration) soma sem estourar: no limite, devolve Instant.MIN ou Instant.MAX. Duration ganhou as constantes MIN e MAX.
HttpRequest.BodyPublishers.ofFileChannel(channel, offset, length) envia só um trecho de um arquivo, útil para upload em partes.
java.nio.ByteOrder virou enum e pode ser usado em switch.
Suporte a Unicode 17.0 e ao JDBC 4.5 MR, que inclui os tipos SQL DECFLOAT e JSON.

import java.time.Duration;
import java.time.Instant;
import java.util.Comparator;
import java.util.UUID;

public class ApisMenores {
    public static void main(String[] args) throws Exception {
        // Process agora é AutoCloseable: processo e streams são liberados ao sair do bloco
        // (a saída de "java -version" vai para o stream do processo, não aparece aqui)
        try (Process p = new ProcessBuilder("java", "-version").start()) {
            p.waitFor();
        }

        // Comparator ganhou min/max entre dois valores
        Comparator<String> porTamanho = Comparator.comparingInt(String::length);
        IO.println(porTamanho.max("java", "kotlin"));   // kotlin

        // UUID versão 7, ordenável pelo instante de criação
        UUID id = UUID.ofEpochMillis(System.currentTimeMillis());
        IO.println(id.version());                        // 7

        // Soma saturada: em vez de estourar, para no limite
        IO.println(Instant.MAX.minusSeconds(10).plusSaturating(Duration.ofDays(1))
                .equals(Instant.MAX));                   // true
        IO.println(Duration.MAX);                        // PT2562047788015215H30M7.999999999S
    }
}

Java 27 (notas de release): KeyStore.getCreationInstant devolve a data de criação de uma entrada como Instant; na Foreign Function & Memory API, Linker.Option.captureCallState também inicializa o estado thread-local antes da downcall (a chamada de Java para uma função nativa); e os formatadores ISO predefinidos de DateTimeFormatter passam a aceitar offsets curtos, como +01, no parsing.

JVM, GC e desempenho#

G1 com menos sincronização entre aplicação e GC#

Chegou em: Java 26 (final, JEP 522)

O G1 divide o heap em regiões e, para não varrer o heap inteiro a cada coleta, anota numa card table quais trechos da memória guardam referências para objetos de outras regiões. Quem mantém essa tabela são as write barriers: pequenos trechos de código que a JVM injeta na aplicação e que rodam a cada atribuição de referência, como pedido.cliente = c. Em segundo plano, threads de otimização do G1 processam a mesma tabela.

O problema. Até o Java 25, a aplicação e as threads de otimização mexiam na mesma card table e precisavam se sincronizar. Essa sincronização deixava as write barriers longas e lentas, e elas rodam o tempo todo.

O que mudou. A JEP 522 cria uma segunda card table. A aplicação escreve numa tabela sem sincronizar, as threads de otimização trabalham na outra, e o G1 troca as duas de forma atômica quando precisa.

No diagrama, à esquerda está o modelo antigo, com uma tabela disputada pelos dois lados; à direita, o novo, em que cada lado tem a sua tabela e as setas laranja indicam a troca.

Resultado e custo. A JEP relata ganhos de throughput (trabalho feito por unidade de tempo) de 5% a 15% em aplicações que modificam muitos campos de referência, e de até 5% nas demais. No x64, as write barriers caíram de cerca de 50 instruções para 12. O custo é memória nativa: cada card table ocupa 0,2% da capacidade do heap, ou cerca de 2 MB por GB. Não há flag nova: basta usar o G1 no Java 26 ou posterior.

O Java 27 muda dois padrões da JVM, resumidos no diagrama e detalhados nas duas seções seguintes: o coletor escolhido quando nenhum é informado e o tamanho do cabeçalho dos objetos. Os dois só afetam quem não passa a flag correspondente na linha de comando.

G1 como coletor padrão em qualquer ambiente#

Chegou em: Java 27 (final, JEP 523)

O problema. Desde o Java 9 (JEP 248, veja G1 como coletor padrão no post do Java 11), o G1 era o padrão apenas em máquinas “server”. Com 1 CPU ou menos de 1792 MB de memória física, a JVM escolhia o Serial, um coletor mais simples, que usa uma única thread. Assim, a mesma aplicação podia rodar com coletores diferentes conforme a máquina.

O que mudou. A JEP 523 afirma que o G1 ficou competitivo com o Serial em qualquer tamanho de heap, em parte graças à JEP 522. Por isso, sem um coletor na linha de comando, a JVM agora escolhe sempre o G1. O Serial continua disponível com -XX:+UseSerialGC.

Cuidados. Na prática, isso atinge principalmente containers com limites baixos, porque a JVM considera os limites do container ao contar CPUs e memória (veja JVM ciente de contêineres no post do Java 11). Se o limite é 1 CPU ou menos de 1792 MB e ninguém escolheu o coletor, o Java 27 passa a rodar G1. As flags AlwaysActAsServerClassMachine e NeverActAsServerClassMachine, que influenciavam essa escolha, foram depreciadas no Java 26 (notas de release do 26).

Compact object headers ligados por padrão#

Chegou em: Java 24 (experimental, JEP 450) → Java 25 (final, JEP 519) → Java 27 (final, JEP 534)

Cada objeto Java carrega um cabeçalho com dados que a JVM usa internamente, como o hash, a idade do objeto para o GC e um ponteiro para a classe. Em arquiteturas de 64 bits, esse cabeçalho ocupava 96 bits; com compact object headers, ocupa 64. Como a maioria dos objetos é pequena (a JEP 450 cita tamanhos médios de 32 a 64 bytes), o cabeçalho sozinho podia ocupar mais de 20% dos dados vivos, e os 32 bits economizados em cada objeto fazem diferença.

O que mudou. No Java 25 o recurso já era de produto, mas era preciso pedir com -XX:+UseCompactObjectHeaders (veja Compact object headers no post do Java 25). No 27, esse é o layout padrão. A JEP 534 cita os experimentos que motivaram a mudança, entre eles um cenário em que o SPECjbb2015 usou 22% menos heap e 8% menos CPU, o uso em centenas de serviços em produção na Amazon e a adoção como padrão no SapMachine, a distribuição da SAP.

Cuidados. Para voltar ao layout antigo, use -XX:-UseCompactObjectHeaders. As notas do Java 27 avisam que essa flag deve ser depreciada e removida no futuro. O JDK traz arquivos CDS (Class Data Sharing, com metadados de classes já processados para acelerar o startup) separados para cada modo, então desligar o recurso não faz perder esse ganho.

Cache AOT com qualquer coletor, inclusive ZGC#

Chegou em: Java 26 (final, JEP 516)

O cache AOT (ahead-of-time, “antes da execução”) do Project Leyden (JEP 483, Java 24, e JEP 514, Java 25) melhora startup e warmup. Numa execução de treino, a JVM observa a aplicação e grava num arquivo as classes já carregadas e ligadas, além de objetos Java prontos. Nas execuções seguintes, ela reaproveita esse arquivo em vez de refazer o trabalho. O funcionamento está no post do Java 25.

O problema. Até o Java 25, os objetos Java do cache ficavam num formato ligado ao layout de memória dos coletores Serial, Parallel e G1, incompatível com o ZGC. Era preciso escolher entre a latência baixa do ZGC e o startup rápido do cache.

O que mudou. A JEP 516 cria um formato independente de GC, chamado streamable: as referências entre objetos viram índices lógicos, e uma thread em segundo plano recria os objetos no heap enquanto a aplicação sobe. O formato antigo, mapeável, continua existindo: nele, os objetos são mapeados direto na memória do heap. A JVM escolhe o formato na hora de gravar o cache. Se o treino usou ZGC, -XX:-UseCompressedOops ou heap acima de 32 GB, grava no formato streamable; com compressed oops ligado e heap de até 32 GB, grava no formato mapeável. O formato streamable pode ser forçado com -XX:+AOTStreamableObjects.

# Treino e criação do cache em um passo (fluxo da JEP 514, Java 25)
java -XX:+UseZGC -XX:AOTCacheOutput=app.aot -jar app.jar

# Produção usando o cache, agora também com ZGC (Java 26+)
java -XX:+UseZGC -XX:AOTCache=app.aot -jar app.jar

Por padrão, se o cache não puder ser usado, a JVM emite um aviso e segue sem ele. Com -XX:AOTMode=on, ela aborta a inicialização, o que é útil para garantir em produção que o cache está sendo aproveitado (JEP 483). No Java 27, -XX:AOTMode=required passou a ser um alias de on e é a forma recomendada, porque on deve ser depreciado e removido (notas do 27). O Java 26 não conhece o valor required: a JVM não inicia com essa flag.

Outros ajustes de GC e runtime#

Mudança	Versão	Fonte
G1 passa a lançar `OutOfMemoryError` quando o overhead de GC fica excessivo (`UseGCOverheadLimit`), como o Parallel já fazia	26	Notas do 26
G1 recupera antes objetos humongous que contêm referências, sem esperar a marcação concorrente	26	Notas do 26
Sem `-Xms`, o heap inicial passa a ser o mínimo possível (`MinHeapSize`), e não mais 1/64 da memória física	26	Notas do 26
Padrões de `-XX:MinHeapFreeRatio`/`MaxHeapFreeRatio` no G1 mudam de 40/70 para 0/100, o que na prática desliga esse redimensionamento do heap	27	Notas do 27
`-XX:InitiatingHeapOccupancyPercent` vira `-XX:G1IHOP` (o nome antigo fica como alias depreciado)	27	Notas do 27
`UseCompressedClassPointers` fica obsoleta: os ponteiros de classe são sempre comprimidos	27	Notas do 27

Ferramentas#

JFR mascara dados sensíveis antes de gravar#

Chegou em: Java 27 (final, JEP 536)

O problema. O JDK Flight Recorder (JFR) é o gravador de eventos de diagnóstico embutido na JVM. Toda gravação guarda os argumentos da linha de comando, as variáveis de ambiente e as system properties iniciais. É útil para diagnóstico, mas senhas passadas por -D, tokens em variáveis de ambiente e argumentos como --dbpassword iam parar, sem nenhuma proteção, no arquivo .jfr que depois é compartilhado ou anexado a um chamado.

O que mudou. A partir do Java 27, o JFR mascara por padrão, ainda dentro do processo e antes de escrever o arquivo, os valores que batem com uma lista de filtros. Para chaves, a lista inclui padrões como *password*, *secret*, *token*, *auth* e *api*key*. Para argumentos, cobre formas como -*password *, que pega a opção e o valor seguinte. O valor mascarado aparece como [REDACTED]. Dá para acrescentar filtros próprios, carregá-los de arquivo ou desligar os padrões:

# Padrão no Java 27: segredos óbvios já saem como [REDACTED]
java -XX:StartFlightRecording:filename=dump.jfr -jar app.jar

# Acrescentar filtros próprios aos padrões (note o "+")
java -XX:FlightRecorderOptions:'redact-key=+confidencial,redact-argument=+--pin *' \
     -XX:StartFlightRecording:filename=dump.jfr -jar app.jar

# Filtros em arquivo e log de depuração do que foi mascarado
java '-XX:FlightRecorderOptions:redact-argument=@args.txt,redact-key=@keys.txt' \
     -Xlog:jfr+redact=debug -XX:StartFlightRecording:filename=dump.jfr -jar app.jar

# Conferir o resultado
jfr print --events InitialSystemProperty,JVMInformation,InitialEnvironmentVariable dump.jfr

# Desligar os filtros padrão (só se houver motivo)
java -XX:FlightRecorderOptions:redact-key=none,redact-argument=none -jar app.jar

Cuidados. Sem o +, os filtros informados substituem a lista padrão em vez de complementá-la (JEP 536; o + e o none também aparecem nas notas do Java 27). Os filtros padrão reconhecem nomes comuns, como password e token; um segredo com nome próprio da aplicação só é mascarado se você acrescentar um filtro para ele. No mesmo release, o evento jdk.SystemProcess deixou de registrar os argumentos de linha de comando de outros processos da máquina.

Diagnóstico e ferramentas menores#

Java 26: javadoc com tema escuro; o thread dump de jcmd <pid> Thread.dump_to_file mostra o dono do lock de threads estacionadas (notas do 26).
Java 27: novo jcmd <pid> VM.security_properties, script de autocompletar do jcmd para Bash, -XX:FlightRecorderOptions:help e contagem de file descriptors abertos em VM.info e no hs_err_pid (notas do 27).

Segurança#

Troca de chaves híbrida pós-quântica no TLS 1.3#

Chegou em: Java 27 (final, JEP 527)

Este recurso usa o ML-KEM, algoritmo resistente a computação quântica que entrou no Java 24 (veja ML-KEM e ML-DSA no post do Java 25).

O problema. Um atacante pode gravar tráfego cifrado hoje e decifrá-lo quando existirem computadores quânticos capazes de quebrar RSA e ECDH. É o ataque conhecido como “harvest now, decrypt later”. A IETF definiu esquemas híbridos para o TLS 1.3, que combinam um algoritmo resistente a ataques quânticos (ML-KEM) com um tradicional (ECDHE). O resultado continua seguro enquanto pelo menos um dos dois resistir.

O que mudou. No TLS, os named groups são os algoritmos de troca de chaves que cliente e servidor negociam no início da conexão (o handshake). O JDK implementa três named groups híbridos: X25519MLKEM768, SecP256r1MLKEM768 e SecP384r1MLKEM1024. O X25519MLKEM768 vai para o topo da lista padrão, então quem usa javax.net.ssl sem escolher grupos passa a oferecê-lo sem mudar código. Os outros dois só são usados se forem configurados. A lista padrão completa fica assim: X25519MLKEM768, x25519, secp256r1, secp384r1, secp521r1, x448, ffdhe2048, ffdhe3072, ffdhe4096. Para restringir ou reordenar, use a propriedade jdk.tls.namedGroups ou SSLParameters.setNamedGroups:

import javax.net.ssl.SSLContext;
import javax.net.ssl.SSLParameters;
import javax.net.ssl.SSLSocket;

public class TlsHibrido {
    public static void main(String[] args) throws Exception {
        SSLSocket socket = (SSLSocket) SSLContext.getDefault()
                .getSocketFactory().createSocket();
        SSLParameters params = socket.getSSLParameters();
        // Só é preciso mexer aqui se a política exigir grupos específicos
        params.setNamedGroups(new String[] {
                "X25519MLKEM768", "SecP256r1MLKEM768", "x25519", "secp256r1"
        });
        socket.setSSLParameters(params);
        IO.println(String.join(", ", socket.getSSLParameters().getNamedGroups()));
        // X25519MLKEM768, SecP256r1MLKEM768, x25519, secp256r1
    }
}

Outras mudanças de segurança#

Mudança	Versão	Fonte
Novo algoritmo de `Cipher` `"HPKE"` (Hybrid Public Key Encryption, RFC 9180) com `HPKEParameterSpec`	26	Notas do 26
Assinatura e verificação de JARs com ML-DSA (`jarsigner` e API `JarSigner`)	26	Notas do 26
Nova propriedade `jdk.crypto.disabledAlgorithms` para desabilitar algoritmos na camada JCE	26	Notas do 26
Compressão de certificados TLS 1.3 com zlib (RFC 8879), ligada por padrão	27	Notas do 27
Chaves privadas ML-KEM e ML-DSA passam a ser codificadas em PKCS#8 no formato `seed` por padrão	27	Notas do 27
Otimizações de desempenho em ML-KEM e ML-DSA (SHA-3 em x86_64 com AVX-512) e em X25519/Ed25519 (AArch64 e x86_64)	27	Notas do 27

Removidos e depreciados#

Mutação de campos final por reflexão passa a emitir aviso#

Chegou em: Java 26 (final, JEP 500)

O problema. Desde o JDK 5, Field.setAccessible(true) seguido de Field.set(...) altera até campos final. Com isso, nem a JVM nem quem lê o código podem confiar que um final de instância nunca muda. Para a JVM, isso bloqueia otimizações como o constant folding, em que o compilador JIT troca a leitura do campo pelo próprio valor (é o que dá desempenho às Lazy Constants).

O que mudou. No Java 26, alterar um campo final por reflexão ainda funciona, mas gera um aviso, no máximo um por módulo. A JEP prevê que uma versão futura passe a lançar exceção por padrão. O comportamento é controlado por --illegal-final-field-mutation=allow|warn|debug|deny (warn é o padrão no 26), e a permissão é dada explicitamente com --enable-final-field-mutation=ALL-UNNAMED ou com uma lista de módulos. --add-opens, a opção usada desde o encapsulamento forte do Java 16 e 17 para liberar reflexão profunda, não basta para evitar o aviso.

import java.lang.reflect.Field;

public class FinalMutavel {

    static class Preco {
        private final long centavos;
        Preco(long centavos) { this.centavos = centavos; }
        long centavos() { return centavos; }
    }

    public static void main(String[] args) throws Exception {
        Preco preco = new Preco(1_000);

        Field campo = Preco.class.getDeclaredField("centavos");
        campo.setAccessible(true);   // continua funcionando como antes
        campo.set(preco, 1);         // Java 26+: gera WARNING (padrão warn)

        IO.println(preco.centavos());
    }
}

Saída no Temurin 26.0.2:

WARNING: Final field centavos in class FinalMutavel$Preco has been mutated reflectively by class FinalMutavel in unnamed module @525b461a (file:/w/FinalMutavel.java)
WARNING: Use --enable-final-field-mutation=ALL-UNNAMED to avoid a warning
WARNING: Mutating final fields will be blocked in a future release unless final field mutation is enabled
1

Cuidados. Com --illegal-final-field-mutation=deny, o mesmo código lança IllegalAccessException. A JEP recomenda rodar os testes com deny desde já para achar quem faz isso, e em geral o culpado é uma biblioteca, não a aplicação. Outra forma de encontrar é o evento JFR jdk.FinalFieldMutation. Para bibliotecas de serialização, a JEP recomenda sun.reflect.ReflectionFactory em vez de reflexão profunda.

Applet API removida#

Chegou em: Java 9 (depreciado, JEP 289) → Java 17 (depreciado para remoção, JEP 398) → Java 26 (removido, JEP 504)

Os navegadores já não executam applets, e desde o Java 11, quando o appletviewer foi removido, o JDK não tem mais como rodá-los (JEP 504; veja também Nashorn, Pack200, CMS e Applet API no post do Java 11). Faltava remover a API. No Java 26 saíram o pacote java.applet inteiro, javax.swing.JApplet, java.beans.AppletInitializer e os membros de java.beans.Beans e javax.swing.RepaintManager que dependiam deles. Um efeito colateral: URL.getContent() e URLConnection.getContent() não devolvem mais java.applet.AudioClip para conteúdo de áudio. Para tocar áudio, a JEP aponta a javax.sound.SoundClip, introduzida no Java 25.

Outras remoções#

Removido	Versão	Fonte
`Thread.stop()`: código que chama não compila, e binários antigos recebem `NoSuchMethodError`	26	Notas do 26
Ferramenta `jrunscript` e módulo `jdk.jsobject` (este segue no JavaFX)	26	Notas do 26
Suporte a InfiniBand SDP, `setTTL`/`getTTL` de `MulticastSocket` e `DatagramSocketImpl` e `MulticastSocket.send(DatagramPacket, byte)`	26	Notas do 26
JVM Compiler Interface (JVMCI, a interface para plugar na JVM um compilador JIT escrito em Java, JEP 243): módulos `jdk.internal.vm.ci`, `jdk.graal.compiler` e `jdk.graal.compiler.management`, flags `JVMCI` e `-XX:+UseGraalJIT`	27	Notas do 27
Opções `-noclassgc`, `-noverify`, `-verifyremote` e `-Xverify:none`	27	Notas do 27
`ThreadPoolExecutor.finalize()`	27	Notas do 27
Mecanismo `VFORK` de `jdk.lang.Process.launchMechanism` (Linux) e a propriedade `java.locale.useOldISOCodes`	27	Notas do 27
`ffdhe6144` e `ffdhe8192` saem da lista padrão de named groups TLS	27	Notas do 27

Depreciações#

Java 26: java.net.SocketPermission e Socket.setPerformancePreferences (e os equivalentes em SocketImpl e ServerSocket) foram depreciados para remoção. Também foram depreciadas as flags -Xmaxjitcodesize, AlwaysActAsServerClassMachine, NeverActAsServerClassMachine, AggressiveHeap e MaxRAM. No caso de MaxRAM, o valor padrão também deixou de existir, e o dimensionamento do heap usa a memória disponível (notas do 26).
Java 27: o alias -XX:InitiatingHeapOccupancyPercent foi depreciado (notas do 27).
Java 28 (ainda não lançado): port macOS/x64 depreciado para remoção (JEP 541). Segundo a JEP, os engenheiros da Oracle deixam de manter esse port a partir do JDK 27.

Ainda em preview ou incubadora#

Nenhum destes recursos é definitivo: todos exigem --enable-preview (ou --add-modules, no caso da incubadora) e mudaram de API entre uma versão e outra. Todos já existiam como preview ou incubadora no Java 25; cada seção aponta para a explicação original no post do Java 25 e mostra o que mudou desde então. Os exemplos refletem o Java 27.

Structured Concurrency#

Chegou em: Java 25 (5ª preview, JEP 505) → Java 26 (6ª preview, JEP 525) → Java 27 (7ª preview, JEP 533)

As primeiras versões estão em Structured Concurrency no post do Java 21 e no post do Java 25.

O problema. Com ExecutorService, nada liga as tarefas ao método que as disparou: se uma falha, as outras continuam; se quem espera é interrompido, as subtarefas nem ficam sabendo; e o thread dump não mostra quem é filho de quem.

Como funciona. StructuredTaskScope trata um grupo de subtarefas como uma unidade presa a um bloco try. A thread que abre o escopo, chamada de thread dona, dispara as subtarefas com fork (por padrão, cada uma numa virtual thread), espera tudo com join e fecha o escopo ao sair do bloco. A política de conclusão fica num Joiner. Na política padrão, se uma subtarefa falhar, as outras são canceladas. O close() sempre espera as threads terminarem, então nenhuma sobra depois do bloco. No thread dump em JSON (jcmd <pid> Thread.dump_to_file -format=json <arquivo>), a hierarquia de escopos aparece.

O diagrama mostra os três desfechos possíveis do join() com os Joiners prontos do Java 27. O exemplo abaixo cobre a política padrão e um Joiner com prazo:

import java.time.Duration;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.StructuredTaskScope;
import java.util.concurrent.StructuredTaskScope.CancelledByTimeoutException;
import java.util.concurrent.StructuredTaskScope.Joiner;
import java.util.concurrent.StructuredTaskScope.Subtask;

public class Checkout {

    record Resumo(String cliente, int itens) {}

    static String buscarCliente() throws InterruptedException {
        Thread.sleep(100);
        return "ana";
    }

    static int contarItens() throws InterruptedException {
        Thread.sleep(150);
        return 3;
    }

    static String consultarEstoque(String sku) throws InterruptedException {
        Thread.sleep(sku.equals("lento") ? 5_000 : 50);
        return sku + ": disponível";
    }

    // Política padrão: se uma subtarefa falhar, as outras são canceladas
    static Resumo carregar() throws ExecutionException, InterruptedException {
        try (var scope = StructuredTaskScope.open()) {
            Subtask<String> cliente = scope.fork(() -> buscarCliente());
            Subtask<Integer> itens = scope.fork(() -> contarItens());

            scope.join(); // Java 27: lança ExecutionException se alguma falhar

            return new Resumo(cliente.get(), itens.get());
        }
    }

    // Todas precisam dar certo dentro do prazo; o resultado já vem como lista
    static List<String> estoque(List<String> skus, Duration prazo)
            throws ExecutionException, InterruptedException {
        try (var scope = StructuredTaskScope.open(
                Joiner.<String>allSuccessfulOrThrow(),
                cf -> cf.withTimeout(prazo))) {
            skus.forEach(sku -> scope.fork(() -> consultarEstoque(sku)));
            return scope.join();
        }
    }

    public static void main(String[] args) throws Exception {
        IO.println(carregar());
        IO.println(estoque(List.of("a1", "b2"), Duration.ofSeconds(1)));
        try {
            estoque(List.of("a1", "lento"), Duration.ofMillis(300));
        } catch (ExecutionException e) {
            if (e.getCause() instanceof CancelledByTimeoutException) {
                IO.println("prazo estourado: subtarefas canceladas");
            }
        }
    }
}

Para rodar no Java 27: java --enable-preview --source 27 Checkout.java. Pela API do JDK 27, a saída esperada é:

Resumo[cliente=ana, itens=3]
[a1: disponível, b2: disponível]
prazo estourado: subtarefas canceladas

A lista do segundo passo vem na ordem em que as subtarefas foram disparadas com fork.

O que mudou no caminho. Cada preview mexeu na API, e código escrito para uma versão costuma não compilar na seguinte:

Versão	Mudanças na API
Java 25 (JEP 505)	Os construtores públicos deram lugar às fábricas estáticas `open(...)` e a política passou para o `Joiner`. Em caso de falha, `join()` lançava `FailedException`; com prazo estourado, `TimeoutException`.
Java 26 (JEP 525)	Novo `Joiner.onTimeout()`, para um `Joiner` devolver resultado quando o prazo estoura. `allSuccessfulOrThrow()` passou a devolver uma lista de resultados, e não mais um stream de subtarefas. `anySuccessfulResultOrThrow()` foi renomeado para `anySuccessfulOrThrow()`. O `open` que recebe `Joiner` e configuração passou a aceitar `UnaryOperator` em vez de `Function`. As exceções de `join()` continuaram as mesmas.
Java 27 (JEP 533)	`StructuredTaskScope` e `Joiner` ganharam um terceiro parâmetro de tipo, `R_X`, com a exceção que `join()` pode lançar. As fábricas prontas passaram a lançar `ExecutionException`, e há sobrecargas que recebem uma `Function` para gerar outra exceção. `FailedException` e `TimeoutException` deixaram de existir. `awaitAll()` foi removido. `onTimeout()` virou `timeout()`, e o estouro de prazo chega como exceção com causa `CancelledByTimeoutException`. Também entrou o `open(UnaryOperator)`.

Na prática, o tratamento de erro escrito para o 26 precisa mudar no 27:

try (var scope = StructuredTaskScope.open()) {
    // ...
} catch (StructuredTaskScope.FailedException e) {   // Java 26
} catch (ExecutionException e) {                    // Java 27
    Throwable causa = e.getCause();                 // exceção da subtarefa que falhou
}

Um Joiner próprio implementa result() e, a partir do 27, timeout(); onFork e onComplete têm implementação default. As assinaturas completas estão na JEP 533 e no código-fonte do StructuredTaskScope na tag jdk-27-ga.

Existe uma JEP candidata, a JEP 543, que propõe finalizar a API no Java 28 sem outras mudanças. Em 16/09/2026 ela ainda não tinha alvo no 28.

Quando usar. Quando uma operação se divide em subtarefas concorrentes que só fazem sentido juntas, como buscar dados de vários serviços para montar uma resposta. Enquanto a API estiver em preview, concentre o uso em poucos pontos do código: a cada versão do JDK, é ali que o ajuste vai ser necessário.

Tipos primitivos em patterns, instanceof e switch#

Chegou em: Java 25 (3ª preview, JEP 507) → Java 26 (4ª preview, JEP 530) → Java 27 (5ª preview, JEP 532)

A versão do Java 25 está em Tipos primitivos em padrões, instanceof e switch no post do Java 25.

O problema. Converter um primitivo para outro menor, como int para byte, é silencioso: se o valor não cabe, o cast corta bits e o erro segue adiante sem aviso. O instanceof sempre serviu para perguntar “é seguro fazer este cast?”, mas só funcionava com tipos de referência. Um switch também não aceitava long, float, double nem boolean como seletor.

Como funciona. Com o recurso habilitado, instanceof e switch aceitam tipos primitivos em qualquer posição de pattern. O teste vale true quando a conversão é exata, ou seja, quando nenhuma informação se perde. Com int i = 1000, i instanceof byte é false. Com i = 16_777_217, i instanceof float também é false, porque o float não representa esse inteiro sem perder precisão. O switch passa a funcionar com todos os tipos primitivos e com os wrappers correspondentes. Um switch sobre boolean que trata true e false já é exaustivo.

O que mudou no caminho. A JEP 530 (Java 26) mudou duas coisas: melhorou a definição de conversão “incondicionalmente exata” e deixou mais rígida a checagem de dominância no switch. Com isso, o compilador passa a rejeitar case que nunca seriam alcançados, e alguns switch que compilavam no Java 25 deixam de compilar. A JEP 532 (Java 27) repete o preview sem mudanças, então quem já ajustou o código para o 26 não precisa mexer de novo.

public class PadroesPrimitivos {

    // instanceof com tipo primitivo: true só se a conversão for exata
    static String classificar(int valor) {
        if (valor instanceof byte b) {
            return "cabe em byte: " + b;
        }
        return "precisa de int: " + valor;
    }

    // switch sobre double, com constante e guarda
    static String descrever(double temperatura) {
        return switch (temperatura) {
            case 0d -> "zero";
            case double t when t < 0 -> "negativa: " + t;
            case double t -> "positiva: " + t;
        };
    }

    // switch sobre boolean: true + false já é exaustivo
    static String estado(boolean ativo) {
        return switch (ativo) {
            case true -> "ligado";
            case false -> "desligado";
        };
    }

    public static void main(String[] args) {
        IO.println(classificar(42));     // cabe em byte: 42
        IO.println(classificar(1000));   // precisa de int: 1000
        IO.println(descrever(-3.5));     // negativa: -3.5
        IO.println(estado(true));        // ligado

        long grande = 16_777_217L;       // 2^24 + 1
        IO.println(grande instanceof float);  // false: float perderia precisão
        IO.println(grande instanceof double); // true
    }
}

Para rodar: java --enable-preview --source 27 PadroesPrimitivos.java (no Java 26, --source 26).

A checagem de dominância mais rígida também pega constantes que um pattern anterior já cobre. O trecho abaixo compila no Java 25 com --enable-preview e é rejeitado a partir do 26:

static void teste(int x) {
    switch (x) {
        case float f -> IO.println("float");
        // erro: "this case label is dominated by a preceding case label"
        case 16_777_216 -> IO.println("constante");
        default -> IO.println("outro");
    }
}

Lazy Constants#

Chegou em: Java 25 (preview, JEP 502) → Java 26 (2ª preview, JEP 526) → Java 27 (3ª preview, JEP 531)

No Java 25, a API se chamava Stable Values (veja Stable Values no post do Java 25); o nome Lazy Constants veio no Java 26.

O problema. Um campo final precisa ser atribuído no construtor ou no inicializador estático, ou seja, cedo. Se o valor é caro de montar (um logger que lê configuração, uma conexão, um cache), a aplicação paga esse custo na subida, mesmo que nunca use o valor. As saídas de sempre têm seus problemas: o padrão da classe holder só serve para campos static, o double-checked locking exige volatile e é fácil de errar, e o ConcurrentHashMap.computeIfAbsent impede que a JVM trate o valor como constante.

Como funciona. Um java.lang.LazyConstant<T> nasce vazio, com uma função de cálculo. O primeiro get() executa a função e guarda o resultado. A função roda no máximo uma vez, mesmo com várias threads chamando get() ao mesmo tempo, e depois disso o conteúdo não muda. Segundo a JEP, o conteúdo fica num campo com a anotação interna @Stable; se a lazy constant estiver num campo final, a JVM pode aplicar constant folding (explicado na seção da JEP 500) como faria com um final comum. Existem também versões preguiçosas das coleções: List.ofLazy, Map.ofLazy e, a partir do Java 27, Set.ofLazy.

O diagrama mostra o ciclo de vida de uma lazy constant e a comparação que a JEP 531 faz com campos final e não final.

import java.util.EnumSet;
import java.util.List;
import java.util.Map;
import java.util.Set;

public class Aplicacao {

    record Conexao(String url) {}
    record Worker(int id) {}
    record Taxa(String moeda, double valor) {}
    enum Opcao { VERBOSE, DRY_RUN, STRICT }

    // Computado no primeiro get(), no máximo uma vez, mesmo com várias threads
    static final LazyConstant<Conexao> CONEXAO =
            LazyConstant.of(() -> abrirConexao("jdbc:postgresql://db/app"));

    // Lista de tamanho fixo: cada posição é computada quando acessada
    static final List<Worker> WORKERS = List.ofLazy(4, Worker::new);

    // Mapa com chaves conhecidas: cada valor é computado quando lido
    static final Map<String, Taxa> TAXAS =
            Map.ofLazy(Set.of("BRL", "USD"), Aplicacao::carregarTaxa);

    // Java 27: a pertinência de cada candidato é decidida sob demanda
    static final Set<Opcao> OPCOES =
            Set.ofLazy(EnumSet.allOf(Opcao.class), Aplicacao::habilitada);

    static Conexao abrirConexao(String url) {
        IO.println("abrindo conexão (uma única vez)");
        return new Conexao(url);
    }

    static Taxa carregarTaxa(String moeda) {
        IO.println("carregando taxa de " + moeda);
        return new Taxa(moeda, moeda.equals("BRL") ? 1.0 : 5.4);
    }

    static boolean habilitada(Opcao opcao) {
        IO.println("avaliando " + opcao);
        return opcao == Opcao.DRY_RUN;
    }

    public static void main(String[] args) {
        IO.println(CONEXAO.get());      // computa aqui
        IO.println(CONEXAO.get());      // devolve o mesmo valor, sem recalcular
        IO.println(WORKERS.get(2));     // só o índice 2 é criado
        IO.println(TAXAS.get("USD"));   // só USD é carregado; BRL, não
        IO.println(OPCOES.contains(Opcao.DRY_RUN)); // só DRY_RUN é avaliado
    }
}

Para rodar no Java 27: java --enable-preview --source 27 Aplicacao.java. A saída mostra que cada função de cálculo roda só quando o valor é pedido, e uma única vez:

abrindo conexão (uma única vez)
Conexao[url=jdbc:postgresql://db/app]
Conexao[url=jdbc:postgresql://db/app]
Worker[id=2]
carregando taxa de USD
Taxa[moeda=USD, valor=5.4]
avaliando DRY_RUN
true

No Java 26, Set.ofLazy não existe. Sem as linhas de OPCOES, o exemplo roda com --source 26 no Temurin 26.0.2 e imprime as seis primeiras linhas acima.

Quando usar. Lazy constants fazem sentido para valores caros que talvez nem sejam usados e que, depois de calculados, nunca mudam: configuração, conexões, loggers, tabelas de consulta. Enquanto a API estiver em preview, prefira usá-la em código que você controla e recompila a cada versão do JDK.

O que mudou no caminho.

Java 26 (JEP 526): a API foi renomeada de StableValue para LazyConstant e ficou só com os casos de alto nível. Saíram os métodos de baixo nível orElseSet, setOrThrow e trySet, e também as fábricas function e intFunction. As fábricas de coleções foram para List.ofLazy e Map.ofLazy, e null deixou de ser aceito como valor calculado.
Java 27 (JEP 531): saíram isInitialized() e orElse(...), e entrou Set.ofLazy(...).

A JEP deixa claro que o ganho de constant folding depende de a JVM confiar em campos final. Campos static final já são confiáveis. A maioria dos campos final de instância ainda pode ser alterada por reflexão, e a JEP cita a intenção de restringir isso no longo prazo, caminho que começou com a JEP 500.

API PEM#

Chegou em: Java 25 (preview, JEP 470) → Java 26 (2ª preview, JEP 524) → Java 27 (3ª preview, JEP 538)

A primeira versão está em Codificação PEM de objetos criptográficos no post do Java 25.

O problema. PEM é o formato de texto com -----BEGIN ...----- usado para chaves, certificados e CRLs. Até aqui, o JDK não tinha uma API para ler e escrever esse formato: era preciso tirar cabeçalhos e decodificar Base64 à mão, ou recorrer a bibliotecas como o Bouncy Castle.

Como funciona. PEMEncoder e PEMDecoder (em java.security) são imutáveis, thread-safe e reutilizáveis. Eles convertem objetos que implementam a interface selada BinaryEncodable: chaves assimétricas, KeyPair, X509Certificate, X509CRL, EncryptedPrivateKeyInfo, as key specs PKCS#8 e X.509 e a classe genérica PEM, que cobre tipos sem API própria, como requisições de certificado PKCS#10.

import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.PEMDecoder;
import java.security.PEMEncoder;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.security.interfaces.ECPrivateKey;
import java.security.interfaces.ECPublicKey;

public class ChavesPem {
    public static void main(String[] args) throws Exception {
        KeyPair par = KeyPairGenerator.getInstance("EC").generateKeyPair();
        char[] senha = "troque-esta-senha".toCharArray();

        // Codificação: encoders são imutáveis e reutilizáveis
        PEMEncoder encoder = PEMEncoder.of();
        String publicaPem = encoder.encodeToString(par.getPublic());
        String privadaPem = encoder.withEncryption(senha).encodeToString(par.getPrivate());
        IO.println(publicaPem.lines().findFirst().orElseThrow()); // -----BEGIN PUBLIC KEY-----
        IO.println(privadaPem.lines().findFirst().orElseThrow()); // -----BEGIN ENCRYPTED PRIVATE KEY-----

        // Decodificação com o tipo esperado
        PEMDecoder decoder = PEMDecoder.of();
        ECPublicKey publica = decoder.decode(publicaPem, ECPublicKey.class);
        ECPrivateKey privada = decoder.withDecryption(senha).decode(privadaPem, ECPrivateKey.class);
        IO.println(publica.getAlgorithm() + " / " + privada.getAlgorithm()); // EC / EC

        // Ou sem saber o tipo de antemão, com pattern matching
        switch (decoder.decode(publicaPem)) {
            case PublicKey pk -> IO.println("chave pública " + pk.getFormat()); // chave pública X.509
            case PrivateKey sk -> IO.println("chave privada");
            default -> IO.println("outro objeto PEM");
        }
    }
}

Para rodar: java --enable-preview --source 27 ChavesPem.java. O código é o mesmo no Java 26, onde a interface ainda se chamava DEREncodable.

O default é obrigatório no switch porque o decode pode devolver outros tipos, como KeyPair, X509Certificate ou PEM. Mesmo um switch que liste todos os tipos públicos precisaria dele: a lista de subtipos de BinaryEncodable não é exaustiva, o que, segundo o Javadoc de BinaryEncodable, permite ampliá-la no futuro sem quebrar código existente.

O que mudou no caminho. No Java 26, PEMRecord virou PEM, os métodos encryptKey de EncryptedPrivateKeyInfo viraram encrypt, e encoder e decoder passaram a cifrar e decifrar KeyPair e PKCS8EncodedKeySpec. No Java 27, DEREncodable virou BinaryEncodable, PEM deixou de ser record e virou classe comum, PEMDecoder.withFactory virou withFactoriesOf, e entrou a exceção não verificada javax.crypto.CryptoException. A JEP 542, já concluída para o Java 28, finaliza a API sem outras mudanças. Ou seja: o código escrito para o 27 deve funcionar no 28 sem --enable-preview, e é a partir dali que vale trocar o parsing manual de PEM pela API em código de produção.

Vector API#

Chegou em: Java 25 (10ª incubadora, JEP 508) → Java 26 (11ª incubadora, JEP 529) → Java 27 (12ª incubadora, JEP 537)

A Vector API (veja Vector API no post do Java 25) expressa cálculos vetoriais que o JIT compila para instruções SIMD da CPU, que aplicam a mesma operação a vários valores de uma vez. Nas duas versões ela voltou sem mudança relevante de API; no 27, só a biblioteca SLEEF usada em ARM e RISC-V foi atualizada. Pelas JEPs, ela fica na incubadora até que os recursos necessários do Project Valhalla cheguem como preview. Em 16/09/2026, o primeiro preview de Value Objects (JEP 401), do Valhalla, já tinha alvo no Java 28.

import jdk.incubator.vector.FloatVector;
import jdk.incubator.vector.VectorSpecies;

public class SomaVetorial {
    static final VectorSpecies<Float> ESPECIE = FloatVector.SPECIES_PREFERRED;

    // c[i] = -(a[i]² + b[i]²), processando várias posições por instrução da CPU
    static void calcular(float[] a, float[] b, float[] c) {
        int i = 0;
        int limite = ESPECIE.loopBound(a.length);
        for (; i < limite; i += ESPECIE.length()) {
            var va = FloatVector.fromArray(ESPECIE, a, i);
            var vb = FloatVector.fromArray(ESPECIE, b, i);
            va.mul(va).add(vb.mul(vb)).neg().intoArray(c, i);
        }
        for (; i < a.length; i++) {           // sobra que não completa um vetor
            c[i] = (a[i] * a[i] + b[i] * b[i]) * -1.0f;
        }
    }

    public static void main(String[] args) {
        float[] a = {1, 2, 3, 4, 5, 6, 7, 8, 9};
        float[] b = {9, 8, 7, 6, 5, 4, 3, 2, 1};
        float[] c = new float[a.length];
        calcular(a, b, c);
        IO.println(java.util.Arrays.toString(c));
        // [-82.0, -68.0, -58.0, -52.0, -50.0, -52.0, -58.0, -68.0, -82.0]
    }
}

Para rodar: java --add-modules jdk.incubator.vector SomaVetorial.java. Sem o --add-modules, o pacote não fica visível e a compilação falha. Com ele, a JVM também imprime WARNING: Using incubator modules: jdk.incubator.vector antes da saída.

O que observar vindo do Java 25#

Mudanças confirmadas no 26 e no 27 que podem quebrar build, testes ou comportamento em produção:

Recompilar tudo o que usa preview. Pela JEP 12, uma JVM não carrega classes que dependem dos previews de outra versão. E as APIs mudaram entre versões: exceções do StructuredTaskScope (FailedException → ExecutionException), StableValue → LazyConstant sem isInitialized/orElse, DEREncodable → BinaryEncodable. Com a dominância mais rígida em switch com primitivos, alguns switch que compilavam deixam de compilar.
Avisos de final alterado por reflexão (JEP 500, detalhes). Procure os WARNING: Final field ... nos logs e rode os testes com --illegal-final-field-mutation=deny. Frameworks de injeção, mocks e serialização são os suspeitos de sempre.
Coletor em containers pequenos (JEP 523, detalhes). Com 1 CPU ou menos de 1792 MB, o padrão passa de Serial para G1. Meça memória e latência e, se preciso, fixe -XX:+UseSerialGC.
Layout de objeto (JEP 534, detalhes). Os compact object headers vêm ligados. Se algo depender do layout antigo, -XX:-UseCompactObjectHeaders desliga.
Flags e dimensionamento de heap. No 26, sem -Xms, o heap inicial passa a ser o mínimo possível; quem dependia do padrão antigo pode fixar -Xms ou -XX:InitialRAMPercentage=1.5625 (notas do 26). No 27, -noverify/-Xverify:none, -noclassgc, -verifyremote e -XX:+UseGraalJIT foram removidas, UseCompressedClassPointers ficou obsoleta, os padrões de Min/MaxHeapFreeRatio no G1 mudaram e InitiatingHeapOccupancyPercent virou G1IHOP (notas do 27). Revise scripts de startup, Dockerfiles e JAVA_TOOL_OPTIONS.
APIs removidas. Thread.stop(), a Applet API e ThreadPoolExecutor.finalize(). No último caso, quem sobrescrevia finalize() chamando super.finalize() passa a chamar Object.finalize(), que declara throws Throwable, e o código pode deixar de compilar (notas do 27).
Rede e HTTP. No 26, o timeout de HttpRequest.Builder.timeout passou a cobrir também a leitura do corpo da resposta, e os atributos de HttpContext deixaram de ser compartilhados com cada HttpExchange no servidor embutido (a propriedade jdk.httpserver.attributes restaura o comportamento antigo). No 27, o HttpServer passou de casamento por prefixo de string para prefixo de caminho: o contexto /foo não casa mais com /foobar, e a propriedade sun.net.httpserver.pathMatcher restaura o comportamento antigo (notas do 26, notas do 27).
TLS e criptografia no 27. X25519MLKEM768 vira o grupo preferido. ffdhe6144/ffdhe8192 saem da lista padrão. A derivação de chave do TLS 1.3 passa a usar chaves Generic, e providers JCE que não as suportam podem falhar no handshake (a propriedade jdk.tls.t13KeyDerivationAlgorithm=TlsPremasterSecret restaura o comportamento anterior). Chaves privadas ML-KEM e ML-DSA codificadas no 27 (formato seed) não são aceitas por versões anteriores por padrão (notas do 27).
Saídas e exceções que mudaram. No 26, DecimalFormat passou a usar o algoritmo de Double.toString (-Djdk.compat.DecimalFormat=true restaura o antigo). No 27, o thread dump em JSON usa números nos IDs, e ZipOutputStream.putNextEntry lança ZipException em vez de IllegalArgumentException para nomes que não podem ser codificados (notas do 26, notas do 27).
Dados de locale, TLS e compilação. No 26, os dados de locale passaram ao CLDR 48 e, no 27, ao CLDR 48.2, com mudanças em formatos de data, hora e número (por exemplo, o separador de milhar suíço); testes que comparam texto formatado podem falhar. Também no 26, conexões RMI sobre TLS passaram a verificar por padrão se o certificado do servidor corresponde ao nome do host (jdk.rmi.ssl.client.enableEndpointIdentification=false desliga), e o KeyManager SunX509 passou a checar os certificados locais contra as restrições de algoritmos (jdk.tls.SunX509KeyManager.certChecking=false restaura o comportamento antigo). No 27, o javac passou a rejeitar anotações TYPE_USE em variáveis com tipo inferido, como as declaradas com var, inclusive parâmetros de lambda (notas do 26, notas do 27).

Todas as JEPs, versão a versão#

Listas conferidas nas páginas oficiais de cada release no OpenJDK; os títulos seguem as páginas das JEPs. Tipos: Final (recurso permanente ou mudança de implementação), Preview, Incubadora, Experimental, Depreciação, Remoção, Plataforma (port para sistema operacional ou arquitetura) e Interno (mudança no desenvolvimento do próprio OpenJDK, sem efeito para quem usa o JDK).

Java 26#

Lançado em 17 de março de 2026, com 10 JEPs (JDK 26).

Ver as 10 JEPs do Java 26

JEP	Título	Tipo
500	Prepare to Make Final Mean Final	Final
504	Remove the Applet API	Remoção
516	Ahead-of-Time Object Caching with Any GC	Final
517	HTTP/3 for the HTTP Client API	Final
522	G1 GC: Improve Throughput by Reducing Synchronization	Final
524	PEM Encodings of Cryptographic Objects (Second Preview)	Preview
525	Structured Concurrency (Sixth Preview)	Preview
526	Lazy Constants (Second Preview)	Preview
529	Vector API (Eleventh Incubator)	Incubadora
530	Primitive Types in Patterns, instanceof, and switch (Fourth Preview)	Preview

Java 27#

Lançado em 15 de setembro de 2026, com 9 JEPs (JDK 27).

Ver as 9 JEPs do Java 27

JEP	Título	Tipo
523	Make G1 the Default Garbage Collector in All Environments	Final
527	Post-Quantum Hybrid Key Exchange for TLS 1.3	Final
531	Lazy Constants (Third Preview)	Preview
532	Primitive Types in Patterns, instanceof, and switch (Fifth Preview)	Preview
533	Structured Concurrency (Seventh Preview)	Preview
534	Compact Object Headers by Default	Final
536	JFR In-Process Data Redaction	Final
537	Vector API (Twelfth Incubator)	Incubadora
538	PEM Encodings of Cryptographic Objects (Third Preview)	Preview

Java 28#

Em desenvolvimento. A página do JDK 28 ainda não publicou o cronograma, e o roadmap da Oracle prevê o lançamento para março de 2027. Na última atualização da página (27/08/2026), estas eram as JEPs com alvo no 28; a coluna Situação mostra o status de cada JEP em 16/09/2026. “Com alvo” significa que a JEP foi aceita para o 28; “integrada”, que o código já entrou no repositório do 28; “concluída”, que além disso a JEP foi encerrada como entregue.

Ver as 6 JEPs do Java 28

JEP	Título	Tipo	Situação
401	Value Objects (Preview)	Preview	Integrada ao 28
535	Shenandoah GC: Generational Mode by Default	Final	Com alvo no 28, ainda não integrada
539	Strict Field Initialization in the JVM (Preview)	Preview	Integrada ao 28
540	Simple JSON API (Incubator)	Incubadora	Integrada ao 28
541	Deprecate the macOS/x64 Port for Removal	Depreciação	Concluída no 28
542	PEM Encodings of Cryptographic Objects	Final	Concluída no 28

Em resumo: Value Objects (Project Valhalla) introduz, em preview, objetos imutáveis e sem identidade, distinguidos só pelos valores dos campos, que a JVM pode representar de forma mais eficiente. Strict Field Initialization é um recurso de VM em preview, voltado a compiladores que geram class files, no qual o campo precisa ser inicializado antes de qualquer leitura, de modo que 0 e null nunca são observados. A Simple JSON API (jdk.incubator.json) faz parsing e geração de JSON sem biblioteca externa. No Shenandoah, o modo geracional vira padrão e o não geracional (ShenandoahGCMode=satb) é depreciado. A API PEM vira final.

Fora da lista, a JEP 543 (candidata, sem versão definida) propõe finalizar Structured Concurrency no Java 28. Nada disso está garantido até o Java 28 sair, e este post será atualizado quando isso acontecer.

Fontes#

Consultadas em 16/09/2026.

Cronograma e suporte

Oracle Java SE Support Roadmap: Java 29 como próxima LTS prevista (setembro de 2027); 26, 27 e 28 não LTS; prazos de Premier Support
JDK 26, página do projeto: JEPs e GA em 17/03/2026
JDK 27, página do projeto: JEPs, cronograma e GA em 15/09/2026
JDK 28, página do projeto: JEPs com alvo no 28
JEP 0 — JEP Index: status das JEPs em andamento
Anúncio de GA do JDK 27 (announce@openjdk.org)
Anúncio de GA do JDK 26 (jdk-dev@openjdk.org)

Notas de release

JDK 27 Release Notes (jdk.java.net)
JDK 26 Release Notes (Oracle)
JDK-8369238: virtual threads e inicialização de classes

JEPs

Anteriores ao Java 26: JEP 243, JEP 248, JEP 289, JEP 321, JEP 398, JEP 450, JEP 483, JEP 470, JEP 502, JEP 505, JEP 507, JEP 508, JEP 514, JEP 519
Java 26: JEP 500, JEP 504, JEP 516, JEP 517, JEP 522, JEP 524, JEP 525, JEP 526, JEP 529, JEP 530
Java 27: JEP 523, JEP 527, JEP 531, JEP 532, JEP 533, JEP 534, JEP 536, JEP 537, JEP 538
Java 28 (com alvo ou candidata): JEP 401, JEP 535, JEP 539, JEP 540, JEP 541, JEP 542, JEP 543
Processo: JEP 11 — Incubator Modules e JEP 12 — Preview Features

Código-fonte do JDK 27 (tag jdk-27-ga)

Bloqueio otimista e pessimista — como funcionam e quando usar cada um

Sun, 13 Sep 2026 00:00:00 GMT

Quando duas requisições leem a mesma linha, calculam um valor novo e gravam, uma delas pode apagar o trabalho da outra sem erro nenhum. Este post mostra as duas formas clássicas de impedir isso, o bloqueio otimista (detectar o conflito) e o bloqueio pessimista (evitar o conflito), com SQL testado no PostgreSQL 17 e o equivalente em Spring Data JPA. No fim, há um critério para escolher entre os dois e um terceiro caminho que muitas vezes dispensa ambos: o UPDATE condicional.

O tema aparece de raspão no artigo sobre cobrança duplicada no retry, como alternativa à restrição única. Aqui ele ganha o espaço que merece.

1. O problema que os dois resolvem#

Os dois existem para o mesmo defeito, que tem nome: lost update, a atualização perdida.

Dois clientes leem a mesma linha, cada um calcula um valor novo a partir do que leu, e os dois gravam. A segunda gravação sobrescreve a primeira, e a primeira desaparece sem erro nenhum. O saldo fica errado e o log está limpo.

É a mesma família do problema de cobrança duplicada no retry: ler, decidir e gravar como operações separadas, com uma janela no meio. Lá, a solução foi uma restrição única, que funciona quando a decisão cabe numa chave. Aqui o caso é outro: a decisão depende do valor lido, e não existe chave que expresse isso.

A diferença entre os dois bloqueios cabe numa frase, e é assim que o catálogo de padrões do Martin Fowler os descreve: bloqueio otimista é detecção de conflito; bloqueio pessimista é prevenção de conflito.

Uma boa analogia é o controle de versão, que você usa todo dia. Duas pessoas precisam mexer no mesmo arquivo.

No jeito otimista, o do Git (e antes dele o do CVS e do Subversion), as duas copiam o arquivo e editam à vontade, sem pedir permissão a ninguém. Quem termina primeiro envia sem problema. Quando a segunda tenta enviar, o sistema compara e recusa: isto aqui mudou desde que você copiou. Ela junta as mudanças e envia de novo.

No jeito pessimista, o de sistemas mais antigos no modelo “trava, modifica, destrava”, quem chega primeiro trava o arquivo. A segunda pessoa simplesmente não consegue editar até a primeira liberar. Conflito nunca acontece, porque nunca há duas edições ao mesmo tempo.

A frase carrega três consequências, que valem mais do que ela:

Onde o custo cai. No otimista, o caso normal é de graça: ninguém espera por ninguém, e só se paga quando o conflito de fato acontece. No pessimista, o custo é cobrado sempre: mesmo quando ninguém mais ia mexer naquela linha, o segundo espera do mesmo jeito. Um cobra por conflito; o outro cobra por acesso.
Quem lida com a falha. Detecção produz erro, e erro precisa de dono: alguém relê, refaz e tenta outra vez. Prevenção produz espera. Por isso o pessimista parece mais simples no código: no caso normal, não há caminho de exceção para escrever. O preço aparece no comportamento sob carga.
O que acontece com o trabalho já feito. No otimista, a segunda pessoa trabalhou e pode ter que jogar tudo fora. No pessimista, ela nem começou: ficou parada. Quando o trabalho é caro ou demorado, jogar fora dói; quando é barato, esperar dói mais.

A aposta de cada um está no próprio nome. O otimista aposta que conflito é raro; se estiver certo, você ganha concorrência de graça. O pessimista aposta que conflito é provável; se estiver certo, você evita um monte de trabalho perdido. Escolher entre os dois é uma aposta sobre a frequência de conflito na sua carga, e isso se mede, não se escolhe por gosto.

2. Bloqueio otimista#

A aposta é que conflito é raro. Ninguém trava nada; todo mundo lê e trabalha à vontade. Na hora de gravar, a escrita carrega a pergunta junto: o dado ainda está como eu li?

A forma de fazer essa pergunta é uma coluna de versão, um número inteiro que muda a cada gravação. Todo UPDATE incrementa a versão e filtra pela versão que foi lida. Se outra transação gravou antes, o filtro não encontra a linha e o banco devolve zero linhas afetadas. Zero linhas afetadas é a detecção do conflito.

Em SQL puro

-- lido antes: saldo = 100, version = 1
UPDATE conta
   SET saldo   = 90,
       version = version + 1
 WHERE id = 1
   AND version = 1;
-- UPDATE 1 -> gravou
-- UPDATE 0 -> alguém mudou a linha nesse meio-tempo

O ponto essencial: a verificação e a escrita são o mesmo comando. Não existe janela entre uma e outra, e é por isso que funciona sem travar nada.

Dá para usar uma coluna updated_at no lugar da versão, mas um número inteiro é mais claro e não depende da precisão do relógio. A própria documentação do Hibernate diz que timestamp é uma forma menos confiável de bloqueio otimista do que número de versão.

Em Spring Data JPA

O Hibernate faz isso sozinho a partir de uma anotação:

@Entity
public class Conta {

    @Id
    private Long id;

    private BigDecimal saldo;

    @Version                 // habilita o bloqueio otimista
    private Long version;    // o Hibernate cuida do incremento
}

Com isso, todo UPDATE que o Hibernate gera para a entidade inclui a versão no filtro (update conta set saldo=?, version=? where id=? and version=?). Se nenhuma linha for afetada, o Hibernate lança OptimisticLockException (da JPA), e o Spring a entrega traduzida como ObjectOptimisticLockingFailureException.

Como o conflito agora é um erro, alguém precisa decidir o que fazer com ele. Uma resposta comum é tentar de novo. Desde o Spring Framework 7 (Spring Boot 4), a anotação @Retryable faz parte do próprio framework e é habilitada com @EnableResilientMethods numa classe de configuração:

@Retryable(
    includes = ObjectOptimisticLockingFailureException.class,
    maxRetries = 2,          // 1 tentativa + 2 retentativas
    delay = 50,
    multiplier = 2,
    jitter = 25
)
@Transactional
public void debitar(Long contaId, BigDecimal valor) {
    Conta conta = repo.findById(contaId).orElseThrow();
    conta.setSaldo(conta.getSaldo().subtract(valor));
    repo.save(conta);
}

Dois detalhes que sempre dão errado. Primeiro, o retry precisa reler o dado: retentar com a entidade velha em mãos falha de novo, sempre. Aqui isso funciona porque o @Retryable envolve o @Transactional: cada tentativa abre uma transação nova e faz um findById novo. Segundo, precisa de teto: três tentativas no total, não um laço infinito. Num teste com Spring Boot 4.1, forçando uma gravação concorrente na primeira tentativa, a segunda releu o saldo já alterado e gravou normalmente.

O projeto Spring Retry, de onde vinha o @Retryable com retryFor e @Backoff, foi arquivado e substituído pelos recursos de resiliência do Spring Framework 7. Em Spring Boot 3, ele ainda é o caminho.

O que costuma passar batido: a versão funciona mesmo entre requisições diferentes, separadas por minutos. Das duas técnicas de banco deste post, é a única que resolve o caso do usuário que abriu um formulário às 10h e salvou às 10h15: a transação no banco durou milissegundos, mas a versão lida às 10h continua sendo o critério. Basta a tela devolver a versão junto com os dados. É exatamente o padrão que o Fowler chama de Optimistic Offline Lock; “offline” porque a proteção atravessa várias requisições, fora de uma única transação do banco.

3. Bloqueio pessimista#

A aposta é a inversa: conflito é provável, então é melhor não deixar acontecer. Quem chega primeiro trava a linha, e os outros esperam.

Em SQL puro

BEGIN;

SELECT saldo
  FROM conta
 WHERE id = 1
   FOR UPDATE;        -- a partir daqui a linha está travada

-- a aplicação confere o saldo e decide

UPDATE conta SET saldo = saldo - 10 WHERE id = 1;

COMMIT;               -- a trava só sai aqui

Quem pedir a mesma linha com FOR UPDATE nesse meio-tempo fica esperando. Quando a primeira transação faz COMMIT, a segunda recebe a trava e lê a versão já atualizada da linha, e não a que existia quando começou a esperar. É isso que impede o lost update.

Três variações que vale conhecer no PostgreSQL:

FOR UPDATE NOWAIT: em vez de esperar, falha na hora se a linha estiver travada (could not obtain lock on row). Bom quando esperar é pior que desistir.
FOR UPDATE SKIP LOCKED: pula as linhas travadas e devolve as outras. É assim que se implementa fila de trabalho em tabela: vários workers pegam itens diferentes sem disputar o mesmo.
lock_timeout: parâmetro de configuração que limita quanto tempo um comando espera por uma trava (por exemplo, SET LOCAL lock_timeout = '3s' vale só para a transação atual). O padrão é 0, que desliga o limite: sem configurar, a espera é indefinida.

Em Spring Data JPA

public interface ContaRepository extends JpaRepository<Conta, Long> {

    @Lock(LockModeType.PESSIMISTIC_WRITE)   // no PostgreSQL: SELECT ... FOR NO KEY UPDATE
    @QueryHints(@QueryHint(name = "jakarta.persistence.lock.timeout", value = "3000"))
    @Query("select c from Conta c where c.id = :id")
    Optional<Conta> findByIdParaAtualizar(@Param("id") Long id);
}

Três cuidados com esse código:

O SQL gerado não é exatamente FOR UPDATE. No PostgreSQL, o Hibernate traduz PESSIMISTIC_WRITE para FOR NO KEY UPDATE, uma trava um pouco mais fraca: bloqueia UPDATEs, DELETEs e outros FOR UPDATE ou FOR NO KEY UPDATE na linha, mas deixa passar o FOR KEY SHARE, a trava mais leve de todas. Para o lost update, o efeito é o mesmo.
O timeout depende da versão do Hibernate. A dica jakarta.persistence.lock.timeout (em milissegundos) só funciona no PostgreSQL em versões recentes do Hibernate 7, que executam SET LOCAL lock_timeout antes da consulta. Em testes contra o PostgreSQL 17, ela funcionou no Hibernate 7.2.24, 7.3.13 e 7.4.5 (os de Spring Boot 4.0.8 e 4.1.1): a espera parou em 3 segundos com erro de trava (no Spring Boot 4.1, CannotAcquireLockException). No Hibernate 6.6 (Spring Boot 3.5) e em 7.1.8, 7.2.0 e 7.3.0, foi ignorada sem aviso, e a espera continuou indefinida. Confirme na sua versão com um teste, ou defina lock_timeout direto no banco, que vale para qualquer versão.
A trava precisa de uma transação em volta. O método de serviço que chama esse repositório deve ser @Transactional. Sem transação, a JPA recusa a consulta com trava (TransactionRequiredException, que o Spring entrega como InvalidDataAccessApiUsageException). E a trava só faz sentido se a leitura e a gravação estiverem na mesma transação, porque ela é liberada no fim dela.

O que costuma passar batido: a trava dura até o commit. Se dentro da transação você chamar o adquirente e ele levar 800 ms, a linha fica travada por 800 ms e todo mundo que quiser aquela linha entra na fila atrás. Não chame serviço externo com uma trava na mão. Como separar a chamada externa da gravação local sem perder nenhuma das duas é o tema do post Efeito externo sem registro local.

4. O UPDATE condicional, que muitas vezes dispensa os dois#

Muita coisa que parece precisar de trava não precisa, porque dá para deixar o próprio banco fazer a conta:

UPDATE conta
   SET saldo = saldo - 10
 WHERE id = 1
   AND saldo >= 10;
-- UPDATE 1 -> debitou
-- UPDATE 0 -> saldo insuficiente

Aqui não há leitura prévia na aplicação, então não há janela e não há lost update. O UPDATE trava a linha por conta própria enquanto grava. Se dois débitos chegam juntos, o segundo espera o primeiro terminar e, no nível de isolamento padrão do PostgreSQL, reavalia o WHERE sobre o saldo já atualizado. Num teste com saldo 15 e dois débitos simultâneos de 10, um afetou uma linha e o outro afetou zero, e o saldo terminou em 5.

Essa é a primeira pergunta a fazer antes de escolher entre otimista e pessimista: dá para escrever isso como um único comando? Se der, nenhum dos dois é necessário. No post sobre arquitetura de ledger, a mesma ideia aparece como balance locking: condicionar a escrita ao saldo em vez de à versão.

5. Como escolher#

	Otimista	Pessimista
Estratégia	detecta o conflito ao gravar	evita o conflito antes
Custo no caso normal	nenhum: ninguém espera	espera de quem chega depois
Custo sob disputa	retentativas, que podem virar avalanche	fila, e risco de deadlock
Quem trata a falha	a aplicação, relendo e tentando de novo	ninguém no caso normal; timeout e deadlock ainda viram erro
Funciona entre requisições?	sim, com a versão indo e voltando	não com trava de banco, que só vive dentro da transação
Onde encaixa	conflito raro, leitura pesada, edição por tela	conflito frequente, operação crítica, transação curta

Na descrição do Fowler, o pessimista limita a concorrência do sistema, enquanto o otimista deixa várias pessoas trabalharem nos mesmos dados ao mesmo tempo. Na prática, isso leva a uma regra que funciona bem: comece otimista, que é mais simples e não cria filas. A pergunta certa não é “quando usar o otimista”, e sim “quando o otimista sozinho não basta”.

No meu domínio, o critério prático é a taxa de disputa pela mesma linha. Cadastro de cooperado, limite, parâmetro de produto: otimista. Saldo de uma única conta em dia de pico, ou contador de uso de limite: pessimista ou, melhor ainda, um único UPDATE condicional.

6. Padrões nomeados#

Já explicados acima; aqui fica só o nome formal

Lost update: duas leituras, dois cálculos, duas escritas, e uma delas desaparece sem erro. Onde mais aparece: contador de estoque, saldo, qualquer campo calculado a partir do valor lido.
Optimistic Offline Lock: nome do padrão no catálogo do Fowler. “Offline” porque a proteção vale além de uma transação do banco, atravessando requisições. Onde mais aparece: ETag com If-Match em HTTP, que a RFC 9110 descreve justamente como proteção contra o lost update; o campo _rev no CouchDB, que recusa com 409 a gravação feita sobre uma revisão antiga; edição concorrente de documentos.
Pessimistic Offline Lock: o par do anterior. Como a trava de banco não sobrevive ao fim da transação, aqui a trava é da aplicação: um registro (numa tabela de travas, por exemplo) dizendo quem está editando o quê, obtido antes de começar e liberado no fim. Onde mais aparece: check-out de arquivo em sistemas de versão antigos, reserva de assento, qualquer “só um por vez”.

Mencionados de passagem; vale saber o que são

Deadlock: duas transações travam as mesmas linhas em ordem invertida e ficam esperando uma pela outra para sempre. O PostgreSQL detecta o ciclo (a checagem roda depois de deadlock_timeout, 1 segundo por padrão) e aborta uma das duas com deadlock detected. A prevenção é simples e quase nunca feita: travar sempre na mesma ordem, por exemplo ordenando por id. É um risco típico do pessimista, mas não exclusivo dele: um UPDATE comum também trava a linha até o commit, então duas transações que atualizam as mesmas contas em ordem invertida podem entrar em deadlock mesmo sem FOR UPDATE, com ou sem coluna de versão.
Níveis de isolamento: a outra forma de tratar concorrência, no nível da transação inteira em vez de linha a linha. O PostgreSQL usa READ COMMITTED por padrão, que não impede o lost update do padrão “leu na aplicação, calculou, gravou”; daí a necessidade de bloqueio explícito. Em REPEATABLE READ e SERIALIZABLE, o PostgreSQL impede, mas abortando a segunda transação com could not serialize access due to concurrent update, e a aplicação precisa saber retentar. Vale saber que existe: é pergunta clássica de entrevista para vaga sênior.
SELECT ... FOR UPDATE SKIP LOCKED como fila: truque para usar uma tabela como fila de trabalho sem broker de mensagens. A documentação do PostgreSQL cita exatamente esse uso: evitar disputa entre vários consumidores de uma tabela que funciona como fila. Por que importa: permite processar lotes com vários workers em paralelo sem que dois peguem o mesmo item.

7. Onde eu apertaria numa entrevista#

Você colocou @Version e o conflito virou exceção. Quem trata? E o que o usuário final vê?
Sob disputa alta, o otimista entra em avalanche de retentativas. Como você percebe isso antes do cliente?
Uma transação com FOR UPDATE chama o adquirente por dentro. O que acontece com as outras requisições daquela conta?
Como você evita deadlock quando precisa travar duas linhas na mesma transação?
O time quer subir o isolamento para SERIALIZABLE e “resolver de uma vez”. Que argumento você traz?

Fontes#

Martin Fowler — Optimistic Offline Lock (Patterns of Enterprise Application Architecture)
Martin Fowler — Pessimistic Offline Lock
Version Control with Subversion — Version Control Basics (lock-modify-unlock e copy-modify-merge)
PostgreSQL — Explicit Locking (modos de trava de linha e deadlocks)
PostgreSQL — SELECT: cláusula de trava (NOWAIT, SKIP LOCKED)
PostgreSQL — Client Connection Defaults (lock_timeout)
PostgreSQL — Transaction Isolation
Hibernate ORM — User Guide: Locking
Hibernate ORM — PostgreSQLLockingSupport (aplicação do lock timeout via SET LOCAL lock_timeout)
Spring Data JPA — Locking e Transactionality
Spring Framework — Resilience Features (@Retryable)
Spring Retry — repositório (arquivado, substituído pelo Spring Framework 7)
IETF — RFC 9110, HTTP Semantics (requisições condicionais e o “lost update”)
Apache CouchDB — API de documentos (_rev e 409 Conflict)
Vlad Mihalcea — artigos sobre explicit locking em JPA e Hibernate
Stormatics — Ensuring Safe Data Modifications in PostgreSQL, parte 2 (bloqueio otimista)

Virtual threads no Java 21 — pinning e CLOSE_WAIT

Sat, 12 Sep 2026 00:00:00 GMT

Um serviço Java 21 com virtual threads para de responder no pico, sem nenhum erro no log, e o host acumula milhares de sockets em CLOSE_WAIT. Este post segue o diagnóstico em formato de desafio: primeiro o sintoma, depois a resposta que parecia certa, onde ela falhou e a causa real, o pinning de virtual threads dentro de blocos synchronized. Em seguida vem o que continua valendo mesmo depois da correção: limites explícitos com bulkhead e circuit breaker, com código Java que você pode rodar.

Em quais versões isso acontece. O pinning por synchronized existe do Java 21 ao 23. O Java 24 corrigiu o problema com a JEP 491, e o Java 25 é a primeira LTS com a correção. As seções 6 e 7 (gargalo, bulkhead e circuit breaker) valem para qualquer versão. O modelo de virtual threads está no post do Java 21 e a correção, no post do Java 25.

1. Desafio#

Enunciado. Serviço de autorização de cartões, Spring Boot 3 com Tomcat embarcado, Java 21. O time ligou virtual threads para processar as requisições (spring.threads.virtual.enabled=true, disponível a partir do Spring Boot 3.2). Cada autorização chama o adquirente, a empresa que processa a transação de cartão para o lojista.

Dois dias depois, no pico da tarde, uma instância para de responder. Não devolve erro: simplesmente não responde. O health check estoura o tempo, o Kubernetes reinicia o pod, e tudo volta ao normal por algumas horas.

Os sinais:

A JVM está viva. Sem OutOfMemoryError, sem exceção, sem stack trace no log.
CPU baixa, memória estável, GC comportado.
No host, milhares de sockets em CLOSE_WAIT.
Não reproduz em homologação. O teste de carga sintético passa limpo.

O que está acontecendo?

2. Vocabulário que faltava#

O diagnóstico começa pelo vocabulário: sem ele, o raciocínio trava. São quatro peças.

Socket — a ponta que cada lado segura numa conexão de rede. Funciona como o telefone numa ligação: enquanto a ligação existe, ele está ocupado. Cada requisição HTTP em curso usa um, e socket é recurso finito: cada um conta no limite de arquivos abertos do processo.

CLOSE_WAIT — estado TCP que significa “o outro lado desligou, o seu ainda não”. Encerrar uma conexão exige que os dois lados desliguem, e quem desliga do seu lado é a aplicação, chamando close(), não o sistema operacional (RFC 9293). Milhares de sockets nesse estado significam que o código parou de chegar à linha que fecha a conexão.

Platform thread — a thread tradicional do Java, que corresponde a uma thread do sistema operacional (SO). É cara: só a pilha reserva 1 MB por padrão no Linux x64 (documentação do java). Por isso ninguém cria uma por requisição: cria-se um pool, e as requisições se revezam. O Tomcat do Spring Boot usa, por padrão, até 200 (server.tomcat.threads.max). O desperdício aparece quando o trabalho é esperar: 300 ms esperando o adquirente são 300 ms de uma thread ocupada sem fazer nada.

Virtual thread — thread gerenciada pela JVM, não pelo SO. É barata a ponto de uma JVM poder ter milhões (JEP 444). Ela não substitui as threads reais: para executar, é montada sobre uma das poucas carrier threads, que são platform threads de um pool da JVM (por padrão, uma por processador disponível). Quando a virtual thread bloqueia em I/O, a JVM normalmente a desmonta da carrier e coloca outra no lugar. É esse revezamento que faz o modelo funcionar.

3. Resposta dada#

O microsserviço para de responder porque não tem thread disponível. O problema deve estar nos sockets em CLOSE_WAIT — teria que descobrir por que a aplicação não está encerrando os sockets.

4. Onde furou#

Dois ajustes.

Não faltou virtual thread, faltou carrier. Virtual thread é barata, e a JVM cria quantas forem precisas. O gargalo é o punhado de threads reais embaixo delas. Se cada carrier fica presa a uma virtual thread que bloqueou e não desmontou, pode haver dezenas de milhares de virtual threads prontas, e nenhuma consegue executar. Esse estado tem nome: pinning (a virtual thread fica “pregada” à carrier).

A causalidade é a inversa. O CLOSE_WAIT não é a causa, é a impressão digital. As carriers travaram, então o código parou de rodar, então ninguém chegou à linha que fecha o socket. Os clientes estouraram o timeout e desligaram do lado deles. Milhares de CLOSE_WAIT são o retrato de uma aplicação congelada, não de um bug no fechamento de conexões.

O diagrama mostra a cadeia completa, do pico de requisições até os sockets em CLOSE_WAIT:

5. Aprendizado — pinning (Java 21 a 23)#

No Java 21, a virtual thread fica presa à carrier em dois casos (JEP 444): quando bloqueia dentro de um bloco ou método synchronized, e durante um método nativo ou função estrangeira. O primeiro é o que pesa: segundo a JEP 491, resolvê-lo elimina quase todos os casos de pinning.

O motivo é interno da JVM. Até o Java 23, ela registra como dona do monitor de um objeto (o lock que o synchronized adquire) a platform thread, ou seja, a carrier, e não a virtual thread. Se a virtual thread desmontasse ali dentro, outra virtual thread montada na mesma carrier pareceria dona do monitor, e a exclusão mútua se perderia (JEP 491). Então a JVM não desmonta: a carrier fica bloqueada junto. E a JEP 444 é explícita: o escalonador não compensa o pinning criando carriers extras.

Veja acontecer. O programa abaixo roda 100 tarefas que esperam 100 ms cada, uma vez segurando um synchronized e outra segurando um ReentrantLock. Cada tarefa tem o próprio lock, então ninguém disputa nada: a única diferença é o tipo de lock.

import java.time.Duration;
import java.time.Instant;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.locks.ReentrantLock;
import java.util.stream.IntStream;

public class CarrierPresa {

    static void esperarAdquirente() {
        try {
            Thread.sleep(100); // espera de I/O: aqui a virtual thread deveria desmontar
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    static void comSynchronized() {
        Object monitor = new Object(); // um por tarefa: ninguém disputa o lock
        synchronized (monitor) {
            esperarAdquirente();
        }
    }

    static void comReentrantLock() {
        ReentrantLock lock = new ReentrantLock(); // um por tarefa, como acima
        lock.lock();
        try {
            esperarAdquirente();
        } finally {
            lock.unlock();
        }
    }

    static long medir(Runnable tarefa) {
        Instant inicio = Instant.now();
        try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
            IntStream.range(0, 100).forEach(i -> executor.submit(tarefa));
        }
        return Duration.between(inicio, Instant.now()).toMillis();
    }

    public static void main(String[] args) {
        System.out.println("Java " + Runtime.version().feature());
        System.out.println("synchronized:  " + medir(CarrierPresa::comSynchronized) + " ms");
        System.out.println("ReentrantLock: " + medir(CarrierPresa::comReentrantLock) + " ms");
    }
}

Rodando com 4 carriers, como numa máquina de 4 vCPUs, nas imagens eclipse-temurin:21 e eclipse-temurin:25:

$ java -Djdk.virtualThreadScheduler.parallelism=4 CarrierPresa.java
Java 21
synchronized:  2581 ms
ReentrantLock: 106 ms

$ java -Djdk.virtualThreadScheduler.parallelism=4 CarrierPresa.java
Java 25
synchronized:  149 ms
ReentrantLock: 104 ms

No Java 21, com synchronized, só 4 tarefas avançam por vez: 100 tarefas ÷ 4 carriers × 100 ms ≈ 2,5 s. Com ReentrantLock, as 100 esperam juntas. No Java 25, os dois casos se comportam igual. Os tempos exatos variam de máquina para máquina; a proporção é o que importa.

Nem sempre o synchronized está no seu código. A Netflix documentou exatamente esse quadro em julho de 2024: Spring Boot 3, Tomcat embarcado, Java 21, instâncias que paravam de responder e sockets acumulados em CLOSE_WAIT. Ali, o synchronized vinha da biblioteca de tracing Brave (em RealSpan.finish). Dentro dele, as virtual threads esperavam um ReentrantLock do reporter do Zipkin. As instâncias tinham 4 vCPUs, portanto 4 carriers. Com as quatro presas, quando o lock era liberado, a virtual thread que deveria recebê-lo não tinha carrier para executar, e nada mais andava. Os sockets em CLOSE_WAIT batiam com milhares de virtual threads que o Tomcat tinha criado e que nunca chegaram a executar.

É também por isso que homologação passa limpo: pinning só vira travamento quando há concorrência suficiente para prender todas as carriers ao mesmo tempo. Com carga baixa, uma carrier presa passa despercebida.

Como se descobre

Thread dump no formato novo. O dump tradicional (jstack ou jcmd <pid> Thread.print) não mostra virtual threads (JEP 444); foi o que confundiu a Netflix no começo, porque o dump parecia ocioso. Use jcmd <pid> Thread.dump_to_file -format=text dump.txt (ou -format=json; o nome do arquivo é obrigatório). Nele, as carriers (ForkJoinPool-1-worker-N) aparecem executando Continuation.run, e as virtual threads montadas nelas aparecem paradas no mesmo ponto, dentro do synchronized. Esse ponto é a resposta. As demais virtual threads aparecem sem stack: foram criadas e esperam uma carrier.
JFR (JDK Flight Recorder), o gravador de eventos embutido na JVM. O evento jdk.VirtualThreadPinned registra, com stack trace, cada vez que uma virtual thread fica parada presa à carrier por mais de 20 ms, o limiar padrão. O evento vem habilitado, mas só é gravado se houver uma gravação ativa: java -XX:StartFlightRecording=filename=rec.jfr ... e depois jfr print --events jdk.VirtualThreadPinned rec.jfr. No CarrierPresa.java, o Java 21 grava 100 eventos, um por tarefa com synchronized; o Java 25 grava zero. Manter o evento ligado em produção, com alerta, é uma das recomendações do artigo da InfoQ citado nas fontes.
-Djdk.tracePinnedThreads=short (ou full), só do Java 21 ao 23. Imprime o stack sempre que uma virtual thread bloqueia presa, e o frame marcado aponta o synchronized:
```
VirtualThread[#25]/runnable@ForkJoinPool-1-worker-2 reason:MONITOR
    CarrierPresa.comSynchronized(CarrierPresa.java:21) <== monitors:1
```
A JEP 491 removeu essa propriedade no Java 24.

Como se resolve

Subir para o Java 24 ou mais novo, na prática para o Java 25, a primeira LTS com a JEP 491. A partir dela, a virtual thread desmonta ao bloquear dentro de synchronized ou em Object.wait(). É o conserto definitivo e vale também para o synchronized das dependências. Os detalhes estão no post do Java 25.
Trocar synchronized por ReentrantLock, se o serviço fica no Java 21. É a mesma exclusão mútua, mas a espera não prende a carrier. A JEP 444 recomenda a troca só onde o bloco roda com frequência e protege I/O potencialmente longo; blocos raros ou que só protegem operações em memória podem ficar como estão. No Java 24 em diante, a JEP 491 volta a recomendar synchronized onde for prático.
Atualizar a dependência, se o synchronized está numa biblioteca e uma versão nova já trocou o lock. Se não trocou, não há o que refatorar no seu código: resta subir o Java.

Um upgrade de Java leva semanas, e no plantão a mitigação imediata é outra: desligar as virtual threads por configuração (spring.threads.virtual.enabled=false) e voltar ao pool tradicional. Perde escalabilidade, mas para de cair. Curativo e conserto são coisas separadas.

6. Aprendizado — o gargalo mudou de lugar#

O Java 25 resolve o pinning por synchronized, mas não resolve o que vem junto com as virtual threads. Esta parte vale para qualquer versão.

No modelo antigo, o pool de 200 threads do Tomcat fazia dois trabalhos sem ninguém perceber: separava o trabalho de cada requisição e limitava quantas requisições estavam em andamento, portanto quantas chamadas saíam do serviço ao mesmo tempo. Com virtual threads, cada requisição ganha a sua thread, e o segundo trabalho desaparece. A propriedade server.tomcat.threads.max nem tem efeito quando as virtual threads estão ligadas.

Chegam 10 mil requisições no pico:

No Postgres, nada é derrubado de imediato: forma-se fila. O pool de conexões do HikariCP tem teto (o padrão é 10; digamos que o time configurou 20). Vinte requisições pegam conexão e o resto espera. Quem não consegue conexão em 30 segundos, o connectionTimeout padrão, recebe erro, e isso acontece em massa (HikariCP). Essa fila não existia antes: com 200 threads, no máximo 200 requisições pediam conexão, e as demais nem tinham começado.
No adquirente, é pior, porque o problema sai de casa. Milhares de chamadas simultâneas chegam a um terceiro com contrato para 500. Ele recusa ou fica lento, e aí você tem milhares de conexões abertas esperando.

Virtual threads não eliminam gargalo, mudam o gargalo de lugar. O conserto é tornar explícito o que era implícito: um limite declarado em cada recurso compartilhado, com o número decidido por você em vez de herdado do tamanho do pool.

7. As três peças juntas#

São três trabalhos diferentes, e nenhum substitui o outro:

Virtual threads dão vazão, isto é, mais trabalho em andamento ao mesmo tempo. Não deixam nada mais rápido: se o adquirente leva 300 ms, continua levando 300 ms. O que muda é quantas requisições cabem simultaneamente.
Bulkhead limita a saída. É preventivo e funciona o tempo todo: declara quantas chamadas simultâneas podem sair do serviço para um destino. Devolve o limite que o pool de threads dava de graça.
Circuit breaker interrompe. É reativo e só age quando o destino está mal: percebe a sequência de falhas e para de insistir por um tempo.

Um sem o outro deixa buraco. Se o adquirente está lento, só com o bulkhead cada requisição ainda espera até 200 ms por uma vaga (o maxWaitDuration dos exemplos abaixo), mais o tempo da própria chamada, para descobrir o que as últimas dezenas de falhas já tinham mostrado.

Vazão — o efeito das virtual threads#

Roda direto com java Vazao.java no Java 21 ou mais novo, sem dependência nenhuma. O Thread.sleep faz o papel da chamada ao adquirente.

import java.time.Duration;
import java.time.Instant;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.stream.IntStream;

public class Vazao {

    static void chamadaAoAdquirente() {
        try {
            Thread.sleep(300); // espera de I/O: a thread não faz nada aqui
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }

    static long medir(ExecutorService executor) {
        Instant inicio = Instant.now();
        try (executor) { // close() espera todas terminarem
            IntStream.range(0, 1000)
                     .forEach(i -> executor.submit(Vazao::chamadaAoAdquirente));
        }
        return Duration.between(inicio, Instant.now()).toMillis();
    }

    public static void main(String[] args) {
        System.out.println("pool de 200 threads: " + medir(Executors.newFixedThreadPool(200)) + " ms");
        System.out.println("virtual threads:     " + medir(Executors.newVirtualThreadPerTaskExecutor()) + " ms");
    }
}

pool de 200 threads: 1623 ms
virtual threads:     324 ms

São mil chamadas de 300 ms. Com 200 threads, elas saem em cinco levas: no mínimo 1500 ms, um pouco mais na prática, porque criar as threads também custa. Com virtual threads, todas ficam em andamento juntas, perto de 300 ms. É esse número que deveria acender a luz amarela: mil chamadas simultâneas saindo para um terceiro.

Bulkhead — o limite, sem dependência#

Também roda sozinho. O Semaphore limita a 100 as chamadas simultâneas, e o programa mostra o pico real de chamadas em andamento e quantas foram recusadas pelo próprio serviço.

import java.util.concurrent.Executors;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Semaphore;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.stream.IntStream;

public class BulkheadSimples {

    static final Semaphore limite = new Semaphore(100);
    static final AtomicInteger emVoo = new AtomicInteger();
    static final AtomicInteger pico = new AtomicInteger();
    static final AtomicInteger recusadas = new AtomicInteger();

    static void capturar() {
        if (!entrar()) {              // não conseguiu vaga a tempo
            recusadas.incrementAndGet();
            return;                   // recusa rápida, decidida por você
        }
        try {
            int agora = emVoo.incrementAndGet();
            pico.updateAndGet(p -> Math.max(p, agora));
            Thread.sleep(300);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        } finally {
            emVoo.decrementAndGet();
            limite.release();         // sem isto, o limite vaza até zerar
        }
    }

    static boolean entrar() {
        try {
            return limite.tryAcquire(200, TimeUnit.MILLISECONDS);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            return false;
        }
    }

    public static void main(String[] args) {
        try (ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor()) {
            IntStream.range(0, 1000).forEach(i -> executor.submit(BulkheadSimples::capturar));
        }
        System.out.println("pico de chamadas simultâneas: " + pico.get());
        System.out.println("recusadas por você:           " + recusadas.get());
    }
}

pico de chamadas simultâneas: 100
recusadas por você:           900

O pico nunca passa de 100, por mais requisições que cheguem. As 100 primeiras entram; as outras 900 esperam 200 ms por uma vaga, e nenhuma vaga abre antes dos 300 ms da chamada, então são recusadas. O finally é o ponto crítico do código: se a permissão não for devolvida em todo caminho de saída, inclusive em exceção, o limite encolhe sozinho até travar tudo.

De onde vem o número. Não é chute nem é o contrato do parceiro (o contrato é o teto, não a meta). Vem da lei de Little: chamadas em andamento = vazão × tempo médio de resposta. Cem chamadas por segundo com resposta em 300 ms dão 30 chamadas em andamento, em média. Some uma folga para picos e meça. O 100 dos exemplos é só ilustrativo.

Circuit breaker — com Resilience4j#

Aqui entra dependência. No Maven:

<dependency>
  <groupId>io.github.resilience4j</groupId>
  <artifactId>resilience4j-circuitbreaker</artifactId>
  <version>2.4.0</version>
</dependency>

O exemplo abaixo simula um parceiro que falha por um tempo e depois volta, e imprime cada mudança de estado:

import io.github.resilience4j.circuitbreaker.CallNotPermittedException;
import io.github.resilience4j.circuitbreaker.CircuitBreaker;
import io.github.resilience4j.circuitbreaker.CircuitBreakerConfig;

import java.time.Duration;

public class Breaker {

    static volatile boolean parceiroFora = true;

    static String capturar() {
        if (parceiroFora) throw new RuntimeException("adquirente indisponível");
        return "CAPTURADO";
    }

    public static void main(String[] args) throws Exception {
        CircuitBreakerConfig config = CircuitBreakerConfig.custom()
            .slidingWindowType(CircuitBreakerConfig.SlidingWindowType.COUNT_BASED)
            .slidingWindowSize(20)                        // olha as últimas 20 chamadas
            .minimumNumberOfCalls(10)                     // só decide depois de 10
            .failureRateThreshold(50)                     // abre com 50% de falha
            .waitDurationInOpenState(Duration.ofSeconds(3))
            .permittedNumberOfCallsInHalfOpenState(3)     // sondagem ao voltar
            .build();

        CircuitBreaker breaker = CircuitBreaker.of("adquirente", config);
        breaker.getEventPublisher()
               .onStateTransition(e -> System.out.println(">> " + e.getStateTransition()));

        for (int i = 1; i <= 60; i++) {
            if (i == 40) parceiroFora = false;  // parceiro se recupera
            try {
                String resposta = breaker.executeSupplier(Breaker::capturar);
                System.out.println(i + ": " + resposta);
            } catch (CallNotPermittedException e) {
                System.out.println(i + ": barrado pelo breaker, sem sair da aplicação");
            } catch (RuntimeException e) {
                System.out.println(i + ": falhou no parceiro");
            }
            Thread.sleep(150);
        }
    }
}

Para rodar sem Maven, basta pôr no classpath os JARs resilience4j-circuitbreaker, resilience4j-core e slf4j-api (java -cp "lib/*" Breaker.java). A saída, resumida (o SLF4J imprime antes um aviso de que não há logger configurado, que pode ser ignorado):

1: falhou no parceiro
...
9: falhou no parceiro
>> State transition from CLOSED to OPEN
10: falhou no parceiro
11: barrado pelo breaker, sem sair da aplicação
...
29: barrado pelo breaker, sem sair da aplicação
>> State transition from OPEN to HALF_OPEN
30: falhou no parceiro
31: falhou no parceiro
>> State transition from HALF_OPEN to OPEN
32: falhou no parceiro
33: barrado pelo breaker, sem sair da aplicação
...
51: barrado pelo breaker, sem sair da aplicação
>> State transition from OPEN to HALF_OPEN
52: CAPTURADO
53: CAPTURADO
>> State transition from HALF_OPEN to CLOSED
54: CAPTURADO
...
60: CAPTURADO

A sequência inteira aparece:

As 10 primeiras chamadas falham de verdade. Na décima, a taxa de falha chega a 100% e o breaker abre. A linha >> sai antes de 10: falhou porque o evento dispara quando o breaker registra a falha, antes de a exceção chegar ao catch.
Durante 3 segundos (cerca de 20 voltas de 150 ms), as chamadas são barradas sem sair da aplicação.
Na primeira chamada depois desse tempo, o breaker passa a meio-aberto e deixa 3 chamadas passarem para sondar. O parceiro ainda está fora, então ele abre de novo.
O parceiro volta na chamada 40, mas o breaker só descobre na sondagem seguinte, na 52. As 3 chamadas de sondagem dão certo e o breaker fecha.

Os três estados: fechado é o saudável, com a corrente passando (o nome confunde no começo); aberto é o disjuntor desarmado, com falha imediata e sem tráfego; meio-aberto deixa poucas chamadas passarem para sondar e decide se fecha ou abre de novo.

De onde vem, e o que ele não é. O circuit breaker não tem relação com virtual threads. Ele é bem mais antigo: aparece no livro Release It!, de Michael Nygard, de 2007, e ficou conhecido com o Hystrix, que a Netflix abriu em 2012, mais de dez anos antes das virtual threads. O problema que ele resolve é de sistema distribuído: parar de insistir com um serviço que está mal. Vale em qualquer linguagem, com ou sem threads, síncrono ou assíncrono. O mesmo vale para o bulkhead, que vem do mesmo livro.

A relação com este caso é outra, e vale guardar assim: virtual threads não criaram a necessidade, tiraram o disfarce. O pool de 200 threads dava um limite acidental de graça, e esse limite mascarava a ausência das duas proteções. Ao remover o pool, o que estava escondido apareceu.

Isso importa na hora de aplicar. Quem conclui que “circuit breaker é coisa de virtual thread” deixa de usá-lo nos serviços que continuam com pool, e lá ele é igualmente necessário; só que a falha demora mais a aparecer.

Em produção, com Spring Boot#

No Spring Boot, o mesmo vira configuração. O starter do Resilience4j exige o AOP e o Actuator do Spring Boot:

<dependency>
  <groupId>io.github.resilience4j</groupId>
  <artifactId>resilience4j-spring-boot3</artifactId>
  <version>2.4.0</version>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-aop</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

resilience4j:
  bulkhead:
    instances:
      adquirente:
        maxConcurrentCalls: 100
        maxWaitDuration: 200ms
  circuitbreaker:
    instances:
      adquirente:
        slidingWindowType: COUNT_BASED
        slidingWindowSize: 20
        minimumNumberOfCalls: 10
        failureRateThreshold: 50
        waitDurationInOpenState: 3s
        permittedNumberOfCallsInHalfOpenState: 3

@Bulkhead(name = "adquirente")
@CircuitBreaker(name = "adquirente", fallbackMethod = "indisponivel")
public Resposta capturar(Cobranca cobranca) {
    return adquirenteClient.capturar(cobranca);
}

// mesma assinatura do método protegido, mais a exceção no final
private Resposta indisponivel(Cobranca cobranca, Throwable causa) {
    return Resposta.negada("INDISPONIVEL_TEMPORARIAMENTE");
}

Com o Actuator, as métricas do bulkhead e do breaker saem pelo Micrometer, e dali para o Prometheus, o Dynatrace ou a ferramenta de observabilidade do time.

Cinco detalhes que costumam morder:

Use o bulkhead de semáforo, não o de thread pool. O Resilience4j tem as duas variantes, e a de thread pool reintroduz exatamente o pool que você acabou de tirar. @Bulkhead sem type já usa o de semáforo.
As anotações só funcionam através do proxy do Spring. Se outro método da mesma classe chama capturar() direto, o bulkhead e o breaker não rodam. O motivo está em A pegadinha da self-invocation.
Timeout é pré-requisito. Sem tempo limite na chamada HTTP, ela não falha: fica pendurada. Uma chamada que nunca termina nunca entra na conta do breaker, que então não abre, e as conexões esperando se acumulam.
O limiar é proporção, não contagem. Baixo demais, o breaker abre por qualquer soluço; alto demais, nunca abre. E o minimumNumberOfCalls evita que três falhas às três da manhã, com tráfego baixo, abram o disjuntor.
Cuidado com a ordem dos aspectos. Por padrão, o Resilience4j aplica, de fora para dentro: Retry, CircuitBreaker, RateLimiter, TimeLimiter, Bulkhead (a ordem pode ser mudada por propriedades como resilience4j.retry.retryAspectOrder). Sendo o mais externo, o retry repete o conjunto inteiro. Por isso ele precisa de espera crescente com um pouco de aleatoriedade (backoff exponencial com jitter), ou você cria uma tempestade de retries que derruba de vez quem já estava mal. Em cobrança, retry também exige idempotência: veja Cobrança duplicada no retry.

O que devolver para quem foi recusado#

Em cartão, negar não é falhar. Um erro genérico obriga a maquininha a decidir sem informação. Uma negativa com um código de indisponibilidade temporária diz que o problema é passageiro, e não uma recusa por saldo ou por suspeita de fraude. Quem recebe pode tentar de novo depois, e quem atende o portador (o titular do cartão) sabe o que aconteceu.

O critério para escolher entre recusa imediata e nova tentativa é o orçamento de tempo. Uma autorização síncrona tem poucos segundos, então recusar rápido é o caminho principal. Retentar fica para os fluxos assíncronos, como ajuste financeiro, estorno e processamento em lote, onde a espera cabe.

8. Padrões nomeados#

Já explicados acima — aqui fica só o nome formal

Carrier pinning — a virtual thread bloqueia sem conseguir desmontar e mantém a carrier refém. Por synchronized, só do Java 21 ao 23. Onde mais aparece: mesmo no Java 24 em diante, ainda há pinning quando código nativo chama de volta código Java que bloqueia, e durante o carregamento e a inicialização de classes (JEP 491). O Java 26 tirou um desses casos, a espera pela inicialização de uma classe (post do Java 29).
CLOSE_WAIT como sintoma — socket que o outro lado fechou e o seu não. Onde mais aparece: vazamento de conexão por close() que não roda, cliente HTTP sem try-with-resources, pool que nunca devolve a conexão. É um dos primeiros lugares a olhar quando o processo está vivo, mas mudo.
Deslocamento de gargalo — remover um limite não aumenta a capacidade, só empurra a fila para o próximo recurso escasso. Onde mais aparece: aumentar o pool de threads e derrubar o banco, subir réplicas e saturar a rede, paralelizar um job e estourar a cota de uma API de terceiro.
Bulkhead — limite declarado de chamadas simultâneas a um recurso, para que a sobrecarga de uma dependência não afunde o serviço inteiro. O nome vem das anteparas que dividem o casco de um navio em compartimentos estanques. Vem do livro Release It!, de Michael Nygard (2007), e não tem nada a ver com virtual threads. Onde mais aparece: pool de conexões separado por dependência, limite de consumidores por tópico, isolamento de clientes (tenants) em SaaS.
Circuit breaker — para de chamar quem está falhando, espera e volta sondando. Três estados: fechado, aberto e meio-aberto. Também vem do Release It! (2007) e foi popularizado pelo Hystrix, da Netflix, em 2012, anos antes das virtual threads. Onde mais aparece: em qualquer chamada a terceiro, e também entre microsserviços internos. Virtual threads não criaram a necessidade dele nem do bulkhead, só tiraram o disfarce, porque o pool de threads dava um limite acidental que mascarava a ausência dos dois.

Mencionados de passagem — vale saber o que são

Backpressure — mecanismo pelo qual quem está sobrecarregado sinaliza a quem produz que desacelere, em vez de aceitar tudo e desmoronar. Semáforo, fila limitada e rate limit são formas de aplicar. Por que importa aqui: virtual threads não aplicam backpressure sozinhas, elas aceitam tudo o que chega. O freio precisa ser declarado, como o semáforo do bulkhead.
Scoped Values — alternativa ao ThreadLocal para compartilhar dados imutáveis ao longo de uma chamada, finalizada no Java 25 (JEP 506; detalhes no post do Java 25). Virtual threads não devem ser reaproveitadas em pool, então o velho hábito de guardar um objeto caro por thread vira um objeto por requisição. Como elas podem ser muitas, a JEP 444 pede cuidado com ThreadLocal: o consumo de memória só aparece sob carga alta. Onde mais aparece: propagação de contexto, como usuário autenticado, trace id e tenant.
JEP — JDK Enhancement Proposal, o documento que descreve cada mudança da plataforma e o raciocínio por trás dela. A JEP 444 trouxe as virtual threads no Java 21; a JEP 491 corrigiu o pinning por synchronized no Java 24. Por que está aqui: ler a JEP é a forma de conferir o que uma versão mudou sem depender de post de blog.

9. Onde eu apertaria numa entrevista#

O upgrade para o Java 25 leva semanas. O que você faz hoje, no plantão?
Java 25 e Spring Boot 4 no mesmo deploy: se algo quebrar, como você sabe qual dos dois foi?
Qual número você coloca no semáforo do adquirente, e como chega nele?
Depois de tudo corrigido, que métrica no Dynatrace avisaria que o pinning voltou?
O teste de carga passou limpo. O que faltava nele?

Fontes#

OpenJDK — JEP 444: Virtual Threads (casos de pinning, carriers, thread dump, JFR, ThreadLocal)
OpenJDK — JEP 491: Synchronize Virtual Threads without Pinning (Java 24)
OpenJDK — JEP 506: Scoped Values (Java 25)
Oracle — Virtual Threads (guia do Java 21)
Oracle — The java Command (tamanho padrão da pilha, -Xss)
Netflix Technology Blog — Java 21 Virtual Threads: Dude, Where’s My Lock? (julho de 2024)
InfoQ — Virtual Threads after JDK 24: What Changed for Production Java
IETF — RFC 9293: Transmission Control Protocol (estados TCP, CLOSE-WAIT)
Spring Boot — Common Application Properties (spring.threads.virtual.enabled, server.tomcat.threads.max)
Spring Boot — Spring Boot 3.2 Release Notes (suporte a virtual threads)
HikariCP — README (maximumPoolSize e connectionTimeout padrão)
Resilience4j — CircuitBreaker, Bulkhead e Getting Started com Spring Boot 3 (dependências, ordem dos aspectos, fallback)
Martin Fowler — CircuitBreaker
ACM Digital Library — Release It!: Design and Deploy Production-Ready Software (Michael T. Nygard, 2007)
Netflix Technology Blog — Introducing Hystrix for Resilience Engineering (novembro de 2012)
Wikipedia — Little’s law
AWS Architecture Blog — Exponential Backoff And Jitter

Efeito externo sem registro local — a cobrança passou e o banco não gravou

Fri, 11 Sep 2026 00:00:00 GMT

Seu serviço cobrou o cliente no adquirente (a empresa que processa a transação de cartão), mas o processo morreu antes de gravar a cobrança no banco. O dinheiro saiu e você não tem registro disso. Este post mostra por que retry e alerta não resolvem, e qual desenho garante que todo efeito externo deixa rastro local: gravar a intenção antes de agir, com tabela outbox, relay e conciliação. É a continuação de Cobrança duplicada no retry.

Formato do artigo: um cenário real, a primeira resposta que costuma aparecer, onde ela falha e o que fica de aprendizado.

1. Desafio#

A chave de idempotência está implantada e funcionando. Um dia, o gráfico mostra cobranças que aparecem na fatura do cliente, mas não existem no seu banco.

Investigando, o fluxo é este: o serviço chama o adquirente, a captura (a efetivação da cobrança) passa, e só depois o serviço grava a cobrança no Postgres. Entre as duas coisas, o processo morreu.

Como você desenha isso para que nunca exista dinheiro cobrado sem registro?

O que o cenário não diz, e vale perguntar: com que frequência isso acontece, se o adquirente permite consultar o status depois e quanto tempo o cliente aceita esperar pela resposta.

2. A primeira resposta#

Envolvo a chamada em try/catch. Se a gravação falhar, faço retry algumas vezes; se ainda assim falhar, registro no log e disparo um alerta para o time olhar.

3. Onde furou#

Retry e alerta tratam o sintoma depois que o dano já existe. Nenhum dos dois muda o fato estrutural: o efeito externo aconteceu antes de existir qualquer registro local.

E se o processo morre de verdade, não há try/catch que rode: o bloco de tratamento morre junto. Isso acontece quando o contêiner é encerrado à força (SIGKILL), seja por falta de memória (OOM), seja num deploy que estoura o prazo de desligamento. O post SIGTERM e SIGKILL detalha esse ciclo no Kubernetes.

O detalhe mais desconfortável: a chave de idempotência do post sobre cobrança duplicada no retry não protege aqui. Ela só existiria dentro da linha que não chegou a ser gravada, então o retry seguinte chega sem nada para comparar e captura de novo.

4. Aprendizado: o problema da escrita dupla#

Escrever em dois sistemas que não compartilham transação é a escrita dupla (dual write). Seu banco não sabe nada sobre o adquirente, e não existe commit que cubra os dois. Uma falha entre as duas escritas deixa os dois lados discordando.

O que não resolve, mesmo parecendo que resolve:

Inverter a ordem: gravar a cobrança como concluída e só depois chamar o adquirente troca o problema de lado. Em vez de cobrança sem registro, você passa a ter registro sem cobrança.
Retry no catch: só roda se o processo continuar vivo. E, quando a falha é ambígua (um timeout, por exemplo), ela não diz se a operação aconteceu; repetir às cegas pode transformar perda em duplicidade.
Transação distribuída com 2PC (two-phase commit, explicado na seção 5): a API do adquirente não participa desse protocolo. E, mesmo entre sistemas que participam, os recursos ficam travados enquanto o coordenador não decide, e uma falha do coordenador deixa todos bloqueados.

O que resolve é mudar o que se escreve primeiro: grave a intenção antes de causar o efeito.

Numa única transação do Postgres, o serviço grava a cobrança com status PENDENTE e, na tabela outbox (uma tabela de eventos a publicar), o evento CobrancaIniciada. Ou as duas linhas existem, ou nenhuma.
Só depois do commit ele chama o adquirente, enviando a mesma chave de idempotência, se o adquirente aceitar uma (a API da Stripe, por exemplo, aceita o cabeçalho Idempotency-Key). Assim, repetir a captura é seguro.
Com a resposta, atualiza a linha para CAPTURADO e grava o evento CobrancaCapturada no outbox, também numa transação só.

Se o processo cair no meio do caminho, sobra um PENDENTE contando exatamente o que faltou terminar. E o retry do cliente agora esbarra numa linha que existe: em vez de capturar às cegas, o serviço sabe que precisa descobrir o que aconteceu com aquela chave.

Duas peças completam o desenho:

Relay do outbox: um processo separado lê a tabela outbox, publica os eventos no broker de mensagens e os marca como enviados. Se cair no meio, publica de novo, então a entrega é pelo menos uma vez e quem consome precisa ser idempotente.
Conciliação: um job varre os PENDENTE antigos e pergunta o status ao adquirente. Se a captura passou, atualiza a linha; se não passou, marca como falha ou tenta de novo com a mesma chave. É a rede que pega o que escapou.

5. Padrões nomeados#

Já explicados acima; aqui fica só o nome formal

Dual write problem: uma operação lógica que precisa escrever em dois sistemas sem transação comum; qualquer falha no meio deixa os dois discordando. Onde mais aparece: banco mais fila, banco mais cache, banco mais índice de busca, banco mais API de terceiro. É a mesma forma em todos.
Transactional outbox: dado e evento gravados na mesma transação; a entrega do evento vira um passo separado e repetível. Onde mais aparece: qualquer serviço que precisa avisar outro depois de mudar o próprio estado, como no post sobre W3C Trace Context, em que o traceparent viaja pelo outbox.
Intenção gravada antes do efeito (pending state): registrar a intenção antes de causar o efeito, para que a falha deixe rastro em vez de silêncio. É um nome descritivo, não um padrão de catálogo; o artigo de Brandur Leach sobre chaves de idempotência formaliza a mesma ideia como fases atômicas com pontos de recuperação. Onde mais aparece: upload em duas etapas, emissão de nota fiscal, provisionamento de recurso em nuvem. É o princípio do write-ahead log do banco (a mudança é registrada no log antes de ser aplicada) levado para o nível da aplicação.
Reconciliation (conciliação): comparar periodicamente o seu estado com o do sistema externo e corrigir a diferença. Onde mais aparece: fechamento contábil, estoque integrado a marketplace, cobrança recorrente. O post Arquitetura de ledger mostra a conciliação aplicada a saldos.

Mencionados de passagem; vale saber o que são

Change Data Capture (CDC): em vez de um processo consultar a tabela outbox de tempos em tempos (polling), uma ferramenta lê o log de transações do próprio banco e publica cada mudança quase em tempo real. O Debezium é o nome mais comum. Quando usar no lugar do relay por polling: quando o atraso do intervalo de consulta não cabe, ou quando o volume torna as consultas caras. O que custa: mais uma peça de infraestrutura para operar e monitorar. Por isso o polling, que funciona com qualquer banco SQL, costuma ser o ponto de partida.
Event sourcing: em vez de guardar o estado atual e emitir eventos, você guarda só a sequência de eventos e calcula o estado a partir dela. Resolve a escrita dupla entre estado e eventos por eliminação: gravar um evento é uma operação só. Atenção: não elimina a chamada ao adquirente; o efeito externo continua precisando da intenção registrada antes. Quando aparece: quando o histórico completo é requisito de negócio, o que é comum em domínio financeiro. O que custa: muda o modelo de dados inteiro e dificulta consultas (em geral exige CQRS), então é decisão de arquitetura, não ajuste pontual.
Two-phase commit (2PC): protocolo em que um coordenador pergunta a todos os participantes se podem confirmar e só então manda confirmar. Existe e funciona entre recursos que o suportam, mas é bloqueante: os participantes seguram travas enquanto esperam a decisão e, se o coordenador falha, ficam presos. E uma API HTTP de terceiro, como a do adquirente, não é participante de 2PC. Por que está aqui: é a resposta que parece óbvia para quem acabou de conhecer o problema, e saber por que ela é rejeitada vale mais do que saber que ela existe.

6. Onde eu apertaria numa entrevista#

O relay parou silenciosamente. Como você descobre antes do cliente?
Quanto tempo uma cobrança pode ficar PENDENTE antes de virar incidente?
E se o adquirente responder “não sei” quando a conciliação perguntar?
A tabela outbox cresce sem parar. Quem limpa, e quando?
Se a conciliação roda como CronJob no Kubernetes, o que acontece quando duas execuções se sobrepõem?
Vale trocar o relay por CDC no seu caso, ou o polling já resolve?

Fontes#

AWS Prescriptive Guidance — Transactional outbox pattern
Confluent — Understanding the Dual-Write Problem
microservices.io — Pattern: Transactional outbox
microservices.io — Pattern: Polling publisher
microservices.io — Pattern: Event sourcing
Debezium — Reliable Microservices Data Exchange With the Outbox Pattern
Brandur Leach — Implementing Stripe-like Idempotency Keys in Postgres
Stripe — Idempotent requests
PostgreSQL — Write-Ahead Logging (WAL)
PostgreSQL — PREPARE TRANSACTION
Wikipedia — Two-phase commit protocol
Kubernetes — Assign Memory Resources to Containers
Kubernetes — Pod Lifecycle: Termination of Pods

Cobrança duplicada no retry

Thu, 10 Sep 2026 00:00:00 GMT

Um timeout não diz se a operação aconteceu. Quando o app reenvia uma cobrança depois de um timeout, o serviço precisa reconhecer a repetição e não cobrar de novo. Parece simples, mas a solução mais intuitiva, consultar antes de gravar, falha justamente quando o serviço roda em várias instâncias.

O post segue um roteiro: o cenário, a primeira resposta que costuma aparecer, onde ela falha e a solução que funciona (chave de idempotência, restrição única no banco e resposta guardada), com SQL testado no PostgreSQL 17 e os cuidados de produção.

1. O cenário#

O app do cliente envia uma requisição de cobrança de R$ 250 para o serviço de autorização. A resposta não chega a tempo e a requisição estoura o timeout. Do lado do cliente, não dá para saber o que aconteceu: o servidor pode ter cobrado, pode ainda estar processando ou pode nem ter recebido o pedido. Então o app reenvia.

O serviço roda em várias instâncias atrás de um load balancer. O reenvio pode cair numa instância diferente da primeira, e pode chegar enquanto a primeira ainda está trabalhando.

Como garantir que o cliente seja cobrado uma vez só?

O nome da propriedade que falta é idempotência: uma operação é idempotente quando repeti-la tem o mesmo efeito que executá-la uma vez. A especificação do HTTP (RFC 9110) classifica GET, PUT e DELETE como idempotentes por definição; POST não é. Uma cobrança é um POST, e cada repetição sem proteção vira uma cobrança nova.

O que o cenário deixa em aberto de propósito: o volume, se o cliente controla o reenvio, por quanto tempo a garantia precisa valer, o que acontece se o reenvio vier no dia seguinte.

2. A primeira resposta#

Antes de gravar a cobrança, o serviço consulta a tabela procurando uma cobrança com o mesmo número de pedido. Se já existir, devolve a que existe. Se não existir, insere e captura.

3. Onde ela falha#

A ideia está certa: reconhecer o pedido repetido e não cobrar de novo. O problema é onde a verificação acontece.

Consultar e depois gravar são duas operações separadas, e entre elas existe uma janela, curta, mas real. Se a requisição original e o reenvio caem em instâncias diferentes ao mesmo tempo, as duas consultam antes de qualquer uma gravar, as duas encontram a tabela vazia e as duas cobram.

Esse defeito tem nome: condição de corrida do tipo verificar-e-agir (check-then-act). A decisão foi tomada com base num estado que mudou antes da ação.

Isso dificilmente aparece em teste local, onde as requisições costumam chegar em sequência. Aparece em produção, no pico, quando o volume aumenta a chance de as duas coincidirem. O cenário é fácil de reproduzir no PostgreSQL: duas conexões simultâneas que consultam, esperam um segundo e inserem acabam gravando as duas.

4. A solução: gravar primeiro e deixar o banco recusar#

A garantia precisa estar em quem consegue decidir sozinho, sem janela: o banco.

São três peças:

Chave de idempotência: um identificador que o cliente gera uma vez por intenção de cobrança e repete em todas as tentativas dessa mesma intenção, normalmente num cabeçalho Idempotency-Key. A Stripe recomenda um UUID v4 ou outro valor aleatório com entropia suficiente para não colidir, e sem dados pessoais. O id do pedido só serve como chave se cada pedido puder ser cobrado uma única vez; se o mesmo pedido pode ter cobranças legítimas separadas, a chave precisa identificar a cobrança, não o pedido.
Restrição única (UNIQUE) no banco sobre essa chave. É ela que transforma “duas gravações” em “uma gravação e uma recusa”.
Resposta guardada: a primeira tentativa salva o que respondeu. As seguintes, ao esbarrar na restrição, leem e devolvem exatamente a mesma resposta.

A ordem se inverte: em vez de verificar e depois gravar, você grava e deixa o banco recusar. A janela some porque verificar e gravar passam a ser a mesma operação.

Na prática, com SQL#

Uma tabela mínima no PostgreSQL:

CREATE TABLE cobranca (
    id              bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    idempotency_key text   NOT NULL,
    pedido_id       bigint NOT NULL,
    valor_centavos  bigint NOT NULL,
    status          text   NOT NULL,  -- PROCESSANDO, CAPTURADA ou RECUSADA
    resposta_http   int,              -- status HTTP devolvido na primeira vez
    resposta_corpo  jsonb,            -- corpo devolvido na primeira vez
    criada_em       timestamptz NOT NULL DEFAULT now(),
    CONSTRAINT uq_cobranca_idempotency_key UNIQUE (idempotency_key)
);

Passo 1: registrar a tentativa antes de cobrar. Toda requisição começa tentando inserir a chave, já com o status PROCESSANDO:

INSERT INTO cobranca (idempotency_key, pedido_id, valor_centavos, status)
VALUES ('5b0e7a52-3f1c-4d7e-9a61-2c8f0d4e7b13', 123, 25000, 'PROCESSANDO')
ON CONFLICT (idempotency_key) DO NOTHING
RETURNING id;

O ON CONFLICT ... DO NOTHING faz o banco ignorar a inserção se a chave já existir, em vez de lançar erro. Como o RETURNING só devolve linhas de fato inseridas, o resultado responde à pergunta sem janela nenhuma:

1 linha: esta requisição é a primeira. Confirme a transação (commit), chame o adquirente e grave o resultado (passo 2).
0 linhas: a chave já existia. Não cobre; leia o registro (passo 3).

Sem o ON CONFLICT, a segunda inserção falha com duplicate key value violates unique constraint "uq_cobranca_idempotency_key". Funciona do mesmo jeito, só que a aplicação precisa tratar a exceção.

Passo 2: guardar a resposta depois que o adquirente responder:

UPDATE cobranca
   SET status         = 'CAPTURADA',
       resposta_http  = 201,
       resposta_corpo = '{"cobranca_id": 1, "status": "CAPTURADA"}'
 WHERE idempotency_key = '5b0e7a52-3f1c-4d7e-9a61-2c8f0d4e7b13';

Passo 3: responder a uma repetição.

SELECT status, pedido_id, valor_centavos, resposta_http, resposta_corpo
  FROM cobranca
 WHERE idempotency_key = '5b0e7a52-3f1c-4d7e-9a61-2c8f0d4e7b13';

Se pedido_id ou valor_centavos forem diferentes dos da requisição atual, a chave foi reaproveitada para outra operação. Recuse: o rascunho da IETF para o cabeçalho Idempotency-Key sugere 422 Unprocessable Content, e a Stripe também devolve erro quando os parâmetros não batem com os da requisição original.
Se o status for PROCESSANDO, a primeira tentativa ainda não terminou. Responda 409 Conflict para o cliente tentar de novo mais tarde; é o que o mesmo rascunho propõe.
Se já houver resposta guardada, devolva resposta_http e resposta_corpo como estão.

Cuidados#

Confirme o registro antes de chamar o adquirente. Se a inserção e a chamada externa ficarem na mesma transação aberta, a segunda inserção com a mesma chave não recusa na hora: o PostgreSQL faz quem tenta inserir esperar até a outra transação terminar. Num teste com PostgreSQL 17, o reenvio ficou parado os dois segundos que a primeira transação levou, e só então recebeu 0 linhas. Sob carga, isso vira conexões presas e fila, e o cliente nunca vê o PROCESSANDO.
Um PROCESSANDO pode ficar órfão. Se o processo morrer entre o commit e a resposta do adquirente, sobra um registro sem desfecho. Descobrir se a cobrança passou é trabalho de conciliação, tema do post Efeito externo sem registro local.
Decida por quanto tempo a chave vale. A Stripe pode remover chaves com pelo menos 24 horas de idade; uma chave reutilizada depois disso gera uma requisição nova. O rascunho da IETF deixa o prazo para cada API definir e publicar na documentação. Prazo mais longo protege reenvios tardios e custa armazenamento.
Decida se erro também fica guardado. A Stripe guarda o status e o corpo da primeira resposta seja sucesso ou falha, inclusive erros 500. Com isso, uma nova tentativa depois de uma recusa exige chave nova, porque é uma nova intenção.

5. Padrões nomeados#

Já explicados acima; aqui fica só o nome formal

Idempotency Key: o cliente marca a intenção com um identificador, e o servidor garante que ela produza efeito uma vez só, chegue quantas vezes chegar. Onde mais aparece: webhooks, APIs públicas de pagamento, comandos consumidos de fila.
Check-then-act race condition: verificar um estado e agir com base nele em duas operações separadas; entre uma e outra, o estado muda. Na forma mais geral é catalogada como TOCTOU (time-of-check to time-of-use, CWE-367). Onde mais aparece: reserva de estoque, cadastro por e-mail, débito de saldo e o clássico “verifica se o arquivo existe antes de criar”.
Restrição única como mecanismo de concorrência: usar a integridade do banco no lugar de coordenação na aplicação. A decisão fica atômica porque acontece dentro da própria escrita. Onde mais aparece: slug de URL, número de matrícula, qualquer regra do tipo “só pode existir um”.

Mencionados de passagem; vale saber o que são

Entrega pelo menos uma vez (at-least-once delivery): a mensagem pode chegar repetida, mas não se perde. É a garantia padrão do Kafka, da fila Standard do SQS e do RabbitMQ com confirmações (acks) na publicação e no consumo, e é o que qualquer retry HTTP produz. “Exatamente uma vez” existe só em escopos limitados, como a deduplicação de 5 minutos das filas FIFO do SQS ou as transações dentro do próprio Kafka; quando o efeito sai para um sistema externo, a documentação do Kafka lembra que o destino precisa cooperar. Na prática, entrega-se pelo menos uma vez e o consumidor é idempotente, o que produz o mesmo efeito final. Onde mais aparece: toda arquitetura de eventos, e é por isso que idempotência e mensageria andam juntas.
Bloqueio pessimista e bloqueio otimista: as alternativas à restrição única. No pessimista (SELECT ... FOR UPDATE), você trava a linha e os concorrentes esperam até você terminar; funciona, mas cria contenção e risco de deadlock sob carga. No otimista, você adiciona uma coluna de versão e só grava se a versão não mudou; quem perde tenta de novo. Os dois precisam de uma linha que já exista. Neste cenário a cobrança ainda não existe, então seria preciso travar outra linha, como a do pedido, o que é mais um motivo para preferir a restrição única. Quando usar no lugar dela: quando a decisão depende de ler e combinar valores e não cabe numa única chave. Onde mais aparece: edição concorrente de cadastro, controle de saldo, qualquer “leu, calculou, gravou”. Os dois são detalhados no post Bloqueio otimista e pessimista.

6. Onde eu apertaria numa entrevista#

Por quanto tempo a chave vale? Um dia, um mês, para sempre? O que essa escolha custa em armazenamento, e o que acontece com o reenvio que chega depois do prazo?
Um registro está em PROCESSANDO há dez minutos. Quem decide se a cobrança passou, e com base em quê?
E se a captura no adquirente passar, mas a gravação da resposta no banco falhar?
Como isso muda se a cobrança virar um evento assíncrono, consumido de uma fila, em vez de uma chamada síncrona?

Fontes#

IETF — RFC 9110: HTTP Semantics, seção 9.2.2 (métodos idempotentes)
IETF — The Idempotency-Key HTTP Header Field (Internet-Draft)
Stripe — Idempotent requests
PostgreSQL 17 — Index Uniqueness Checks
PostgreSQL 17 — INSERT (ON CONFLICT e RETURNING)
PostgreSQL 17 — Constraints (Unique Constraints)
MITRE — CWE-367: Time-of-check Time-of-use (TOCTOU) Race Condition
Apache Kafka — Design: Message Delivery Semantics
AWS — Amazon SQS at-least-once delivery
AWS — Exactly-once processing in Amazon SQS
RabbitMQ — Reliability Guide
ByteByteGo — How to Avoid Double Payment

Arquitetura de ledger — partidas dobradas, saldos e conciliação

Thu, 28 May 2026 00:00:00 GMT

Todo sistema que movimenta valor — dinheiro, créditos, pontos — esbarra nos mesmos problemas: como garantir que nada seja criado nem destruído por acidente, como responder “qual era o saldo naquela data” e como perceber quando o número exibido divergiu da verdade. Os artigos resumidos aqui chegam à mesma resposta: ledger append-only + saldo materializado + conciliação.

Este post resume 12 artigos sobre o assunto — as séries How to Scale a Ledger e Accounting for Developers, da Modern Treasury, e mais três textos independentes —, com os exemplos de código convertidos para Java. Cada seção traz a ideia central do artigo, os pontos importantes e o link para o original. Se contabilidade é novidade para você, vale ler antes as seções 8 a 10 (os fundamentos) e depois voltar ao começo.

O modelo que todos compartilham tem três peças: a account (conta), a transaction (o movimento completo) e as entries (os lançamentos de débito e crédito que compõem a transaction):

Vocabulário mínimo#

Os termos abaixo aparecem o tempo todo no post:

Ledger (livro-razão): o registro de todos os movimentos de valor de um sistema.
Double-entry (partidas dobradas): todo movimento tem pelo menos um débito e um crédito, e a soma dos débitos é igual à soma dos créditos. Dinheiro sempre sai de algum lugar e entra em outro.
Débito e crédito: não significam “tira” e “põe”. O efeito de cada um depende do tipo da conta (a normalidade, explicada nas seções 3 e 8).
Append-only: só se acrescentam registros; nada é alterado nem apagado. Um erro se corrige com um novo lançamento, que compensa o anterior.
Saldo materializado: saldo pré-calculado e guardado para leitura rápida, mas sempre derivado dos lançamentos.
Drift: divergência entre o saldo guardado e a soma dos lançamentos.
Conciliação: comparar dois registros que deveriam bater (saldo guardado × lançamentos, ou ledger × extrato do banco) e tratar as diferenças.
Idempotência: repetir a mesma requisição não repete o efeito. O tema tem post próprio: Cobrança duplicada no retry.
Liquidação (settlement): o momento em que o dinheiro efetivamente muda de mãos, em geral depois da autorização.

1. Ledger confiável em sistema event-driven, sem transações gigantes#

Visão geral: como construir um ledger de grau financeiro num sistema distribuído e orientado a eventos sem envolver cada operação numa transação de banco gigante. A consistência vem de concorrência otimista, particionamento e restrições de unicidade — não de locks globais.

Pontos importantes:

Event sourcing: cada mudança vira um evento imutável (depósito, saque, bloqueio de valor). Em vez de guardar só o saldo final, você guarda todos os eventos, e o saldo pode ser reconstruído a partir deles. Isso dá trilha de auditoria completa e permite reprocessar tudo (replay) se a lógica mudar.
CQRS (separação entre comando e consulta): o lado de comando recebe “Sacar $30” e, se o comando for válido, emite o evento FundsWithdrawn. O lado de consulta assina os eventos e atualiza um read model (uma tabela otimizada para leitura, como account_balances). A consulta de saldo lê essa tabela em vez de reprocessar todos os eventos.
O problema de concorrência: dois eventos quase simultâneos na mesma conta (depósito de $50 e saque de $30) podem ler dados desatualizados e perder ou contar dinheiro em dobro se não houver controle.
Três técnicas para resolver sem transação gigante:
1. Controle de concorrência otimista (OCC): cada conta — o aggregate, no vocabulário de DDD — tem uma version inteira. Ao gravar um evento, você informa a versão que leu; se ela mudou porque outro evento entrou antes, a gravação falha e você recarrega o estado e tenta de novo (compare-and-swap). O assunto é aprofundado em Bloqueio otimista e pessimista.
2. Particionamento por conta: sistemas como o Kafka particionam as mensagens por uma chave, aqui o account_id. Cada partição é consumida em sequência por uma única thread, o que garante ordem serial dentro da mesma conta e paralelismo entre contas diferentes.
3. Restrição de unicidade em (aggregate_id, version): o próprio banco rejeita a segunda inserção com a mesma versão. É a salvaguarda do compare-and-swap no nível do banco.
Idempotência no replay: ao reprocessar eventos, guarde o aggregate_id e a versão já aplicados; se o evento já foi aplicado, pule. Assim nada é contado duas vezes.
Saldo bloqueado × disponível: ledgers reais precisam de estados como valores reservados (por exemplo, a autorização de um cartão, que bloqueia o valor antes de liquidar). Modele eventos FundsHeld, FundsReleased e FundsSettled e mantenha uma projeção com held_balance e available_balance.

O event store se resume a uma tabela events (o artigo usa MySQL; aqui, a versão em PostgreSQL):

CREATE TABLE events (
    id           BIGSERIAL    PRIMARY KEY,
    aggregate_id VARCHAR(50)  NOT NULL,
    version      INT          NOT NULL,
    event_type   VARCHAR(255) NOT NULL,
    payload      JSONB        NOT NULL,
    created_at   TIMESTAMPTZ  NOT NULL,
    UNIQUE (aggregate_id, version)
);

O append confere a versão esperada e grava os eventos numa transação curta, que envolve só os eventos daquela conta. A conferência sozinha não basta: dois escritores podem ler a mesma versão ao mesmo tempo. Quem fecha essa brecha é a restrição de unicidade — o segundo INSERT falha com o código 23505 (unique_violation) e vira um conflito de versão:

// Event store com checagem de versão esperada (compare-and-swap)
public class EventStore {

    private static final String UNIQUE_VIOLATION = "23505"; // SQLSTATE do PostgreSQL

    private final DataSource dataSource;

    public EventStore(DataSource dataSource) {
        this.dataSource = dataSource;
    }

    // Versão atual (maior version) de uma conta
    private int getCurrentVersion(Connection conn, String accountId) throws SQLException {
        String sql = "SELECT COALESCE(MAX(version), 0) FROM events WHERE aggregate_id = ?";
        try (PreparedStatement stmt = conn.prepareStatement(sql)) {
            stmt.setString(1, accountId);
            try (ResultSet rs = stmt.executeQuery()) {
                return rs.next() ? rs.getInt(1) : 0;
            }
        }
    }

    // Append com verificação de versão esperada
    public void append(String accountId, int expectedVersion, List<DomainEvent> events)
            throws SQLException {
        try (Connection conn = dataSource.getConnection()) {
            conn.setAutoCommit(false); // transação curta: só os eventos desta conta
            try {
                // 1) Checa a versão mais recente e compara com a esperada
                int currentVersion = getCurrentVersion(conn, accountId);
                if (currentVersion != expectedVersion) {
                    throw new VersionConflictException(
                        "Version conflict! Expected " + expectedVersion + ", got " + currentVersion);
                }

                // 2) Insere cada evento com a versão seguinte
                String insert = "INSERT INTO events " +
                    "(aggregate_id, version, event_type, payload, created_at) " +
                    "VALUES (?, ?, ?, CAST(? AS JSONB), NOW())";
                try (PreparedStatement stmt = conn.prepareStatement(insert)) {
                    for (DomainEvent event : events) {
                        stmt.setString(1, accountId);
                        stmt.setInt(2, ++currentVersion);
                        stmt.setString(3, event.getClass().getName());
                        stmt.setString(4, event.toPayloadJson());
                        stmt.executeUpdate();
                    }
                }
                conn.commit();
            } catch (SQLException | RuntimeException ex) {
                conn.rollback();
                // 3) Outro escritor gravou a mesma (aggregate_id, version) entre a leitura e o insert
                if (ex instanceof SQLException sqlEx && UNIQUE_VIOLATION.equals(sqlEx.getSQLState())) {
                    throw new VersionConflictException("Version conflict on insert", sqlEx);
                }
                throw ex;
            }
        }
    }
}

Quem chama trata o conflito recarregando o estado e revalidando o comando — o saldo pode não ser mais suficiente depois do evento que entrou antes:

// Retry em caso de conflito de versão
public void handleWithdrawCommand(String accountId, BigDecimal withdrawAmount)
        throws SQLException {
    for (int attempt = 1; ; attempt++) {
        // Reconstrói o estado da conta a partir dos eventos
        List<DomainEvent> events = eventStore.loadEvents(accountId);
        AccountAggregate aggregate = new AccountAggregate(accountId, events);
        int expectedVersion = aggregate.getVersion(); // ex.: 5

        // Regra de negócio: recusa o saque se o saldo não for suficiente
        List<DomainEvent> newEvents = aggregate.withdraw(withdrawAmount);

        try {
            eventStore.append(accountId, expectedVersion, newEvents);
            return;
        } catch (VersionConflictException ex) {
            // Outro evento entrou antes: recarrega e revalida na próxima volta
            if (attempt == MAX_ATTEMPTS) {
                throw ex;
            }
        }
    }
}

Fonte: Building a Reliable Ledger in an Event-Sourced System Without Big DB Transactions

2. How to Scale a Ledger, Part I — por que usar um banco de ledger#

Visão geral: toda empresa que move dinheiro em escala precisa de um ledger — um banco de dados double-entry — como fonte única da verdade, em vez de espalhar a lógica financeira pelos modelos de domínio (o objeto “pedido”, “corrida”, “reserva”).

Pontos importantes:

Por que os modelos tradicionais falham em escala:
- as exigências de relatório e auditoria crescem (é preciso saber origem e destino de cada centavo);
- os dados ficam fragmentados entre vários serviços e produtos SaaS que não se integram;
- a performance degrada (jobs de repasse perdem o prazo, a checagem de autorização de cartão atrasa);
- cenários de falha (cobrança a mais, saldo insuficiente, fraude) ficam mais frequentes e difíceis de reverter.
Modelo de dados central: accounts (porções separadas de valor), transactions (eventos monetários atômicos) e entries (os débitos e créditos individuais que compõem a transaction).
As quatro garantias de um ledger escalável:
1. Imutabilidade — estados passados sempre podem ser recuperados; as mudanças são permanentes e consultáveis.
2. Double-entry obrigatório — não dá para mover dinheiro sem informar a origem e o destino.
3. Controle de concorrência — o mesmo dinheiro não pode ser gasto duas vezes, mesmo com escritas paralelas ou fora de ordem.
4. Agregações eficientes — somar eventos financeiros de um período é rápido.
O problema da “tradução”: engenheiros de produto falam a língua do domínio (pedidos, corridas, reservas), mas precisam traduzi-la para a língua de finanças (débitos, créditos, ativos, passivos) — com eventos que chegam fragmentados, de APIs diferentes e de registros que mudam.
Consequência real de erros: um líder de produto de uma grande empresa de pagamentos contou que, todo mês, o time financeiro notava “alguns milhões de dólares” sumidos do ledger. O dinheiro continuava no banco; o que se perdia era a atribuição (o registro de a quem ele pertence).
Por que não construir do zero: um ledger double-entry performático e confiável leva anos de esforço e dezenas de engenheiros sênior; hoje há bancos de dados de ledger prontos.

Fonte: How to Scale a Ledger, Part I

3. Part II — mapeando eventos financeiros#

Visão geral: detalha os três objetos centrais (account, entry, transaction), como mapear eventos financeiros reais neles e como calcular os diferentes tipos de saldo.

Pontos importantes:

Dois princípios básicos: todo evento monetário é registrado num modelo double-entry consistente, e todos os saldos mostrados a usuários e sistemas são lidos desse modelo (nunca de um campo mutável solto).
Account = porção separada de valor, numa moeda. Ela deve informar três saldos:
- Posted (lançado): apenas o que já liquidou.
- Pending (pendente): o que já liquidou mais o que deve liquidar.
- Available (disponível): o que pode sair agora — desconta as saídas previstas e não conta as entradas ainda não liquidadas.
O ciclo de vida de um cartão de crédito ilustra como cada ação afeta esses saldos: compra de passagem (pendente), liquidação, pagamento da fatura, pré-autorização de hotel e sua liberação.
Entry = registro imutável de movimento. Saldos nunca são alterados diretamente; toda mudança entra como uma entry. Os campos centrais (amount, direction) são imutáveis; o único campo mutável é discarded_at, usado só para substituir entries pendentes.
Descartar × reverter: só entries pending podem ser substituídas; entries posted e archived são permanentes. Descartar a pendente, em vez de criar uma entry de reversão, mantém o histórico limpo — os débitos reais do cliente não se misturam com débitos criados só para reverter.
Normalidade da conta (ponto-chave): cada conta é debit normal (usos de recursos: ativos e despesas — aumentam com débito) ou credit normal (fontes de recursos: passivos, patrimônio líquido e receita — aumentam com crédito). Com números positivos e negativos, um depósito não conseguiria aumentar as duas contas envolvidas ao mesmo tempo, porque uma delas teria de ficar negativa para a soma fechar.
Cinco campos para calcular qualquer saldo: posted_debits, posted_credits, pending_debits, pending_credits e normal_balance. O ledger deve buscar esses cinco campos rapidamente e só calcular os saldos quando alguém pedir.

As fórmulas do artigo, em Java (lembrando que, no modelo da Modern Treasury, os totais pending_* já incluem o que está posted):

enum NormalBalance { CREDIT, DEBIT }

public class BalanceCalculator {

    // Posted balance
    public BigDecimal postedBalance(NormalBalance normal,
                                    BigDecimal postedCredits,
                                    BigDecimal postedDebits) {
        return switch (normal) {
            case CREDIT -> postedCredits.subtract(postedDebits);
            case DEBIT  -> postedDebits.subtract(postedCredits);
        };
    }

    // Pending balance
    public BigDecimal pendingBalance(NormalBalance normal,
                                     BigDecimal pendingCredits,
                                     BigDecimal pendingDebits) {
        return switch (normal) {
            case CREDIT -> pendingCredits.subtract(pendingDebits);
            case DEBIT  -> pendingDebits.subtract(pendingCredits);
        };
    }

    // Available balance
    public BigDecimal availableBalance(NormalBalance normal,
                                       BigDecimal postedCredits,
                                       BigDecimal postedDebits,
                                       BigDecimal pendingCredits,
                                       BigDecimal pendingDebits) {
        return switch (normal) {
            case CREDIT -> postedCredits.subtract(pendingDebits);
            case DEBIT  -> postedDebits.subtract(pendingCredits);
        };
    }
}

Fonte: How to Scale a Ledger, Part II

4. Part III — o modelo de transaction#

Visão geral: a transaction, que agrupa as entries, é o que garante movimento de dinheiro atômico e obriga o double-entry. Sem ela, dá para deixar o ledger inconsistente registrando só parte de um movimento.

Pontos importantes:

Uma transaction garante: atomicidade (todas as entries têm sucesso ou falham juntas), consistência (nada de mudanças parciais) e double-entry (entries sempre balanceadas).
O risco sem transaction: se a entry de débito grava, mas a de crédito falha (por exemplo, por um problema de rede), um lado foi debitado e o outro não recebeu nada — o dinheiro se perdeu.
A API só deve permitir criar transactions, nunca entries avulsas. Assim o cliente não consegue deixar um movimento pela metade; as entries são gerenciadas internamente.
Três estados da transaction:
1. Pending (estado inicial): grava débito e crédito como pending, ainda não finalizados.
2. Posted (finalizado): como entries são imutáveis, as pendentes são descartadas e novas entries posted são criadas.
3. Archived (cancelado antes de ser lançado): só transactions pendentes podem ser arquivadas; as entries pendentes são descartadas e novas entries archived são criadas, preservando o histórico do cancelamento.
Tudo ou nada: todas as entries não descartadas de uma transaction têm o mesmo status que ela, e por isso mudam de status juntas.

Fonte: How to Scale a Ledger, Part III

5. Part IV — registrar × autorizar#

Visão geral: um ledger opera em dois modos. No recording (registro), ele só anota o que já aconteceu em outros sistemas; no authorizing (autorização), aprova ou nega transactions ativamente. A maioria das implementações só escala bem em um dos dois; o ideal é escolher o modo no nível da entry.

Pontos importantes:

Recording: alto volume de escrita (milhares por segundo ou mais), processamento assíncrono (as leituras podem ficar alguns segundos defasadas, com consistência eventual) e suporte a consultas complexas. Aqui o ledger não é a fonte da verdade — ele reflete o que já aconteceu em outro lugar (banco, processadora de cartão).
- effective_at: data e hora informadas pelo cliente para retroagir a transaction ao momento em que o dinheiro realmente se moveu. Todas as entries herdam o effective_at da transaction.
- Versões do saldo da conta: como saldos passados podem mudar, cada conta tem uma version incrementada sempre que uma entry é criada ou modificada. Cada entry guarda o account_version correspondente, o que permite saber exatamente quais entries compõem um saldo.
- Casos de uso: exibir detalhes da conta, repasses (payouts), gestão de empréstimos, cripto.
Authorizing: consistência read-after-write (a leitura logo após a escrita já enxerga o novo saldo), volume menor (a performance degrada perto de 100 entries por segundo numa mesma conta), verificações de saldo e controle de concorrência. É o modo para mover dinheiro em tempo real, validando se há saldo — carteiras digitais e autorização de cartão.
- Version locking: o cliente envia a versão da conta junto com o pedido, e o ledger rejeita se a versão no banco for outra (bloqueio otimista). O algoritmo: inicia a transação de banco → grava a entry → atualiza a versão da conta com condição na versão atual → faz commit se a atualização aconteceu, senão rollback.
- Balance locking: o version locking sofre com hot accounts — contas com tanta escrita que a versão muda antes de o cliente conseguir usá-la. A alternativa é condicionar a escrita ao saldo (por exemplo, gte: 0: só grava se o saldo não ficar negativo). No exemplo do artigo, o mesmo resultado sai em 2 chamadas em vez de 6, e a API expressa melhor a intenção.
Modo misto (o ideal): decidir entre recording e authorizing por entry, não por conta. Numa autorização de cartão, a entry da conta do cliente precisa de balance lock e consistência forte, enquanto a entry da conta da processadora (liquidada uma vez por dia) pode ter consistência eventual e alto volume. As duas continuam atômicas na mesma transaction.

Fonte: How to Scale a Ledger, Part IV

6. Part V — imutabilidade e double-entry a fundo#

Visão geral: aprofunda duas das quatro garantias: imutabilidade (qualquer estado passado do ledger pode ser reconstruído) e double-entry (dinheiro não pode ser criado nem destruído).

Pontos importantes:

Imutabilidade apesar de campos mutáveis: o saldo das accounts muda, transactions passam de pending para posted ou archived, entries podem ser descartadas — mas tudo é construído sobre um log append-only imutável. Nada é apagado de fato.
Como consultar estados passados: as entries de uma conta num dado instante são as que têm effective_at menor ou igual a esse instante e não tinham sido descartadas até lá (consulta abaixo).
Versões para precisão: só a data e hora não bastam, porque várias entries podem ter o mesmo effective_at ou discarded_at. As versões da conta gravadas nas entries dizem exatamente quais entries formam um saldo, e as versões passadas da transaction permitem reconstruir estados anteriores.
Log de auditoria: além do estado, registre o que mudou, quem mudou e quando (várias chaves de API, usuários internos pelo painel administrativo). O artigo recomenda um log de auditoria ao lado do ledger.
Validação do double-entry: toda transaction precisa de pelo menos uma entry de débito e uma de crédito, e débitos = créditos em cada moeda.
Por que balancear por moeda: numa compra de 1 ETH com dólares, validar só o total quebra — dá para creditar ETH criado do nada e debitar dólares que simplesmente somem. O certo é agrupar as entries por moeda e validar cada grupo. Uma conversão de moeda sempre envolve pelo menos 4 contas (a plataforma precisa de uma conta em ETH de onde sai a cripto e de uma em dólar onde entra o dinheiro do cliente); modelar com só 2 contas e uma taxa de câmbio não funciona, porque a taxa varia no tempo e não existe uma taxa única aceita por todos.

// Busca as entries presentes numa conta num determinado effective time
public List<Entry> findEntriesAt(String accountId, Instant timestamp) throws SQLException {
    String sql =
        "SELECT * FROM entries " +
        "WHERE account_id = ? " +
        "  AND effective_at <= ? " +
        "  AND (discarded_at IS NULL OR discarded_at >= ?)";
    try (Connection conn = dataSource.getConnection();
         PreparedStatement stmt = conn.prepareStatement(sql)) {
        stmt.setString(1, accountId);
        stmt.setTimestamp(2, Timestamp.from(timestamp));
        stmt.setTimestamp(3, Timestamp.from(timestamp));
        try (ResultSet rs = stmt.executeQuery()) {
            List<Entry> entries = new ArrayList<>();
            while (rs.next()) {
                entries.add(Entry.fromResultSet(rs));
            }
            return entries;
        }
    }
}

Fonte: How to Scale a Ledger, Part V

7. Part VI — concorrência, performance e o job de conciliação#

Visão geral: as duas últimas garantias — controle de concorrência (evitar gastar o mesmo dinheiro duas vezes) e performance (leitura rápida de saldo) — e o job que detecta drift no cache de saldo, que fecha o padrão “registro + saldo + conciliação”. É o artigo que melhor mostra a conciliação interna na prática.

Pontos importantes:

Chaves de idempotência: o cenário clássico — o cliente envia o pedido, o ledger demora, o cliente estoura o timeout e tenta de novo; o pedido original termina e o ledger cria a transaction duas vezes. A solução é deduplicar com uma chave de idempotência: uma string enviada pelo cliente e gerada fora do loop de retry, para que todas as tentativas usem a mesma. Se o ledger recebe uma chave que já conhece, devolve a resposta da primeira requisição. As chaves ficam guardadas por 24 horas.
Performance — cache de saldo: calcular o saldo somando as entries é O(n) e fica lento com dezenas ou centenas de milhares de entries. A solução é cachear pending_debits, pending_credits, posted_debits e posted_credits numa linha da conta.
- Cache do saldo atual: reflete todas as entries e é atualizado de forma síncrona quando entries de autorização são gravadas, porque é ele que sustenta o balance locking. Quem faz a conta de forma atômica é o banco.
- Cache de saldo por data efetiva: mais complexo, com duas abordagens — anchoring (guarda o saldo do fim de cada dia e aplica as entries do dia por cima) e resulting balances (guarda o saldo resultante após cada entry, útil para contas com muitas entries no mesmo dia). No anchoring, a atualização é assíncrona: as entries entram numa fila e o cache é atualizado em lotes.
Monitorando o drift do cache (o job de conciliação): ler o saldo do cache melhora a performance, mas o cache pode divergir das entries, que são a fonte da verdade. O tratamento tem três passos:
1. Verificar regularmente se o saldo em cache de cada conta bate com a soma das entries.
2. Desligar automaticamente a leitura do cache nas contas com drift.
3. Oferecer ferramentas de backfill (recalcular o cache a partir das entries) e um runbook para o plantão investigar e corrigir o drift.

Tópicos avançados de escala: account categories (um modelo em grafo para agregar grupos de contas em relatórios); busca de transactions com paginação por cursor, não por offset; filas de escrita assíncronas que absorvem picos de carga — as fintechs líderes passam facilmente de 5.000 QPS (requisições por segundo); e sharding de contas entre bancos, seja manual, seja com bancos distribuídos como Spanner ou CockroachDB — com o desafio de manter a atomicidade do double-entry entre shards.

// Idempotency key gerada FORA do loop de retry (mesma string em todas as tentativas)
String idempotencyKey = UUID.randomUUID().toString();
TransactionResponse response = null;

for (int attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
    response = createTransaction(idempotencyKey);
    if (response.isSuccessful()) {
        break;
    }
}

// Conceito do job de conciliação: comparar saldo em cache com a soma das entries
public void reconcileAccount(String accountId) throws SQLException {
    BigDecimal cachedBalance = balanceCache.getBalance(accountId);
    BigDecimal computedBalance = sumAllEntries(accountId); // SUM() sobre as entries

    if (cachedBalance.compareTo(computedBalance) != 0) {
        // Drift detectado: desliga a leitura do cache e alerta o plantão (backfill + runbook)
        balanceCache.disableReads(accountId);
        alerting.raiseDrift(accountId, cachedBalance, computedBalance);
    }
}

Fonte: How to Scale a Ledger, Part VI

8. Accounting for Developers, Part I — os fundamentos#

Visão geral: introdução à contabilidade para desenvolvedores: os conceitos de double-entry traduzidos para termos técnicos, para quem constrói sistemas que movem dinheiro.

Pontos importantes:

Princípio central: toda transaction registra de onde o dinheiro veio e em que foi usado. Com isso você reconstrói saldos em qualquer data, rastreia o movimento com auditabilidade total e alinha a lógica do sistema com as finanças reais.
Falha mais comum: o software criar ou destruir registros de dinheiro por acidente. Os sintomas: registros internos diferentes do extrato do banco, ferramentas de conciliação apontando divergências, saldos que não fazem sentido diante das transactions. Uber, Square e Airbnb são citadas como empresas que adotaram double-entry.
Conceitos: account (porção separada de valor), transaction (evento atômico que afeta saldos; tem pelo menos duas entries, afeta duas ou mais contas e mantém o ledger balanceado) e ledger (log de eventos com impacto monetário).
Não altere saldos diretamente: guarde transactions imutáveis e sempre calcule o saldo a partir delas. Alterar o saldo direto parece mais simples e eficiente, mas gera um sistema propenso a erros difíceis de detectar e de conciliar.
Debit normal × credit normal: contas debit normal representam o que você tem ou os usos do dinheiro (ativos, despesas) e aumentam com débito; contas credit normal representam o que você deve ou as fontes do dinheiro (passivos, patrimônio líquido, receita) e aumentam com crédito.

Tipo de conta	Débito	Crédito
Ativo (asset)	+	−
Passivo (liability)	−	+
Patrimônio líquido (equity)	−	+
Receita (revenue)	−	+
Despesa (expense)	+	−

Ledger balanceado: a soma dos saldos das contas credit normal é igual à soma dos saldos das contas debit normal. Se não bate, o sistema criou ou perdeu dinheiro do nada.
Detalhe contraintuitivo: duas contas podem aumentar ao mesmo tempo. No exemplo do artigo, a Modern Bagelry, uma loja on-line de bagels, recebe um aporte de $1 milhão: o caixa (ativo, debit normal) sobe com um débito e o patrimônio líquido (credit normal) sobe com um crédito.

Fonte: Accounting for Developers, Part I

9. Part II — o ledger de uma carteira digital#

Visão geral: aplica os fundamentos construindo, passo a passo, o ledger de uma carteira digital no estilo do Venmo: requisitos → plano de contas → modelagem das transactions → modelagem do banco.

Pontos importantes:

Plano de contas (chart of accounts) do app: Cash (o dinheiro real no banco) → ativo, debit normal; saldo da carteira de cada usuário (uma conta por usuário) → passivo, credit normal (a empresa “deve” esse dinheiro ao usuário); taxas de processamento de cartão → despesa, debit normal; receita com tarifas → credit normal.
Três transactions modeladas:
1. Transferência ($100 de A para B): debita a carteira de quem envia e credita a de quem recebe.
2. Depósito com cartão: crédito de $300 na carteira, contrabalançado por dois débitos — taxa de cartão ($6, ou 2%) e caixa ($294). Um único evento com várias entries.
3. Saque: saque de $500 com tarifa de 0,5% ($2,50) → debita $502,50 da carteira, credita $497,50 no caixa e $2,50 na receita.
Modelagem do banco: accounts (id, user_id, account_type, normality), transactions (id, timestamp, description) e entries (id, transaction_id, account_id, amount, direction). Invariante a garantir: soma dos débitos = soma dos créditos em cada transaction.

enum Normality { DEBIT, CREDIT }
enum Direction { DEBIT, CREDIT }

// userId é nulo nas contas internas; accountType: "USER_WALLET", "CASH", "REVENUE", "CARD_FEES"
record Account(long id, Long userId, String accountType, Normality normality) {}

record Entry(long id, long transactionId, long accountId, BigDecimal amount, Direction direction) {}

record LedgerTransaction(long id, Instant timestamp, String description, List<Entry> entries) {

    // Invariante: soma dos débitos == soma dos créditos
    boolean isBalanced() {
        return total(Direction.DEBIT).compareTo(total(Direction.CREDIT)) == 0;
    }

    private BigDecimal total(Direction direction) {
        return entries.stream()
            .filter(e -> e.direction() == direction)
            .map(Entry::amount)
            .reduce(BigDecimal.ZERO, BigDecimal::add);
    }
}

O depósito do artigo, montado com esse modelo:

// Contas: 1 = carteira do Art, 2 = taxas de cartão, 3 = caixa
var deposito = new LedgerTransaction(10, Instant.now(), "Depósito com cartão", List.of(
    new Entry(100, 10, 1, new BigDecimal("300.00"), Direction.CREDIT),
    new Entry(101, 10, 2, new BigDecimal("6.00"), Direction.DEBIT),
    new Entry(102, 10, 3, new BigDecimal("294.00"), Direction.DEBIT)));

System.out.println(deposito.isBalanced()); // true

Com várias moedas, a mesma checagem deve ser feita em cada moeda, como mostra a Part V.

Fonte: Accounting for Developers, Part II

10. Part III — um marketplace de empréstimos#

Visão geral: aplica os princípios num marketplace de empréstimos entre pessoas (P2P), com juros, amortização, investidores e tomadores.

Pontos importantes:

Dois tipos de dado: o histórico (o que já aconteceu, baseado em transactions lançadas) fica no ledger; o prospectivo (taxas de juros, prazos, divisão de cada parcela entre juros e principal) fica fora dele, numa tabela de amortização. Separar os dois mantém o ledger limpo.
Plano de contas: caixa (debit normal), receita de juros (credit normal) e duas contas por usuário (principal e juros). As contas do investidor são credit normal (a plataforma deve a ele); as do tomador são debit normal (ele deve à plataforma).
Cinco transactions modeladas: depósito do investidor; desembolso ao tomador; apropriação mensal de juros; pagamento mensal do tomador; pagamento ao investidor no vencimento. Na apropriação de juros, o investidor recebe 4,8% ao ano e o tomador paga 12%: credita $40 por mês nos juros do investidor, debita $50 nos juros do tomador, e a diferença de $10 vai para a receita — o spread da plataforma.
Arquitetura final: um ledger central com as restrições de double-entry, um Transaction Logic Service (converte eventos e webhooks em entries válidas), uma tabela de amortização (calcula as parcelas) e um plano de contas com pelo menos 6 tipos de conta.

Fonte: Accounting for Developers, Part III

11. Arquitetura de plataformas de fidelidade (Open Loyalty)#

Visão geral: a arquitetura de plataformas de pontos e fidelidade — um domínio onde o mesmo padrão de ledger aparece fora do dinheiro. O artigo defende plataformas modulares e API-first, com o ledger de pontos como um dos componentes centrais.

Pontos importantes:

Componentes centrais: motor de regras (avalia as ações do cliente e decide o que disparar), ledger de pontos (cada ponto ganho, resgatado, transferido ou expirado, com trilha de auditoria completa), serviço de entrega das recompensas (fulfillment), camada de API, camada de eventos e mensageria e camada de dados do cliente.
O ledger de pontos é um dos componentes mais exigentes: quando o cliente conclui uma compra, os pontos devem ser creditados exatamente uma vez, mesmo que a requisição seja repetida ou processada duas vezes. Um ledger que erra isso produz erros de saldo difíceis de detectar e caros de corrigir. Plataformas modernas o tratam como serviço independente, e não como um campo no cadastro do cliente.
Idempotência na API é essencial — concessão ou resgate duplicado de pontos é um risco operacional real.
Fluxo ponta a ponta: compra → chamada de API → a camada de eventos roteia para o motor de regras → o motor avalia campanhas e categoria do cliente → o fulfillment gera a recompensa → o ledger é atualizado com registro de auditoria → o evento “recompensa emitida” segue para os outros sistemas. As falhas ficam contidas: se o fulfillment atrasa, a atualização do ledger ainda termina.
Quando essa complexidade não é necessária: num programa simples, no início ou em um único canal, uma plataforma tudo-em-um é mais pragmática. A arquitetura deve seguir as necessidades reais do programa.

Fonte: Loyalty System Architecture

12. Payment Ledger Architecture (Trio) — os 6 fatores#

Visão geral: define um ledger de pagamentos por seis fatores e apresenta a stack em que a maioria dos sistemas em produção converge. É o resumo mais direto e prático do conjunto.

Os 6 fatores:

Double-entry como invariante do banco, não da aplicação: débito, crédito e metadados da mesma entry são gravados numa única transação atômica de banco. Uma CHECK constraint ou uma validação antes do commit confirma que a entry soma zero. Errar isso gera drift de saldo silencioso. Um cuidado prático: no PostgreSQL, uma CHECK constraint só enxerga a linha que está sendo gravada. Se débito e crédito ficam em linhas separadas, a soma precisa ser validada por um constraint trigger adiado para o fim da transação (DEFERRABLE INITIALLY DEFERRED) ou pela aplicação antes do commit.
Derivar saldos das entries, nunca guardar um saldo corrente: uma coluna balance mutável sofre drift com escrita concorrente, falha parcial, correção manual ou migração. Em escala, fazer SUM() a cada leitura fica caro, então crie um saldo materializado: uma visão em cache, otimizada para leitura, recalculada quando novas entries são lançadas — e sempre conferida contra as entries na conciliação.
Journals imutáveis com reversões explícitas (sem UPDATE nem DELETE): o journal é a tabela de lançamentos, e ela precisa ser inalterável para valer em auditorias (SOC 2, PCI DSS, exames de AML/KYC). Reverter = lançar uma nova entry compensatória. O usuário de banco usado pelo posting engine (o serviço que grava os lançamentos) não deve ter permissão de UPDATE ou DELETE nas tabelas de journal.
Modelo de três saldos: ledger balance (liquidado), pending (em trânsito) e available (o que pode ser gasto agora). Juntar os três num só aumenta o risco de o cliente gastar mais do que tem, inclusive valores bloqueados ou ainda em trânsito.
CQRS — separar escrita e leitura: a escrita é fortemente consistente, atômica e durável; a leitura é rápida, via saldo materializado. Quando o saldo alimenta uma decisão financeira, o posting engine valida contra o journal, não contra a visão materializada, que pode estar defasada.
Conciliação como entregável de engenharia, não planilha do financeiro: há a correção interna (entries balanceadas, saldos derivados batendo com o journal) e a externa (o ledger batendo com processadora, bandeira, banco parceiro e câmara de compensação). O caminho é um pipeline automatizado que roda todo dia ou após cada janela de liquidação, compara linha a linha e expõe as divergências com classificação de severidade (diferença de prazo × divergência real), alertas e acompanhamento das exceções. Segundo o artigo, o colapso da Synapse em 2024 foi em grande parte uma falha de conciliação do ledger.

A stack de referência:

No diagrama, o posting engine valida o double-entry, grava as entries atomicamente no journal (PostgreSQL, append-only) e publica o evento JournalEntryPosted no Kafka. O balance materializer consome esses eventos e mantém os três saldos, usando Redis para contas muito movimentadas. O pipeline de conciliação roda em jobs agendados (Airflow, Dagster ou Prefect): lê os arquivos externos — relatórios da processadora, extratos bancários, arquivos da bandeira —, compara cada linha com o journal e grava as divergências numa tabela de exceções, com alertas. Para volumes muito altos, o artigo cita bancos SQL distribuídos como CockroachDB e Google Spanner.

Construir ou comprar: construa se o ledger é diferencial competitivo, se o time já construiu ledgers em produção ou se os requisitos vão além do que um Ledger-as-a-Service (LaaS, ledger oferecido como serviço) suporta. Use LaaS ou open-source (Formance Ledger, Blnk) se o ledger é infraestrutura e o tempo até o mercado importa mais. A maioria começa melhor com LaaS ou open-source e migra para uma solução própria quando a plataforma deixa de atender algum requisito.

Fonte: Payment Ledger Architecture: How Modern Fintechs Design Ledgers

Síntese — o padrão em que os 12 artigos convergem#

Independentemente do domínio — banco digital, carteira, marketplace, programa de pontos —, o desenho final é o mesmo:

Cada movimento é uma entry imutável num ledger append-only, protegida por chave de idempotência para nunca ser lançada duas vezes.
O saldo é um saldo materializado: um cache de leitura rápida, atualizado de forma síncrona quando sustenta autorizações (seção 7) ou de forma assíncrona a partir dos eventos (seção 12) — mas sempre derivado e reconstruível a partir das entries, nunca a fonte da verdade.
A conciliação é um job ou pipeline que soma as entries de cada conta, compara com o saldo materializado, detecta drift, desliga a leitura do cache da conta afetada e alerta — e, havendo sistema externo, confere o ledger também contra ele.
Double-entry vale além do dinheiro. Levando o raciocínio dos artigos para um programa de pontos: ao conceder pontos, credita-se a conta do cliente e debita-se uma conta interna de pontos emitidos. Assim a soma sempre fecha e qualquer drift fica detectável.

Quando um efeito externo (a captura no parceiro, por exemplo) pode dar certo sem que o registro local seja gravado, a conciliação externa ganha um aliado: gravar a intenção antes de agir, tema de Efeito externo sem registro local.

Fontes#

Os 12 artigos resumidos:

Building a Reliable Ledger in an Event-Sourced System Without Big DB Transactions — Medium
How to Scale a Ledger, Part I — Modern Treasury
How to Scale a Ledger, Part II — Modern Treasury
How to Scale a Ledger, Part III — Modern Treasury
How to Scale a Ledger, Part IV — Modern Treasury
How to Scale a Ledger, Part V — Modern Treasury
How to Scale a Ledger, Part VI — Modern Treasury
Accounting for Developers, Part I — Modern Treasury
Accounting for Developers, Part II — Modern Treasury
Accounting for Developers, Part III — Modern Treasury
Loyalty system architecture: How modern platforms are built — Open Loyalty
Payment Ledger Architecture: How Modern Fintechs Design Ledgers — Trio

Documentação usada nos exemplos e observações técnicas:

PostgreSQL — Constraints (CHECK constraint só valida a linha gravada)
PostgreSQL — CREATE TRIGGER (constraint triggers adiados)
PostgreSQL — Error Codes (23505 unique_violation)

SNS MessageAttributes e Filter Policy — filtrando mensagens antes do SQS

Wed, 20 May 2026 00:00:00 GMT

Quando um tópico SNS tem várias filas SQS assinando (o chamado fan-out), cada fila recebe, por padrão, todas as mensagens publicadas no tópico. Se o consumidor só se interessa por um tipo de evento, ele precisa receber, ler e descartar o resto, pagando por isso. A filter policy resolve esse problema: é uma regra em JSON configurada na assinatura que faz o próprio SNS decidir quais mensagens entrega àquela fila. O que não passa no filtro não é enviado à fila.

Neste post: como marcar a mensagem com MessageAttributes no produtor, como escrever e aplicar a filter policy, como o SNS avalia a regra, a diferença entre filtrar por atributo e pelo corpo da mensagem, e os limites e cuidados.

Os termos em uma frase#

Tópico: o canal onde o produtor publica. Assinatura (subscription): o vínculo entre o tópico e um destino, como uma fila SQS.
MessageAttributes: metadados opcionais enviados junto com a mensagem, mas fora do corpo. Cada atributo tem nome, tipo (String, String.Array, Number ou Binary) e valor.
Filter policy: JSON guardado na assinatura que diz quais mensagens ela aceita. Assinatura sem filter policy recebe tudo.

Como funciona na prática#

Ao publicar, o produtor adiciona um atributo que identifica o tipo de evento. Com Spring Cloud AWS, os headers da mensagem viram MessageAttributes do SNS (um header String vira atributo do tipo String), e o convertAndSend do SnsTemplate criado pela autoconfiguração serializa o evento em JSON no corpo:

snsTemplate.convertAndSend(
    topicArn,
    event,                                    // corpo: o evento serializado em JSON
    Map.of("eventType", "OrderCreatedEvent")  // header que vira MessageAttribute no SNS
);

Cuidado com a variante send(topicArn, message): ela não converte o payload e publica o toString() do objeto, então só use com payload já em String.

Sem Spring, o equivalente é preencher MessageAttributes na chamada Publish da API do SNS, com DataType String e StringValue OrderCreatedEvent.

Na assinatura da fila, você configura a filter policy:

{ "eventType": ["OrderCreatedEvent"] }

Ela é gravada no atributo FilterPolicy da assinatura, pelo console, pela CLI, pelos SDKs ou por CloudFormation:

aws sns set-subscription-attributes \
  --subscription-arn arn:aws:sns:... \
  --attribute-name FilterPolicy \
  --attribute-value '{"eventType": ["OrderCreatedEvent"]}'

Resultado: essa fila só recebe mensagens com eventType = OrderCreatedEvent. Os outros tipos publicados no mesmo tópico não são entregues a ela. O filtro vale por assinatura: no diagrama abaixo, cada fila tem o seu, e uma mensagem que não casa com nenhum deles não chega a fila nenhuma.

Chaves diferentes = E (AND): a mensagem precisa satisfazer todas as chaves da policy.
Valores no mesmo array = OU (OR): basta casar com um deles.
Atributo ausente reprova: se a policy exige eventType e a mensagem não tem esse atributo, ela não é entregue (a exceção é "exists": false, que casa justamente com a ausência). Atributos da mensagem que a policy não cita são ignorados.
Comparação de strings diferencia maiúsculas de minúsculas, a menos que você use equals-ignore-case.

Além da igualdade exata, a policy aceita operadores. Os mais úteis:

Operador	Exemplo	Casa quando
`anything-but`	`[{"anything-but": ["OrderShippedEvent"]}]`	o valor não é nenhum dos listados
`prefix` / `suffix`	`[{"prefix": "Order"}]`	o valor começa (ou termina) com o texto
`equals-ignore-case`	`[{"equals-ignore-case": "ordercreatedevent"}]`	igualdade sem diferenciar maiúsculas de minúsculas
`numeric`	`[{"numeric": [">=", 100, "<", 500]}]`	o número está na faixa
`exists`	`[{"exists": true}]`	o atributo está presente (ou ausente, com `false`)
`cidr`	`[{"cidr": "10.0.0.0/24"}]`	o IP pertence à sub-rede
`$or`	`{"$or": [{...}, {...}]}`	uma das condições (entre chaves diferentes) é verdadeira

Um exemplo combinando AND, OR e operadores: aceita pedidos criados ou cancelados, de lojas cujo código começa com loja-, com valor a partir de 100 (publique total como atributo do tipo Number):

{
  "eventType": ["OrderCreatedEvent", "OrderCancelledEvent"],
  "store": [{ "prefix": "loja-" }],
  "total": [{ "numeric": [">=", 100] }]
}

Filtrar por atributo ou pelo corpo#

O atributo FilterPolicyScope da assinatura define onde o SNS procura os campos:

MessageAttributes (padrão): a policy é comparada com os atributos da mensagem. Não aceita policy aninhada, compara só atributos String, String.Array e Number, e ignora atributos Binary.
MessageBody: a policy é comparada com os campos do corpo, que precisa ser um objeto JSON válido. Aceita policy aninhada, espelhando a estrutura do JSON.

Por exemplo, para um corpo {"order": {"status": "CREATED", "total": 250}}, esta policy aninhada aceita a mensagem:

{
  "order": {
    "status": ["CREATED"],
    "total": [{ "numeric": [">=", 100] }]
  }
}

Filtrar pelo corpo é útil quando você não controla o produtor e ele não publica atributos. Mesmo assim, o filtro por atributo continua sendo o caminho padrão por dois motivos: é gratuito, enquanto o filtro pelo corpo é cobrado por GB de payload analisado (contando tanto as mensagens entregues quanto as filtradas), e não acopla a regra ao formato do payload.

Por que isso importa#

Sem filter policy: todas as mensagens do tópico chegam à fila, e o consumidor recebe e descarta o que não é dele.
Com filter policy: só o que interessa chega. São menos requisições ao SQS (que cobra por requisição: envio, recebimento e exclusão contam), menos transferência de dados do SNS para o SQS (cobrada por volume entregue) e menos processamento desperdiçado no consumidor.
O filtro fica na assinatura, não no produtor: o produtor não precisa saber quem consome. É o desacoplamento clássico do pub/sub (publicação e assinatura), só que com entrega seletiva.

MessageAttributes também servem para outras coisas além de filtro, como propagar o ID de rastreamento entre serviços; veja W3C Trace Context.

Limites e cuidados#

Tamanho da policy: no máximo 5 chaves e 150 combinações. As combinações são o produto da quantidade de valores de cada chave: chaves com 3, 1 e 2 valores dão 3 × 1 × 2 = 6. A policy pode ter até 256 KB.
Quantidade de policies: por padrão, até 200 por tópico e 10.000 por conta, ajustáveis pelo Service Quotas.
Mudança não é instantânea: criar ou alterar uma filter policy leva até 15 minutos para valer por completo (consistência eventual). Não conclua que o filtro falhou logo após o deploy.
Raw message delivery: com raw message delivery ligado (a fila recebe a mensagem sem o envelope JSON do SNS), a assinatura SQS aceita no máximo 10 atributos; mensagens com mais que isso são descartadas. Atenção com frameworks: o Spring Cloud AWS também envia como atributos os headers id e timestamp que toda Message do Spring recebe automaticamente.
Um filtro errado descarta mensagens em silêncio: um nome de atributo digitado errado faz a mensagem simplesmente não ser entregue. Monitore a métrica NumberOfNotificationsFilteredOut do CloudWatch (e as variantes -NoMessageAttributes e -InvalidAttributes) para perceber quando o filtro barra mais do que deveria.

Fontes#

AWS — Amazon SNS message filtering
AWS — Amazon SNS subscription filter policies
AWS — Filter policy constraints in Amazon SNS
AWS — AND/OR logic, Key matching, String value matching e Numeric value matching
AWS — Amazon SNS example filter policies
AWS — Applying a subscription filter policy in Amazon SNS
AWS — SetSubscriptionAttributes (FilterPolicyScope)
AWS — Amazon SNS message attributes
AWS — Monitoring Amazon SNS topics using CloudWatch
AWS — Amazon SNS pricing e Amazon SQS pricing
Spring Cloud AWS — Reference: SNS Template, código-fonte de SnsHeaderConverterUtil (headers viram atributos), TopicMessageChannel (publicação) e SnsAutoConfiguration (conversor JSON do SnsTemplate)

W3C Trace Context — correlacionando logs entre microsserviços com o traceparent

Wed, 20 May 2026 00:00:00 GMT

Quando uma operação passa por vários serviços, cada um grava seus próprios logs. Sem um identificador comum, reconstruir o que aconteceu com uma operação vira garimpo: buscar por horário, por ID de cliente, torcer para os relógios baterem. E se cada ferramenta de tracing usa um header próprio, o ID se perde na primeira fronteira entre fornecedores.

O W3C Trace Context resolve isso. É uma recomendação do W3C que padroniza como o contexto de rastreamento (quem é a operação e de onde veio a chamada) é propagado entre serviços, de forma que qualquer ferramenta entenda. O campo central é o traceparent: com o valor dele em mãos, uma única busca na ferramenta de observabilidade mostra tudo o que aconteceu com a operação, do serviço que a originou até o último consumidor.

Este post mostra a anatomia do traceparent e do tracestate, os valores que a especificação considera inválidos, a granularidade certa para jobs em lote e como o ID atravessa um fluxo assíncrono com outbox pattern e SNS.

Trace, span e os IDs do traceparent#

Dois termos antes de começar:

Trace: a operação inteira, com todos os passos em todos os serviços.
Span: um passo dentro do trace (uma requisição recebida, uma consulta, uma publicação de mensagem). Um serviço pode gerar vários spans no mesmo trace.

O traceparent carrega dois IDs que importam para a correlação:

ID	O que é	Exemplo de uso
trace-id	ID da operação inteira, o mesmo em todos os serviços	“me mostre tudo sobre esse lote específico”
parent-id	ID do span de quem fez a chamada (muitas ferramentas chamam de span-id); cada passo gera o seu	saber de qual passo veio a chamada que gerou um log

Além deles, o header traz a versão do formato e as flags de rastreamento.

Anatomia do traceparent#

O valor tem quatro campos separados por hífen, sempre em hexadecimal minúsculo. Este é o exemplo da própria especificação:

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

Campo	Tamanho	Valor no exemplo	O que significa
`version`	2 caracteres (1 byte)	`00`	versão do formato; a atual é `00`
`trace-id`	32 caracteres (16 bytes)	`4bf92f3577b34da6a3ce929d0e0e4736`	ID do trace, igual em todos os serviços
`parent-id`	16 caracteres (8 bytes)	`00f067aa0ba902b7`	ID do span de quem chamou
`trace-flags`	2 caracteres (8 bits)	`01`	flags; hoje só o bit `sampled` é definido

No total são 55 caracteres. A recomendação é enviar o nome do header em minúsculas (traceparent), e quem recebe precisa aceitá-lo em qualquer caixa.

As flags são bits, não um número. O único bit definido é o menos significativo, sampled (amostrado): ligado, indica que quem chamou pode ter gravado os dados do trace; desligado (00), que não gravou. Como é um campo de bits, a leitura correta usa máscara (flags & 0x01), não comparação com 01. Os demais bits são reservados e devem ir zerados.

A cada salto, o serviço repassa o trace-id intacto e normalmente troca o parent-id pelo ID do próprio span. É isso que permite montar a árvore de chamadas: o trace-id agrupa, o parent-id encadeia.

Valores inválidos#

A especificação define quando o traceparent não vale:

Versão ff: proibida.
trace-id só com zeros (00000000000000000000000000000000): inválido.
parent-id só com zeros (0000000000000000): inválido.
Caracteres fora do hexadecimal minúsculo (letras maiúsculas, por exemplo) ou tamanho errado: inválido.

Diante de um valor inválido, o serviço deve ignorar o traceparent recebido: começa um trace novo e descarta o tracestate. Na prática, não gere esses valores à mão. Use a biblioteca de tracing (o OpenTelemetry já usa o W3C Trace Context como propagador padrão). A especificação recomenda que o trace-id seja aleatório e globalmente único, e proíbe usar dados do usuário (como o IP) como semente.

O tracestate#

A especificação define um segundo header, o tracestate, para informações específicas de cada fornecedor de tracing. É uma lista de pares chave=valor separados por vírgula, com no máximo 32 itens:

rojo=00f067aa0ba902b7,congo=t61rcWkgMzE

Ele sempre acompanha o traceparent: um tracestate recebido sem traceparent é descartado, e se o traceparent for inválido o tracestate nem é lido. Para correlacionar logs, o traceparent sozinho basta. O tracestate só importa quando mais de uma ferramenta de tracing participa do mesmo fluxo.

Os dois campos existem apenas para correlação: a especificação proíbe colocar neles dados pessoais ou sensíveis.

Fora do HTTP: o traceparent em mensagens#

A especificação define o formato para headers HTTP. Outros protocolos têm especificações de extensão, e em mensageria o caminho usual é levar o mesmo valor como metadado da mensagem. No SNS, isso é um MessageAttribute (metadado enviado junto com a mensagem, fora do corpo; veja o post sobre SNS MessageAttributes e Filter Policy).

As convenções semânticas de mensageria do OpenTelemetry chamam isso de contexto de criação da mensagem: o produtor cria o contexto e ele deve ser propagado com a mensagem até os consumidores. Sem isso, os traces do consumidor não se ligam diretamente aos do produtor.

Granularidade importa: por lote, não por execução#

Um job que processa 50 lotes poderia usar o mesmo trace-id para todos (um trace por execução do job). Mas isso mistura os logs de todos os lotes: se o lote #47 falhar no consumidor, não dá para isolá-lo. A abordagem recomendada é gerar um trace-id por lote (por evento de outbox). Cada evento gravado na tabela de outbox tem seu próprio traceparent, que viaja com a mensagem até o consumidor.

Para correlacionar todos os lotes de uma mesma execução (“quantos lotes rodaram na execução das 02h?”), use um job-run-id separado no MDC (o contexto de log por thread do SLF4J/Logback), sem misturar com o trace-id do evento. São duas perguntas diferentes, respondidas por dois IDs diferentes. Se a ferramenta for o OpenTelemetry, dá para registrar também essa relação entre traces com span links, que associam um span a um ou mais spans, inclusive de outros traces, indicando relação de causa.

Como o outbox pattern usa na prática#

O outbox pattern grava o evento numa tabela do próprio banco (a tabela outbox), na mesma transação da mudança de estado. Um processo separado, o relay, lê essa tabela e publica os eventos no broker (detalhes no post Efeito externo sem registro local). O traceparent vai junto com o evento em cada etapa:

O job produtor inicia um trace novo por lote e grava o traceparent junto do evento na tabela de outbox.
O relay lê o evento e o traceparent da tabela.
O relay publica no SNS com PublishBatch (até 10 mensagens por chamada), levando o traceparent como MessageAttribute de cada mensagem.
O SNS entrega na fila SQS. O consumidor lê o atributo, continua o mesmo trace e coloca o trace-id e o span-id no MDC. Todos os logs dele saem com esses campos.

Com isso, a ferramenta de observabilidade monta a linha do tempo produtor → mensageria → consumidor com uma busca só pelo trace-id. Para os campos do MDC aparecerem como campos pesquisáveis no log, emita logs estruturados (veja Logging estruturado em Spring Boot). O mesmo trace_id também pode ligar um wide event ao trace distribuído.

Cuidados nesse fluxo:

Raw message delivery: com a entrega bruta desligada (o padrão), a mensagem chega ao SQS dentro do envelope JSON do SNS, e os atributos vêm no campo MessageAttributes desse JSON. Com ela ligada, os atributos chegam como atributos da própria mensagem SQS, mas o limite é de 10: mensagens com mais atributos que isso são descartadas.
Nomes no MDC: o agente Java do OpenTelemetry já injeta trace_id, span_id e trace_flags no MDC do Logback e do Log4j. Se você preencher o MDC à mão, use os mesmos nomes em todos os serviços, ou a busca não junta os logs.

Fontes#

W3C — Trace Context (W3C Recommendation, 23/11/2021)
OpenTelemetry — Context Propagation
OpenTelemetry — Traces: Span Context e Span Links
OpenTelemetry — Semantic conventions for messaging spans
OpenTelemetry Java Instrumentation — Logger MDC auto-instrumentation
AWS — Amazon SNS message attributes
AWS — Amazon SNS raw message delivery
AWS — HTTP/HTTPS notification JSON format
AWS — PublishBatch (Amazon SNS API Reference)

AOP no Spring — JDK Dynamic Proxy, CGLIB e aspects customizados

Tue, 19 May 2026 00:00:00 GMT

Log, transação, cache, segurança e métricas aparecem em quase todo serviço, mas não fazem parte da regra de negócio de nenhum deles. AOP (Aspect-Oriented Programming, ou programação orientada a aspectos) é o paradigma que tira esse código repetido das classes de negócio: você descreve onde aplicar (o pointcut) e o que executar (o advice) numa classe separada, chamada aspect.

No Spring, é AOP que faz @Transactional, @Async e @Cacheable funcionarem. O container troca o bean original por um proxy, um objeto intermediário que intercepta as chamadas e roda o código extra antes e depois de delegar ao objeto real. Esse proxy é gerado de um de dois jeitos: JDK Dynamic Proxy (implementa as interfaces do bean) ou CGLIB (cria uma subclasse do bean).

Neste post: o vocabulário básico, como cada tipo de proxy funciona e quando o Spring usa cada um, por que chamar um método da própria classe ignora o @Transactional (a self-invocation) e como escrever um aspect custom, isto é, um aspect seu, para uma necessidade do seu sistema.

1. O problema que AOP resolve#

Preocupações que se repetem em muitas classes sem pertencer ao domínio delas se chamam cross-cutting concerns (preocupações transversais): log, transação, cache, segurança, métricas, retry, auditoria. Sem AOP, cada método de serviço ganha seu próprio try/finally, sua checagem de permissão e seu cronômetro, e a regra de negócio fica escondida no meio desse ruído.

A ideia central do AOP é modularizar essas preocupações em unidades separadas (os aspects) e aplicá-las de forma declarativa em pontos escolhidos da execução. As classes de negócio ficam limpas, e mudar a política de log ou de métricas passa a exigir alteração em um lugar só.

2. Vocabulário fundamental#

Os termos não foram inventados pelo Spring: são o vocabulário geral de AOP, o mesmo usado pelo AspectJ, e o Spring os adota como são.

Aspect: módulo que encapsula uma preocupação transversal. No Spring, normalmente uma classe anotada com @Aspect. Ex.: LoggingAspect, MetricsAspect, RetryAspect.
Join point: um ponto da execução do programa onde um aspect pode atuar. No Spring AOP, join point é sempre a execução de um método. O AspectJ vai além e cobre também acesso a campo, construção de objeto etc.
Pointcut: o predicado que seleciona quais join points interessam, ou seja, a expressão que diz “onde” aplicar. Ex.: execution(* com.exemplo.servico..*(..)) casa com todos os métodos das classes do pacote com.exemplo.servico e subpacotes. O Spring usa a linguagem de pointcut do AspectJ.
Advice: a ação que o aspect executa num join point, o “o que” rodar (antes, depois ou em volta do método).
Target (objeto alvo): o objeto que recebe os advices. Como o Spring AOP é baseado em proxy, esse objeto fica sempre atrás de um proxy em tempo de execução.
AOP proxy: o objeto criado pelo framework para aplicar os advices ao target. No Spring, é um JDK Dynamic Proxy ou um proxy CGLIB.
Weaving: o processo de “costurar” os aspects no código da aplicação. Pode acontecer na compilação (compilador do AspectJ), no carregamento das classes (load-time weaving) ou em tempo de execução, que é o caso do Spring AOP.
Introduction: declarar métodos ou campos adicionais num tipo. Com ela, um bean passa a implementar uma interface nova, com a implementação fornecida pelo aspect.

3. Tipos de advice#

Cada tipo corresponde a uma anotação usada dentro de uma classe @Aspect:

@Before: roda antes do método alvo. Não consegue impedir a execução, a não ser lançando uma exceção.
@AfterReturning: roda depois, se o método terminou normalmente. Tem acesso ao valor de retorno.
@AfterThrowing: roda quando o método lança exceção. Tem acesso à exceção.
@After: roda sempre depois, com sucesso ou erro (análogo ao finally).
@Around: o mais poderoso, envolve a chamada inteira. Recebe um ProceedingJoinPoint e decide se chama proceed(), que executa o método real. Pode trocar os argumentos, transformar o retorno ou nem chamar o método.

A documentação do Spring recomenda usar o tipo de advice menos poderoso que resolve o caso. Se basta agir depois que o método retorna, @AfterReturning é mais simples que @Around, e não há proceed() para esquecer de chamar (esquecer significa que o método real nunca roda).

4. Como o Spring implementa: proxy em tempo de execução#

O AspectJ completo altera o bytecode das classes (bytecode weaving). O Spring AOP, ao contrário, trabalha com proxies criados em tempo de execução: quando um bean tem advices aplicáveis, o container entrega um proxy no lugar da instância original. O proxy tem o mesmo tipo do bean (implementa as interfaces dele ou estende a classe), intercepta cada chamada, executa os advices e delega para o objeto real.

Consequências desse modelo:

Só chamadas que passam pelo proxy são interceptadas. Acesso a campo e construtor ficam de fora, e método private também (não dá para interceptar o que não pode ser sobrescrito nem chamado de fora).
O que o proxy intercepta depende do tipo dele. Com JDK Dynamic Proxy, só métodos públicos declarados em interface. Com CGLIB, métodos public e protected (e até os de visibilidade de pacote, se necessário). A recomendação oficial, mesmo assim, é que as interações via proxy usem métodos públicos.
Self-invocation não passa pelo proxy (detalhes a seguir).
O Spring AOP é mais simples e mais limitado que o AspectJ completo; em troca, não exige compilador especial nem agente no carregamento das classes.

A pegadinha da self-invocation#

Self-invocation é quando um método de um bean chama outro método do mesmo objeto. A chamada externa entrou pelo proxy e chegou ao objeto real. Dali em diante, this é o objeto real, não o proxy, e qualquer chamada this.outroMetodo() (ou só outroMetodo(), que é a mesma coisa) vai direto, sem advice nenhum.

@Service
public class PedidoService {

    public void importar(List<Pedido> pedidos) {
        for (Pedido p : pedidos) {
            salvar(p);   // o mesmo que this.salvar(p): não passa pelo proxy
        }
    }

    @Transactional
    public void salvar(Pedido p) {
        // chamado por importar(), o @Transactional é ignorado
    }
}

É a pegadinha clássica: o @Transactional está lá, o código compila, não há erro nem aviso, e a transação simplesmente não é aberta. A documentação do Spring lista três saídas, nesta ordem de preferência:

Evitar a self-invocation, refatorando. Por exemplo, mover salvar() para outro bean, que é chamado por PedidoService. É a opção menos invasiva.

Injetar uma referência ao próprio bean (self injection) e chamar o método por ela. A referência injetada é o proxy, então o advice roda. No Spring Boot, referências circulares são proibidas por padrão desde a versão 2.6, e uma autoinjeção comum faz a aplicação falhar na subida com erro de ciclo entre beans. Marcar a dependência com @Lazy resolve:

@Service
public class PedidoService {

    private final PedidoService self;

    public PedidoService(@Lazy PedidoService self) {
        this.self = self;   // referência ao proxy, não ao objeto real
    }

    public void importar(List<Pedido> pedidos) {
        for (Pedido p : pedidos) {
            self.salvar(p);   // passa pelo proxy: a transação é aberta
        }
    }

    @Transactional
    public void salvar(Pedido p) { /* ... */ }
}

AopContext.currentProxy(), que devolve o proxy atual. A documentação desaconselha fortemente: acopla a classe ao Spring AOP e exige configurar o proxy para ser exposto (@EnableAspectJAutoProxy(exposeProxy = true)).

Com weaving do AspectJ (em compilação ou no carregamento das classes) o problema não existe, porque o advice fica dentro do próprio bytecode da classe, e não num proxy.

5. JDK Dynamic Proxy: proxy baseado em interface#

Faz parte do Java desde a versão 1.3 (java.lang.reflect.Proxy + InvocationHandler). Gera, em tempo de execução, uma classe que implementa as interfaces informadas. Toda chamada a um método do proxy é redirecionada para o método invoke(Object proxy, Method method, Object[] args) do handler, que decide o que fazer.

Exemplo em Java puro (sem Spring) de um proxy que loga antes e depois de cada chamada:

import java.lang.reflect.InvocationHandler;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;

public class ProxyPuro {
    public static void main(String[] args) {
        Servico alvo = new ServicoImpl();
        Servico proxy = (Servico) Proxy.newProxyInstance(
                Servico.class.getClassLoader(),
                new Class<?>[] { Servico.class },
                new LogHandler(alvo));

        proxy.executar("x");
        // ANTES de executar
        // executando: x
        // DEPOIS de executar
    }
}

interface Servico {
    void executar(String dado);
}

class ServicoImpl implements Servico {
    public void executar(String dado) {
        System.out.println("executando: " + dado);
    }
}

class LogHandler implements InvocationHandler {
    private final Object alvo;

    LogHandler(Object alvo) { this.alvo = alvo; }

    @Override
    public Object invoke(Object proxy, Method metodo, Object[] args) throws Throwable {
        System.out.println("ANTES de " + metodo.getName());
        try {
            return metodo.invoke(alvo, args);   // delega para o objeto real
        } catch (InvocationTargetException e) {
            throw e.getCause();                 // repassa a exceção original do alvo
        } finally {
            System.out.println("DEPOIS de " + metodo.getName());
        }
    }
}

O arquivo roda direto com java ProxyPuro.java. O catch de InvocationTargetException importa: a reflection embrulha qualquer exceção lançada pelo alvo, e sem desembrulhar quem chama o proxy receberia uma exceção diferente da original.

Características práticas:

Exige que o alvo implemente pelo menos uma interface, e só os métodos declarados nas interfaces passam pelo proxy.
O proxy é do tipo da interface, nunca da classe concreta. No Spring, isso significa que injetar o bean pela classe concreta falha na subida da aplicação: se PedidoServiceImpl implementa PedidoService, o proxy é um PedidoService, mas não um PedidoServiceImpl.
Não precisa de biblioteca externa: é parte do JDK.
No Spring Framework, continua sendo o padrão quando o bean implementa alguma interface.

6. CGLIB: proxy via subclasse#

CGLIB (Code Generation Library) gera bytecode: cria em tempo de execução uma subclasse da classe alvo e sobrescreve os métodos para inserir os advices. O Spring traz o CGLIB reempacotado dentro do spring-core, sem dependência separada.

Não precisa de interface: funciona com qualquer classe concreta.
Não intercepta métodos final (não dá para sobrescrever) e não gera proxy de classes final (não dá para estender). Métodos private também ficam de fora.
O construtor do alvo não é chamado duas vezes: o Spring cria a instância do proxy via Objenesis, uma biblioteca que instancia objetos sem executar construtor.
Pode esbarrar no sistema de módulos do Java: com a aplicação no module path, por exemplo, não dá para gerar proxy CGLIB de uma classe do pacote java.lang.

Quando o Spring usa cada um#

Spring Framework puro: se o bean implementa pelo menos uma interface, usa JDK Dynamic Proxy; se não implementa nenhuma, usa CGLIB. Para forçar CGLIB, use proxyTargetClass = true em @EnableAspectJAutoProxy, @EnableTransactionManagement e anotações parecidas. Essas configurações são unificadas: se uma delas força CGLIB, vale para todas.
Spring Boot: desde a versão 2.0, usa CGLIB por padrão, mesmo quando o bean implementa interface, e isso vale também para @Transactional e os demais recursos baseados em proxy. A propriedade é spring.aop.proxy-target-class, com padrão true. Com o AspectJ no classpath, o Spring Boot também já habilita os aspects sozinho, sem precisar de @EnableAspectJAutoProxy.
Por bean (Spring Framework 7.0+): a anotação @Proxyable num @Bean ou @Component escolhe o tipo de proxy daquele bean (@Proxyable(INTERFACES) ou @Proxyable(TARGET_CLASS)), sobrepondo o padrão global.

Na prática, a diferença aparece em dois casos, os mesmos que a documentação do Spring cita como motivo para forçar CGLIB: quando é preciso aplicar advice num método que não está declarado em interface nenhuma e quando o bean precisa ser usado pelo tipo da classe concreta. Com proxy de subclasse, os dois funcionam; com JDK Dynamic Proxy, o advice fica de fora no primeiro e a injeção falha no segundo.

7. Comparativo rápido#

	JDK Dynamic Proxy	CGLIB
Como funciona	Classe gerada que implementa as interfaces	Subclasse gerada da classe alvo
Exige interface?	Sim	Não
Métodos interceptados	Públicos declarados em interface	`public` e `protected` (e de pacote, se necessário); nunca `final` ou `private`
Classe `final`	Funciona (o proxy não estende a classe)	Não funciona (não dá para estender)
Injetar/converter para	Só a interface	Classe concreta ou interface
Origem	JDK (`java.lang.reflect.Proxy`)	Biblioteca reempacotada no `spring-core`
Padrão no Spring Framework	Quando o bean implementa interface	Quando o bean não implementa interface
Padrão no Spring Boot 2.0+	Só com `spring.aop.proxy-target-class=false`	Sim, com ou sem interface

8. Escrevendo um aspect custom#

Quando você usa @Transactional, @Async ou @Cacheable, está usando recursos prontos do Spring, construídos sobre essa mesma infraestrutura de proxy. Um aspect custom é um aspect que você mesmo escreve para uma preocupação transversal do seu sistema.

Exemplo: medir o tempo de execução de todo método público dos serviços.

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;
import org.springframework.stereotype.Component;

@Aspect
@Component
public class TimingAspect {

    // Pointcut: todos os métodos públicos das classes anotadas
    // com @Service no pacote com.exemplo e subpacotes
    @Pointcut("execution(public * com.exemplo..*(..)) " +
              "&& within(@org.springframework.stereotype.Service *)")
    public void servicos() {}

    @Around("servicos()")
    public Object medir(ProceedingJoinPoint pjp) throws Throwable {
        long inicio = System.nanoTime();
        try {
            return pjp.proceed();  // chama o método real
        } finally {
            long ms = (System.nanoTime() - inicio) / 1_000_000;
            String nome = pjp.getSignature().toShortString();
            System.out.println(nome + " levou " + ms + "ms");
        }
    }
}

Pontos a notar:

@Aspect sozinho não registra o bean; o @Component é o que faz o component scan encontrar a classe.
execution(public * com.exemplo..*(..)) casa com qualquer método público, de qualquer retorno e com quaisquer argumentos, em com.exemplo e subpacotes. within(@...Service *) restringe às classes anotadas com @Service.
Aqui @Around é justificado: é preciso marcar o tempo antes e calcular depois, na mesma execução. Por isso o método retorna Object e devolve o resultado de proceed().

Com isso, todo @Service do pacote passa a ter medição de tempo sem alterar uma linha das classes de negócio. É esse o ganho concreto do AOP. E vale a pegadinha da seção 4: um serviço que chama o próprio método via this não terá essa chamada interna medida.

Dependência necessária no Spring Boot 4:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aspectj</artifactId>
</dependency>

Até o Spring Boot 3.x, o nome do starter era spring-boot-starter-aop; no 4.0 ele foi renomeado para spring-boot-starter-aspectj. O starter traz o aspectjweaver, a biblioteca do AspectJ que fornece as anotações (@Aspect, @Around…) e interpreta as expressões de pointcut. O weaving continua sendo do Spring AOP, em tempo de execução via proxy: nem o compilador nem o weaver do AspectJ entram em ação. O guia de migração sugere revisar se o starter é mesmo necessário: ele só faz falta se a aplicação (ou alguma biblioteca, como o @Timed do Micrometer) usa as anotações do pacote org.aspectj.lang.annotation.

9. Cuidados práticos#

Self-invocation não passa pelo proxy. Se metodoA() chama this.metodoB() na mesma classe, o advice de metodoB() não roda. Prefira separar em outro bean; como alternativa, injete o próprio bean com @Lazy e chame por ele (seção 4).
Métodos private e final nunca recebem advice, e com JDK Dynamic Proxy só os métodos de interface. Deixe as chamadas que precisam de advice em métodos públicos.
bean.getClass() retorna a classe do proxy, não a real (ex.: PedidoService$$SpringCGLIB$$0). Para reflection e leitura de anotações, use AopUtils.getTargetClass(bean), assunto do post AopUtils.getTargetClass(): desembrulhando os proxies do Spring.
Forçar JDK Dynamic Proxy no Spring Boot: spring.aop.proxy-target-class=false. Em geral não compensa: qualquer injeção pela classe concreta passa a falhar na subida.
Desempenho: cada chamada interceptada percorre a cadeia de advices antes de chegar ao método real. Em caminhos muito quentes, meça antes de concluir se o custo importa.

Fontes#

Spring Framework Reference — AOP Concepts
Spring Framework Reference — AOP Proxies
Spring Framework Reference — Proxying Mechanisms (JDK x CGLIB, proxyTargetClass, @Proxyable, self-invocation)
Spring Framework Reference — @AspectJ support
Spring Framework Reference — Declaring a Pointcut (métodos interceptados por tipo de proxy)
Spring Framework Reference — Declaring Advice
Spring Framework Reference — Using @Autowired: Self Injection
Spring Boot Reference — Aspect-Oriented Programming
Spring Boot Reference — Common Application Properties (spring.aop.proxy-target-class)
Spring Boot Wiki — Spring Boot 2.0 Migration Guide (CGLIB como padrão)
Spring Boot Wiki — Spring Boot 2.6 Release Notes (referências circulares proibidas por padrão)
Spring Boot Wiki — Spring Boot 4.0 Migration Guide (renomeação para spring-boot-starter-aspectj)
Java SE 25 API — java.lang.reflect.Proxy
Baeldung — Dynamic Proxies in Java
Baeldung — Introduction to Pointcut Expressions in Spring

AopUtils.getTargetClass() — desembrulhando os proxies do Spring

Tue, 19 May 2026 00:00:00 GMT

No Spring, anotações como @Transactional, @Async, @Cacheable e @PreAuthorize só funcionam porque o container troca o bean original por um proxy: um objeto gerado em tempo de execução que intercepta as chamadas, executa a lógica extra e repassa a chamada ao objeto real (o modelo completo está no post AOP no Spring — JDK Dynamic Proxy, CGLIB e aspects custom). O efeito colateral é que bean.getClass() deixa de retornar a sua classe e passa a retornar a classe do proxy.

Neste post você vai ver por que isso quebra reflection, logs e mapas indexados por classe, como AopUtils.getTargetClass(bean) recupera a classe real e quando é preciso recorrer a AopProxyUtils.ultimateTargetClass().

O que o AOP faz pelo seu código, na prática#

Sem AOP, as preocupações transversais (transação, segurança, métricas, que não fazem parte da regra de negócio) se espalham pelo método. Em um esboço simplificado:

public Pedido criar(Pedido p) {
    long inicio = System.currentTimeMillis();
    tx.begin();
    try {
        if (!user.hasRole("ADMIN")) throw new AccessDenied();
        log.info("criando pedido {}", p);
        var salvo = repo.save(p);
        tx.commit();
        return salvo;
    } catch (Exception e) {
        tx.rollback();
        throw e;
    } finally {
        metrics.record("criar", System.currentTimeMillis() - inicio);
    }
}

Com AOP, o método volta a falar só de negócio:

@Transactional
@PreAuthorize("hasRole('ADMIN')")
@Timed("criar") // Micrometer; exige o TimedAspect registrado
public Pedido criar(Pedido p) {
    log.info("criando pedido {}", p);
    return repo.save(p);
}

Cada anotação é atendida por um interceptor (o advice) que o container aplica ao bean. É exatamente por isso que o objeto injetado não é uma instância da sua classe: é o proxy que executa esses interceptores antes de chamar o seu código.

O problema: `bean.getClass()` devolve a classe do proxy#

O Spring gera o proxy de duas formas:

JDK Dynamic Proxy: uma classe criada pela JVM que implementa as interfaces do bean. É o padrão do Spring Framework quando o bean implementa ao menos uma interface.
CGLIB: uma subclasse da sua classe gerada em tempo de execução. É usada quando o bean não implementa interfaces e é o padrão no Spring Boot (spring.aop.proxy-target-class=true).

Por isso getClass() devolve algo assim:

br.com.exemplo.MeuServico$$SpringCGLIB$$0   // CGLIB: subclasse de MeuServico
jdk.proxy2.$Proxy42                         // JDK: pacote e número variam

Desde o Spring Framework 6.0, o nome das classes CGLIB usa o marcador $$SpringCGLIB$$ seguido de um contador (antes era um hash). No proxy JDK, a especificação só reserva o prefixo $Proxy; o nome do pacote não é especificado.

Isso quebra qualquer código que dependa da identidade da classe real:

Leitura de anotações via reflection. A subclasse CGLIB só enxerga as anotações de classe marcadas com @Inherited (como @Transactional). Anotações sem @Inherited, como uma anotação sua, não aparecem, e as anotações de método também não, porque o proxy sobrescreve os métodos sem copiá-las. O proxy JDK não enxerga nenhuma anotação da classe alvo.
Logging com getClass().getSimpleName(): o log mostra MeuServico$$SpringCGLIB$$0 ou $Proxy42 no lugar de MeuServico.
Mapas do tipo Map<Class<?>, Handler>: handlers.get(bean.getClass()) não encontra a entrada registrada com MeuServico.class.
Código de infraestrutura que descobre metadados pela classe, como um BeanPostProcessor próprio ou um registro de listeners: sofre dos mesmos problemas.

O diagrama resume a diferença: o proxy envolve o objeto real; getClass() para na camada de fora, e getTargetClass() atravessa essa camada e devolve a classe que você escreveu.

O utilitário: `AopUtils.getTargetClass(Object)`#

Fica no pacote org.springframework.aop.support:

public static Class<?> getTargetClass(Object candidate)

Segundo o Javadoc, o método determina a classe alvo de um bean que pode ser um proxy AOP: devolve a classe alvo quando é proxy e a própria classe do objeto nos demais casos, nunca null.

Como ele chega lá (código do Spring Framework 7.0.9):

Se o objeto implementa TargetClassAware, pergunta a ele qual é a classe alvo. Todo proxy Spring AOP implementa essa interface por meio de Advised, a menos que tenha sido criado com a opção opaque.
Se não obteve resposta, usa a superclasse quando o objeto é um proxy CGLIB e getClass() nos demais casos.

Na prática:

Se o bean não é proxy, retorna bean.getClass().
Se é proxy CGLIB ou JDK, retorna a classe do objeto real que o proxy envolve.
Se é um proxy de proxy, desce apenas um nível e retorna a classe do proxy interno (por exemplo, MeuServico$$SpringCGLIB$$0). Para chegar ao fundo, use AopProxyUtils.ultimateTargetClass(), descrito mais abaixo.
Nunca retorna null, garantia da API.

Exemplo prático#

Como MeuServico não implementa interface, o Spring cria um proxy CGLIB por causa do @Transactional. A anotação @Auditavel foi criada sem @Inherited para mostrar a diferença:

import org.springframework.aop.support.AopUtils;
import org.springframework.transaction.annotation.Transactional;
// demais imports omitidos

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Auditavel {} // sem @Inherited

@Service
@Auditavel
public class MeuServico {
    @Transactional
    public void processar() { /* ... */ }
}

@Component
public class Inspetor {
    public void inspecionar(Object bean) throws NoSuchMethodException {
        System.out.println(bean.getClass().getName());
        // br.com.exemplo.MeuServico$$SpringCGLIB$$0

        Class<?> alvo = AopUtils.getTargetClass(bean);
        System.out.println(alvo.getName());
        // br.com.exemplo.MeuServico

        // Anotação de classe sem @Inherited
        bean.getClass().isAnnotationPresent(Auditavel.class); // false
        alvo.isAnnotationPresent(Auditavel.class);            // true

        // Anotação de método
        bean.getClass().getMethod("processar")
                .isAnnotationPresent(Transactional.class);    // false
        alvo.getMethod("processar")
                .isAnnotationPresent(Transactional.class);    // true
    }
}

Use a classe alvo só para ler metadados. Para chamar métodos, continue usando o próprio bean: é o proxy que aplica a transação, o cache e a segurança.

Métodos relacionados#

O próprio AopUtils tem três métodos para descobrir que tipo de objeto você recebeu. Todos verificam também se o objeto implementa SpringProxy, ou seja, respondem true só para proxies criados pelo Spring AOP:

isAopProxy(Object): true se o objeto é um proxy Spring AOP, JDK ou CGLIB.
isCglibProxy(Object): true se é um proxy CGLIB.
isJdkDynamicProxy(Object): true se é um JDK Dynamic Proxy.

Em outras classes utilitárias:

AopProxyUtils.ultimateTargetClass(Object) (pacote org.springframework.aop.framework): desce por qualquer número de proxies aninhados até a classe final. Só atravessa um nível quando consegue fazer isso sem efeitos colaterais, isto é, quando o alvo é um singleton guardado em um SingletonTargetSource (o TargetSource é o componente que entrega ao proxy o objeto real). Com outros TargetSources (lazy, pool, protótipo, hot swap), para naquele nível e devolve a classe informada por ele. Também nunca retorna null.
ClassUtils.getUserClass(Object) (pacote org.springframework.util): devolve a classe original quando a classe do objeto é uma subclasse gerada pelo CGLIB (nome com $$). Não reconhece proxy JDK, que continua como $Proxy42. Tem também a versão getUserClass(Class<?>), útil quando você só tem a classe em mãos.

O diagrama abaixo mostra a diferença em um proxy JDK que envolve um proxy CGLIB:

Resumo do comportamento, conferido no Spring Framework 7.0.9:

Método	Proxy CGLIB	Proxy JDK	Proxy de proxy
`AopUtils.getTargetClass`	classe real	classe real	classe do proxy interno
`AopProxyUtils.ultimateTargetClass`	classe real	classe real	classe real (alvos singleton)
`ClassUtils.getUserClass`	classe real	classe do proxy (`$Proxy…`)	depende do tipo de cada proxy (não use)

Regra prática#

Sempre que for inspecionar um bean Spring por reflection (ler anotações, comparar tipos, registrar em mapa por classe, logar um nome legível), use AopUtils.getTargetClass(bean) em vez de bean.getClass(). Se o bean puder estar envolvido por mais de um proxy, prefira AopProxyUtils.ultimateTargetClass(bean). Não custa nada e evita bugs que só aparecem meses depois, quando alguém adiciona um @Transactional ao serviço e o proxy passa a existir.

Fontes#

Spring Framework Reference — Proxying Mechanisms
Spring Framework Reference — AOP Proxies
Javadoc — AopUtils
Javadoc — AopProxyUtils
Javadoc — ClassUtils
Javadoc — TargetClassAware
Javadoc — Transactional (declarada com @Inherited)
Código-fonte do Spring Framework 7.0.9 — AopUtils.java, AopProxyUtils.java e SpringNamingPolicy.java
Spring Boot — Common Application Properties (spring.aop.proxy-target-class)
Java SE 21 API — java.lang.reflect.Proxy e java.lang.annotation.Inherited
Micrometer — Timers (@Timed e TimedAspect)

AtomicBoolean — o sinalizador thread-safe da parada graciosa

Tue, 19 May 2026 00:00:00 GMT

Por que um boolean comum pode não ser visto por outra thread, quando volatile basta, por que preferir AtomicBoolean e como ligar o SIGTERM a um job sem encerrar a JVM no meio de um lote.

Gradle — quando usar implementation, api, compileOnly e as demais configurações

Tue, 19 May 2026 00:00:00 GMT

Cada configuração de dependência do Gradle alimenta um classpath: compilação, execução, processadores de anotação ou testes. Guia para bibliotecas e starters Spring Boot, com o papel do platform (BOM).

Kubernetes CronJob — concorrência, retries e tempo máximo de execução

Tue, 19 May 2026 00:00:00 GMT

Os campos que protegem rotinas agendadas: concurrencyPolicy, startingDeadlineSeconds, activeDeadlineSeconds, backoffLimit, restartPolicy e timeZone, e o que eles não garantem.

Logging estruturado em Spring Boot — LogstashEncoder vs o suporte nativo do 3.4+

Tue, 19 May 2026 00:00:00 GMT

Cada log como uma linha JSON pesquisável: o caminho clássico com LogstashEncoder e o suporte nativo do Spring Boot 3.4+ (ECS, Logstash e GELF), com saídas reais, comparativo e critério de escolha.

SIGTERM e SIGKILL — o ciclo de término de um pod no Kubernetes

Tue, 19 May 2026 00:00:00 GMT

Como o Kubernetes encerra um pod: SIGTERM, SIGKILL e grace period, a corrida com os endpoints que o preStop resolve, exit codes, o graceful shutdown do Spring Boot e a pegadinha do PID 1.

Wide events e canonical log lines — a evolução do logging estruturado

Tue, 19 May 2026 00:00:00 GMT

Um evento rico em contexto por requisição, no lugar de dezenas de logs parciais: as canonical log lines da Stripe, cardinalidade e Observability 2.0, um filtro em Spring Boot e tail sampling.

Overhead vs overkill — o custo de toda escolha e o exagero dela

Sat, 16 May 2026 00:00:00 GMT

Overhead é o custo extra que toda decisão técnica cobra; overkill é a solução desproporcional ao problema. As seis dimensões do overhead e um critério prático para reconhecer overengineering.

JWT — a estrutura e o significado de cada campo

Sun, 12 Apr 2026 00:00:00 GMT

As três partes de um JWT, campo a campo: headers JOSE (alg, kid…), claims registradas (iss, sub, exp…), algoritmos de assinatura e cuidados de validação. O payload não é criptografado.

Data lake vs data warehouse — e onde entra o lakehouse

Tue, 31 Mar 2026 00:00:00 GMT

Schema-on-write vs schema-on-read, ETL vs ELT, dado curado vs dado bruto: o comparativo direto entre Data Warehouse e Data Lake, por que os dois costumam trabalhar juntos e o que o Lakehouse propõe unificar.

Guia de atualizações do Java

Mon, 14 Jul 2025 00:00:00 GMT

Como planejar a migração entre LTS do Java: ciclo de releases, distribuições e licenças, versões mínimas do ecossistema, processo em cinco fases com rollback, segurança, desempenho, containers e CI.

Java 25 (LTS) — arquivos-fonte compactos, Scoped Values, cache AOT e criptografia pós-quântica

Wed, 02 Jul 2025 02:50:00 GMT

Do Java 22 ao 25, para quem vem do Java 21: arquivos compactos, import module, construtores flexíveis, Scoped Values, cache AOT, headers compactos, criptografia pós-quântica e as 66 JEPs.

Java 21 (LTS) — virtual threads, pattern matching e Sequenced Collections

Wed, 02 Jul 2025 02:10:00 GMT

O que mudou do Java 17 ao Java 21: virtual threads, pattern matching para switch, record patterns, Sequenced Collections, ZGC geracional e as 38 JEPs do Java 18 ao 21, com a versão em que cada recurso chegou.

Java 17 (LTS) — records, sealed classes, text blocks e switch expressions

Wed, 02 Jul 2025 01:30:00 GMT

Do Java 12 ao 17, versão a versão: records, sealed classes, text blocks, switch expressions, pattern matching para instanceof, ZGC e Shenandoah em produção e o que quebra vindo do Java 11.

Java 11 (LTS) — módulos, var, HTTP Client e o novo ciclo de releases

Wed, 02 Jul 2025 00:30:00 GMT

O que chegou do Java 9 ao 11 para quem migra do Java 8: sistema de módulos, var, HttpClient, novas APIs, G1 como padrão, TLS 1.3, a remoção do Java EE e do CORBA e o ciclo de releases a cada seis meses.

Java 8 (LTS) — lambdas, Stream API, java.time e o fim do PermGen

Wed, 02 Jul 2025 00:00:00 GMT

O que mudou do Java 7 para o Java 8: lambdas, Stream, Optional, java.time, CompletableFuture e Metaspace no lugar do PermGen, com exemplos antes e depois e a lista completa das 55 JEPs.