Cesar Schutz

Filtros de serialização no Jackson — mascarando número de cartão nos logs

Fri, 25 Sep 2026 00:00:00 GMT

Logar o payload de uma requisição ou de um evento é uma das formas mais práticas de investigar problemas. Num sistema de cartões, o risco é óbvio: o JSON que vai pro log carrega número do cartão, CVV, CPF. Ao mesmo tempo, a resposta da API precisa continuar trazendo esses dados completos.

O Jackson resolve isso com filtros de serialização, um mecanismo que deixa você decidir, campo a campo, o que é escrito no JSON, sem alterar as classes e sem mexer no mapper usado pela API.

1. As três peças

Um filtro envolve três coisas, e vale entender cada uma antes do código.

@JsonFilter("id") é uma etiqueta colocada na classe. Ela diz ao Jackson: “quando for serializar esta classe, passe cada campo pelo filtro chamado id”. A anotação não diz qual é o filtro, só o nome dele.

PropertyFilter é o filtro em si, a regra. O Jackson chama o filtro uma vez para cada propriedade do objeto, e o filtro decide o que fazer: escrever normalmente, omitir, ou escrever outra coisa no lugar. Na prática você estende SimpleBeanPropertyFilter, que já traz o comportamento padrão.

FilterProvider é o registro, configurado no mapper, que liga o nome ao filtro. A implementação padrão é SimpleFilterProvider, usada com addFilter("id", filtro).

A consequência dessa separação é que a mesma classe pode ser serializada com filtros diferentes, dependendo do mapper que está sendo usado.

2. Primeiro exemplo: removendo o CVV

O caso mais simples usa um filtro pronto do Jackson:

import com.fasterxml.jackson.annotation.JsonFilter;

@JsonFilter("cartaoFilter")
public record Cartao(String titular, String numero, String cvv) {}

import tools.jackson.databind.json.JsonMapper;
import tools.jackson.databind.ser.std.SimpleBeanPropertyFilter;
import tools.jackson.databind.ser.std.SimpleFilterProvider;

JsonMapper mapper = JsonMapper.builder()
        .filterProvider(new SimpleFilterProvider()
                .addFilter("cartaoFilter", SimpleBeanPropertyFilter.serializeAllExcept("cvv")))
        .build();

mapper.writeValueAsString(new Cartao("Cesar", "5502091234567890", "123"));

Saída:

{"titular":"Cesar","numero":"5502091234567890"}

O SimpleBeanPropertyFilter tem quatro filtros prontos: serializeAll() não filtra nada, serializeAllExcept(...) escreve tudo menos os campos listados, filterOutAllExcept(...) escreve só os campos listados e filterOutAll() não escreve nenhum.

Também dá para passar o provider só na hora de escrever, sem configurá-lo no mapper: mapper.writer(filterProvider).writeValueAsString(objeto).

O efeito colateral de anotar a classe

Com @JsonFilter na classe, todo mapper que serializar essa classe precisa conhecer o filtro. Um mapper sem provider falha:

tools.jackson.databind.exc.InvalidDefinitionException:
Cannot resolve PropertyFilter with id 'cartaoFilter'; no FilterProvider configured

Ou seja, se o mapper da API não tiver o filtro registrado, a anotação quebra a API. Guarde isso: é o motivo de existir o mixin da seção 4.

3. Mascarando o número do cartão

Remover campo é fácil com os filtros prontos. Para mascarar, você escreve um filtro próprio e sobrescreve serializeAsProperty, o método que o Jackson chama para cada propriedade:

import java.util.Set;
import tools.jackson.core.JsonGenerator;
import tools.jackson.databind.SerializationContext;
import tools.jackson.databind.ser.BeanPropertyWriter;
import tools.jackson.databind.ser.PropertyWriter;
import tools.jackson.databind.ser.jdk.MapProperty;
import tools.jackson.databind.ser.std.SimpleBeanPropertyFilter;

public class MascaraCartaoFilter extends SimpleBeanPropertyFilter {

    private static final Set<String> CAMPOS_MASCARADOS = Set.of("numero", "numeroCartao", "pan");
    private static final Set<String> CAMPOS_REMOVIDOS = Set.of("cvv", "senha");

    @Override
    public void serializeAsProperty(Object pojo, JsonGenerator g, SerializationContext ctxt,
                                    PropertyWriter writer) throws Exception {
        String nome = writer.getName();

        // 1. Campo proibido: não escreve nada
        if (CAMPOS_REMOVIDOS.contains(nome)) {
            writer.serializeAsOmittedProperty(pojo, g, ctxt);
            return;
        }

        // 2. Campo sensível: escreve a versão mascarada
        if (CAMPOS_MASCARADOS.contains(nome)) {
            Object valor = valorDe(pojo, writer);
            if (valor != null) {
                g.writeStringProperty(nome, mascarar(valor.toString()));
                return;
            }
        }

        // 3. Qualquer outro campo: segue o fluxo normal
        writer.serializeAsProperty(pojo, g, ctxt);
    }

    private static Object valorDe(Object pojo, PropertyWriter writer) throws Exception {
        if (writer instanceof BeanPropertyWriter propriedade) {
            return propriedade.get(pojo);          // campo de um objeto/record
        }
        if (writer instanceof MapProperty entrada) {
            return entrada.getValue();             // entrada de um Map
        }
        return null;
    }

    static String mascarar(String numero) {
        String digitos = numero.replaceAll("\\D", "");
        if (digitos.length() < 12) {
            return "*".repeat(digitos.length());
        }
        return digitos.substring(0, 6)
                + "*".repeat(digitos.length() - 10)
                + digitos.substring(digitos.length() - 4);
    }
}

Diagrama: um Cartao com titular, numero e cvv passa pelo MascaraCartaoFilter, uma propriedade por vez. O cvv é omitido, o numero sai mascarado como 550209******7890 e o titular segue o fluxo normal para o JSON do log. O diagrama, passo a passo, está no site.

O writer representa a propriedade que está sendo escrita, e writer.getName() é o nome dela no JSON. A partir daí, o filtro segue um de três caminhos.

Para remover, chama serializeAsOmittedProperty, que é o mesmo que os filtros prontos fazem. Em JSON, isso simplesmente não escreve nada.

Para mascarar, lê o valor original e, em vez de delegar ao writer, escreve ele mesmo o par nome/valor com g.writeStringProperty(...).

Para qualquer outro campo, chama writer.serializeAsProperty(...), o fluxo normal.

O método valorDe trata dois tipos de writer: BeanPropertyWriter para campos de objetos e records, e MapProperty para entradas de um Map (o filtro também é aplicado a mapas, como aparece na seção 4). A função mascarar remove espaços e hífens, mantém os 6 primeiros e os 4 últimos dígitos e, se o valor for curto demais para ser um número de cartão, mascara tudo.

O registro é o mesmo de antes, usando o Cartao anotado com @JsonFilter("cartaoFilter"):

JsonMapper mapper = JsonMapper.builder()
        .filterProvider(new SimpleFilterProvider()
                .addFilter("cartaoFilter", new MascaraCartaoFilter()))
        .build();

mapper.writeValueAsString(new Cartao("Cesar", "5502 0912 3456 7890", "123"));

Saída:

{"titular":"Cesar","numero":"550209******7890"}

Se o número vier null, o filtro não inventa nada e segue o fluxo normal: {"titular":"Cesar","numero":null}.

4. Aplicando em todas as classes com mixin

Anotar cada DTO com @JsonFilter tem dois problemas: é fácil esquecer uma classe e, como vimos, a anotação obriga todo mapper a conhecer o filtro.

O mixin resolve os dois. Mixin é o recurso do Jackson para “colar” anotações numa classe sem alterar o código dela. Você cria uma classe auxiliar só com as anotações e registra no mapper com addMixIn(alvo, classeComAsAnotacoes). Aquele mapper passa a tratar o alvo como se tivesse aquelas anotações; os outros mappers não enxergam nada.

O truque é usar Object.class como alvo. Toda classe herda de Object, e o Jackson considera os mixins de Object ao ler as anotações de qualquer classe. Resultado: toda classe ganha o @JsonFilter, mas só dentro deste mapper.

import com.fasterxml.jackson.annotation.JsonFilter;

@JsonFilter("logFilter")
public abstract class LogFilterMixin {
}

JsonMapper logMapper = JsonMapper.builder()
        .addMixIn(Object.class, LogFilterMixin.class)
        .filterProvider(new SimpleFilterProvider()
                .addFilter("logFilter", new MascaraCartaoFilter()))
        .build();

Agora as classes de domínio não precisam de nenhuma anotação do Jackson:

public record Cartao(String titular, String numero, String cvv) {}
public record Cliente(String nome, String cpf) {}
public record Pedido(Long id, Cliente cliente, Cartao cartao,
                     List<Cartao> adicionais, Map<String, Object> extras) {}

O mesmo pedido serializado pelos dois mappers:

// mapper normal (API)
{"id":10,"cliente":{"nome":"Cesar","cpf":"123.456.789-00"},
 "cartao":{"titular":"Cesar","numero":"5502091234567890","cvv":"123"},
 "adicionais":[{"titular":"Maria","numero":"4000123412341234","cvv":"999"}],
 "extras":{"numero":"4111111111111111"}}

// logMapper
{"id":10,"cliente":{"nome":"Cesar","cpf":"123.456.789-00"},
 "cartao":{"titular":"Cesar","numero":"550209******7890"},
 "adicionais":[{"titular":"Maria","numero":"400012******1234"}],
 "extras":{"numero":"411111******1111"}}

O filtro alcançou o objeto aninhado, os itens da lista e a entrada do Map. O mapper normal continuou escrevendo tudo.

5. Juntando tudo no Spring

Na aplicação, isso vira dois beans: o mapper padrão, marcado como @Primary, e o mapper de log.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import tools.jackson.databind.DeserializationFeature;
import tools.jackson.databind.cfg.DateTimeFeature;
import tools.jackson.databind.json.JsonMapper;
import tools.jackson.databind.ser.std.SimpleFilterProvider;

@Configuration
public class JacksonConfig {

    @Bean
    @Primary
    public JsonMapper objectMapper() {
        return baseBuilder().build();
    }

    @Bean
    public JsonMapper logMapper() {
        return baseBuilder()
                .addMixIn(Object.class, LogFilterMixin.class)
                .filterProvider(new SimpleFilterProvider()
                        .addFilter("logFilter", new MascaraCartaoFilter()))
                .build();
    }

    private JsonMapper.Builder baseBuilder() {
        return JsonMapper.builder()
                .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
                .disable(DateTimeFeature.WRITE_DATES_AS_TIMESTAMPS);
    }
}

O @Primary é o que o Spring injeta quando ninguém especifica qual mapper quer, então é ele que serializa as requisições e respostas HTTP. O logMapper só é usado onde for pedido pelo nome (o nome do bean é o nome do método). O baseBuilder() evita repetir a configuração comum nos dois.

Não pule o mapper @Primary: o Spring Boot só cria o mapper padrão dele quando a aplicação não declara nenhum bean desse tipo. Se você declarar apenas o logMapper, ele vira o único mapper da aplicação e passa a ser usado também nas respostas da API, que começam a devolver cartão mascarado.

Um detalhe do baseBuilder(): como ele parte de JsonMapper.builder(), as propriedades spring.jackson.* do application.yml não valem para nenhum dos dois mappers (declarar um JsonMapper próprio desliga toda a configuração automática do mapper). Se a aplicação depende delas, receba o JsonMapper.Builder que o Spring Boot oferece. Ele já vem com as spring.jackson.* aplicadas e é criado de novo a cada injeção, então o mixin do logMapper não vaza para o mapper da API:

@Bean
@Primary
public JsonMapper objectMapper(JsonMapper.Builder builder) {
    return builder.build();
}

@Bean
public JsonMapper logMapper(JsonMapper.Builder builder) {
    return builder
            .addMixIn(Object.class, LogFilterMixin.class)
            .filterProvider(new SimpleFilterProvider()
                    .addFilter("logFilter", new MascaraCartaoFilter()))
            .build();
}

Para usar o mapper de log, vale centralizar num componente:

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Component;
import tools.jackson.core.JacksonException;
import tools.jackson.databind.json.JsonMapper;

@Component
public class LogJson {

    private final JsonMapper logMapper;

    public LogJson(@Qualifier("logMapper") JsonMapper logMapper) {
        this.logMapper = logMapper;
    }

    public String toJson(Object objeto) {
        try {
            return logMapper.writeValueAsString(objeto);
        } catch (JacksonException e) {
            // nunca cair no toString() aqui: ele não passa pelo filtro
            return "<falha ao serializar " + objeto.getClass().getSimpleName() + ">";
        }
    }
}

E no código:

log.info("Pedido recebido: {}", logJson.toJson(pedido));

6. Variação: marcar os campos com uma anotação própria

Filtrar pelo nome do campo tem um ponto fraco: numero é um nome genérico. O número da conta ou o número do endereço também seriam mascarados, e um campo de cartão com outro nome (cartaoVinculado, por exemplo) escaparia.

Uma alternativa é criar uma anotação sua (não do Jackson) e fazer o filtro procurar por ela:

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

@Retention(RetentionPolicy.RUNTIME)
public @interface NumeroCartao {
}

public class MascaraPorAnotacaoFilter extends SimpleBeanPropertyFilter {

    @Override
    public void serializeAsProperty(Object pojo, JsonGenerator g, SerializationContext ctxt,
                                    PropertyWriter writer) throws Exception {
        if (writer.getAnnotation(NumeroCartao.class) != null
                && writer instanceof BeanPropertyWriter propriedade) {
            Object valor = propriedade.get(pojo);
            if (valor != null) {
                g.writeStringProperty(writer.getName(), MascaraCartaoFilter.mascarar(valor.toString()));
                return;
            }
        }
        writer.serializeAsProperty(pojo, g, ctxt);
    }
}

public record Cartao(String titular, @NumeroCartao String numero) {}

public class Conta {
    @NumeroCartao
    private String cartaoVinculado;
    private String numero;          // número da conta: não deve ser mascarado
    // getters...
}

Saída de uma Conta pelo mapper de log:

{"cartaoVinculado":"550209******7890","numero":"12345-6"}

A troca é que agora os DTOs precisam da anotação. A diferença para o @JsonFilter é que uma anotação própria não quebra os outros mappers, porque eles simplesmente a ignoram. Também dá para combinar as duas abordagens (lista de nomes e anotação) no mesmo filtro. Só lembre que entradas de Map não têm anotação, então essa variação vale apenas para campos de objetos e records.

7. Cuidados

O filtro só age quando o objeto passa pelo mapper. Um log.info("{}", pedido) usa o toString(), e o toString() de um record (ou de uma classe com @Data/@ToString do Lombok) imprime tudo:

Cartao[titular=Cesar, numero=5502091234567890, cvv=123]

Por isso a regra é logar sempre via logJson.toJson(...).

O que passa pelo filtro e o que não passa. Com o mixin em Object, passam objetos, records, objetos aninhados, itens de listas e entradas de Map (a chave vira o nome da propriedade). Uma String solta não passa, inclusive uma String que já contém JSON: logJson.toJson("5502091234567890") sai inteiro. Se o sistema loga o corpo cru da requisição como texto, o filtro não protege.

Classes com @JsonFilter próprio. Uma anotação diretamente na classe tem prioridade sobre o mixin de Object. Se alguma classe tiver @JsonFilter("outroId"), o logMapper falha com No filter configured with id 'outroId'. A solução é registrar esse id também no provider ou definir um filtro padrão com new SimpleFilterProvider().setDefaultFilter(filtro), que é usado para qualquer id sem registro.

O filtro é compartilhado entre threads. Uma única instância atende todas as serializações do mapper. Mantenha o filtro sem estado mutável, como no exemplo (conjuntos imutáveis e métodos que só dependem dos parâmetros).

Só serialização. Filtros não afetam a leitura de JSON. O logMapper desserializa normalmente.

O tipo muda. O campo mascarado sempre sai como string no JSON, mesmo que o original seja numérico.

CVV não se mascara, se remove. CVV não deve aparecer em log nenhum, nem parcialmente. Por isso o exemplo remove o campo em vez de mascará-lo. O PCI DSS proíbe guardar o código de verificação do cartão depois da autorização, mesmo cifrado, e um log é um lugar onde ele fica guardado.

Quantos dígitos mostrar. O PCI DSS (requisito 3.4.1) limita o número exibido a, no máximo, o BIN e os 4 últimos dígitos. Como o BIN tem de 6 a 8 dígitos, os 6 primeiros e os 4 últimos do mascarar ficam dentro desse limite.

8. Jackson 2 x Jackson 3

A ideia é a mesma nas duas versões; mudam pacotes e nomes de métodos.

	Jackson 3	Jackson 2
Pacote base	`tools.jackson.databind`	`com.fasterxml.jackson.databind`
`@JsonFilter`	`com.fasterxml.jackson.annotation`	`com.fasterxml.jackson.annotation` (igual)
`SimpleBeanPropertyFilter` e `SimpleFilterProvider`	`...databind.ser.std`	`...databind.ser.impl`
`MapProperty`	`...databind.ser.jdk`	`...databind.ser.std`
Método do filtro	`serializeAsProperty(Object, JsonGenerator, SerializationContext, PropertyWriter)`	`serializeAsField(Object, JsonGenerator, SerializerProvider, PropertyWriter)`
Omitir campo	`writer.serializeAsOmittedProperty(...)`	`writer.serializeAsOmittedField(...)`
Delegar ao fluxo normal	`writer.serializeAsProperty(...)`	`writer.serializeAsField(...)`
Escrever o campo mascarado	`g.writeStringProperty(nome, valor)`	`gen.writeStringField(nome, valor)`
Registrar o provider	`JsonMapper.builder().filterProvider(...)`	`builder().filterProvider(...)` ou `mapper.setFilterProvider(...)`
Datas como ISO	`DateTimeFeature.WRITE_DATES_AS_TIMESTAMPS`	`SerializationFeature.WRITE_DATES_AS_TIMESTAMPS`
Exceção de `writeValueAsString`	`JacksonException` (unchecked)	`JsonProcessingException` (checked)

addMixIn, BeanPropertyWriter, PropertyWriter e o resto do fluxo funcionam da mesma forma.

Resumo

@JsonFilter dá um nome de filtro a uma classe, o FilterProvider diz qual regra responde por esse nome, e o PropertyFilter decide campo a campo o que escrever. Para mascarar, o filtro lê o valor e escreve a versão mascarada no lugar. Com um mixin em Object.class, o filtro vale para todas as classes, mas só no mapper de log, e o mapper @Primary continua servindo a API com os dados completos.

Fontes

Jackson — Migrating to Jackson 3 (pacote tools.jackson, SerializationContext, métodos “field” que viraram “property”, JacksonException e DateTimeFeature)
Jackson API — @JsonFilter, PropertyFilter e SimpleBeanPropertyFilter (Jackson 3.2.3)
Jackson Wiki — Mix-in Annotations
Spring Boot Reference — Customize the Jackson JsonMapper (o JsonMapper próprio com @Primary, o JsonMapper.Builder e as propriedades spring.jackson.*)
PCI SSC — FAQ 1492: mascaramento e truncamento do PAN com BIN de 8 dígitos (requisito 3.4.1: no máximo o BIN e os 4 últimos dígitos)
PCI SSC — FAQ: o código de verificação pode ser guardado para cartão salvo ou cobrança recorrente? (não pode ser guardado depois da autorização, nem cifrado)

CronJob ou endpoint + fila — onde rodar o batch de uma API Spring Boot no Kubernetes

Wed, 23 Sep 2026 00:00:00 GMT

Um cenário comum: um microsserviço Spring Boot roda no Kubernetes como API e passa a precisar de uma rotina periódica, por exemplo ler uma lista de registros do banco, aplicar validações e publicar parte deles num tópico SNS. A lógica de negócio já está no serviço, então a pergunta não é se o código será reaproveitado, e sim onde essa rotina vai rodar.

Duas abordagens aparecem com frequência. Ambas funcionam e reaproveitam o código, mas com trade-offs diferentes. Neste post, comparo as duas critério por critério, incluindo onde cada uma leva vantagem, e explico por que, para esse tipo de carga, a balança pende para a primeira.

Versões. Os exemplos de código foram testados com Spring Boot 4.1.1 (que traz o Spring Batch 6.0.5), Java 21 e PostgreSQL 16, e o CronJob foi validado contra o schema da API do Kubernetes 1.37. Onde o Spring Boot 4 mudou o comportamento em relação ao 3.x, o texto avisa.

As duas abordagens

A — CronJob com a mesma imagem e outro perfil do Spring

A API continua no Deployment de sempre. No horário agendado, o CronJob cria um Job, que sobe um pod com a mesma imagem da API e o perfil batch: sem servidor web, esse pod executa o job com Spring Batch e termina. O exit code informa ao Kubernetes se deu certo.

B — CronJob chama um endpoint que enfileira uma mensagem no SQS, e a própria API a consome

No horário agendado, o CronJob chama um endpoint da API com curl. O endpoint publica uma única mensagem numa fila SQS, um pedido para processar os pendentes, e responde 202 Accepted, sem consultar o banco. Um dos pods da API consome essa mensagem (por exemplo, com o @SqsListener do Spring Cloud AWS): lê os registros pendentes no banco e processa um a um, publicando no SNS e marcando o status de cada registro. Se der erro, a mensagem não é apagada e volta a ficar visível na fila (ela nunca sai de lá; só fica invisível enquanto é processada), e a nova tentativa segue de onde a anterior parou, porque o banco diz o que já foi enviado. Depois de N tentativas, a mensagem vai para a DLQ (dead-letter queue, a fila das mensagens que falharam).

A abordagem B não é um antipadrão. Entre os exemplos de gatilho agendado para processamento em segundo plano, a Microsoft cita exatamente esse desenho: um timer em outra aplicação envia periodicamente uma requisição a uma API, e a API dispara a tarefa (Microsoft — Best practices for background jobs). A discussão aqui é de trade-off.

O padrão por trás da abordagem A

Rodar a mesma base de código como tipos diferentes de processo é um princípio do Twelve-Factor App (fator VIII, Concurrency): o processo web atende HTTP, e o worker executa tarefas longas em segundo plano.

Chris Jones, da AWS Professional Services, descreve uma evolução em três passos em Rethinking Java @Scheduled Tasks in Kubernetes (The New Stack, 2023): primeiro o @Scheduled dentro da API, depois um CronJob que chama um endpoint via curl e, por fim, um CronJob que roda a mesma imagem da API com um ponto de entrada alternativo. Ele detalha o padrão no AWS Open Source Blog, em Alternative JAR Entry Points Using Java Dependency Injection Frameworks, com um código de exemplo em que o main escolhe o ponto de entrada por uma variável de ambiente própria (ALTERNATIVE_ENTRY_POINT). No Spring Boot, um caminho comum para o mesmo efeito é um perfil (Spring Boot — Profiles): o perfil batch troca beans e configuração e é ativado no CronJob pela variável SPRING_PROFILES_ACTIVE, como mostra a seção Como montar a abordagem A.

Uma alternativa frequente ao primeiro passo, @Scheduled com ShedLock, só impede que duas réplicas rodem a tarefa ao mesmo tempo. O processamento continua dentro da API, com os problemas dos critérios 1 a 4 e sem os ganhos da fila.

Mahmoud Ben Hassine, líder do projeto Spring Batch, mostra como rodar jobs do Spring Batch como Jobs do Kubernetes em Spring Batch on Kubernetes: Efficient batch processing at scale (Spring blog, 2021). O texto é da época do Spring Batch 4; o que mudou desde então aparece ao longo deste post.

Critério a critério

1. Disputa de recursos com quem atende o usuário

Na abordagem B, o lote roda dentro de um pod da API, o que recebeu a mensagem, e esse pod continua atendendo a sua parte das requisições. O batch e as requisições HTTP passam a dividir o mesmo processo:

Pool de conexões. O HikariCP, pool que o Spring Boot usa por padrão, abre no máximo 10 conexões, e o lote usa esse mesmo pool. Processando em série, ele ocupa uma conexão por vez; se o consumidor dividir o lote entre várias threads para terminar antes, ocupa várias, e as requisições da API esperam por uma conexão livre até estourar o timeout (30 s por padrão).
CPU. O limite de CPU do container é um só: o que o batch consome, as requisições que caem nesse pod perdem em latência.
Heap. O heap é a área de memória da JVM onde vivem os objetos. Processar grandes volumes aumenta o trabalho do garbage collector, e as pausas dele atingem a aplicação inteira. No limite, a JVM lança OutOfMemoryError, ou o container passa do limite de memória e é morto pelo kernel (OOMKilled), levando junto as requisições em andamento.

Isolar recursos por tipo de carga, para que uma não esgote a outra, é o padrão Bulkhead, popularizado por Michael Nygard em Release It! e documentado pela Microsoft (Bulkhead pattern). Martin Kleppmann ajuda a entender por que as duas cargas não combinam: em serviços online, a principal medida de desempenho é o tempo de resposta, e a disponibilidade costuma ser crítica; em sistemas batch, é o throughput (Designing Data-Intensive Applications, 1ª ed., cap. 10). O Borg, gerenciador de clusters do Google e antecessor do Kubernetes, trata serviços de longa duração e jobs batch como classes distintas de carga, com prioridades diferentes (Verma et al., EuroSys 2015).

Na abordagem A, o job roda num pod separado, com seus próprios requests e limites de CPU e memória e seu pool de conexões.

Ressalva: o banco continua compartilhado. O pod separado isola o processo, não o banco. Por isso, o job deve ter um pool pequeno (mas não menor que o número de threads do step) e chunks, a quantidade de itens gravados por transação, bem dimensionados.

2. Deploy da API no meio do processamento

Na abordagem B, um deploy da API feito durante a janela do batch acontece no meio do processamento. No rolling update, cada pod antigo recebe SIGTERM e tem o grace period (30 segundos por padrão) para encerrar antes do SIGKILL (Kubernetes — término de pods; o ciclo completo está em SIGTERM e SIGKILL). O graceful shutdown do Spring Boot cuida das requisições HTTP (Spring Boot — Graceful shutdown); o listener da fila tem prazo próprio. Quando chega a vez do pod que está com a mensagem do lote:

o listener para de buscar mensagens e espera a que está em andamento, no Spring Cloud AWS até 20 s por padrão (listenerShutdownTimeout). Um lote de minutos não termina nesse prazo, e o processamento é cancelado;
como não foi concluída, a mensagem não foi apagada da fila: reaparece depois do visibility timeout (o prazo em que a mensagem recebida fica invisível para os outros consumidores), e um pod da versão nova a recebe e segue de onde o anterior parou, pelo status no banco. Se o registro que estava em andamento já tinha sido publicado no SNS, mas ainda não tinha sido marcado, ele é enviado de novo;
o lote termina em duas versões do código: parte processada pela antiga, parte pela nova.

Como a mensagem é uma só, o deploy não põe em risco só o registro em andamento: o lote inteiro para, e a retomada espera o visibility timeout expirar. Se ele foi dimensionado para cobrir o lote (critério 6), a espera pode ser longa: no exemplo, um deploy às 03:30 deixa o lote parado até as 05:00. Aumentar o grace period não resolve: ele é só um teto, não muda o prazo do listener e teria de cobrir o lote inteiro. O resultado costuma ser o time evitando deploy na janela do batch.

Na abordagem A, o deploy da API não toca no pod do job. Nem mesmo uma atualização do CronJob afeta o que já está rodando: as mudanças valem só para os Jobs criados depois, e os que já começaram seguem sem alteração (Kubernetes — CronJob). O job de hoje termina com a versão com que começou, e a nova versão entra na próxima execução. Isso vale para o código, não para o banco: se a versão nova da API roda migrações, elas precisam ser compatíveis com o job que ainda está rodando (expand/contract), a mesma disciplina que o próprio rolling update já exige.

3. Recurso reservado o dia inteiro

No Kubernetes, cada container declara quanto de memória e CPU reserva no cluster (os requests). Desde a versão 1.35 (estável; em beta desde a 1.33), dá para redimensionar um pod em execução (Kubernetes — Resizing Pods), mas nada no Kubernetes faz isso sozinho só nos minutos em que o batch roda. E, numa JVM, memória a mais sem reiniciar o container não aumenta o heap, porque o tamanho máximo dele é fixado quando a JVM sobe. O Vertical Pod Autoscaler, instalado à parte, também não resolve: para memória, ele considera o pico de cada período de 24 horas, então recomendaria reservar o pico do batch o dia inteiro.

Na abordagem B, cada réplica da API precisa de folga para o pico do batch, 24 horas por dia: qualquer uma pode receber a mensagem e rodar o lote inteiro (critério 6). Essa folga precisa estar no request: memória não se comprime, e, quando falta memória no nó, os pods que passam do próprio request tendem a ser os primeiros despejados (Kubernetes — requests e limits). Um exemplo com números hipotéticos: a API precisa de 512 MB, e o lote, de mais 1 GB. Como qualquer réplica pode recebê-lo, cada uma reserva 1,5 GB, e, com três réplicas, são 4,5 GB reservados o tempo todo. Na abordagem A, são 1,5 GB para a API e 1 GB para o pod do job, só enquanto ele roda: terminado o Job, o pod fica como Completed e deixa de reservar CPU e memória. Ele pode continuar existindo como registro, para consulta de logs, até ser removido pelo limite de histórico do CronJob (Kubernetes — Jobs). O paper do Borg registra o mesmo desperdício do lado dos serviços: jobs de produção costumam reservar recurso para picos raros e não usá-lo na maior parte do tempo.

Sobre a fatura: o SQS custa pouco, e o nível gratuito inclui 1 milhão de requisições por mês, somadas todas as filas da conta (Amazon SQS — Pricing). O que pesa não é a conta do SQS, e sim o custo total de propriedade: recurso reservado e mais peças para provisionar, proteger e monitorar em cada ambiente.

4. Autoscaling reagindo ao batch, e não aos usuários

O HPA (Horizontal Pod Autoscaler) adiciona e remove réplicas da API conforme uma métrica, normalmente CPU. A premissa é que CPU alta significa mais usuários. Com o batch dentro da API, essa premissa quebra:

o HPA sobe réplicas que nenhum usuário está usando, e você paga por elas. E elas nem ajudam o lote: a mensagem é uma só e já está num pod;
quando a média de CPU cai, o HPA remove réplicas depois da janela de estabilização (5 minutos por padrão), e o pod removido pode ser justamente o que está com a mensagem: o lote é interrompido como num deploy (ver critério 2);
a métrica perde significado: não dá mais para saber se a API escalou por demanda real ou por causa do batch.

Na abordagem A, o HPA da API continua reagindo só ao tráfego.

5. Quando o destino cai: retry, DLQ e redrive

Imagine o SNS indisponível por uma hora.

Abordagem B: o consumidor tenta publicar, falha, e o processamento para. A mensagem não é apagada: volta à fila depois do visibility timeout, e a nova tentativa segue de onde parou, pelo status no banco, e falha de novo enquanto o SNS estiver fora. Cada tentativa conta um recebimento; atingido o maxReceiveCount (o limite de recebimentos da redrive policy), a mensagem, que representa o lote inteiro, vai para a DLQ. O intervalo entre as tentativas é o próprio visibility timeout: se ele foi dimensionado para cobrir o lote (critério 6), uma queda de uma hora pode passar entre duas tentativas; se é curto e o consumidor o estende enquanto processa, as tentativas se esgotam em minutos. Na DLQ, nada retoma sozinho: os pendentes ficam no banco até alguém, ou uma automação, fazer o redrive da mensagem para a fila principal (SQS — DLQ redrive), ou até o próximo disparo. E a DLQ tem prazo: a retenção conta desde o envio original, então a mensagem esquecida lá expira (SQS — Dead-letter queues). Ela também não separa as causas: uma queda do SNS e um registro ruim que derruba o consumidor chegam lá do mesmo jeito, como o lote inteiro.
Abordagem A: o SDK da AWS tenta de novo algumas vezes, com backoff. Esgotadas as tentativas, o step falha no chunk em andamento, o job sai com exit code diferente de zero e os registros ainda não enviados continuam pendentes no banco. As novas tentativas do backoffLimit não resolvem uma queda longa: o Kubernetes recria o pod com atraso de 10 s, 20 s, 40 s… (limitado a seis minutos), então, com backoffLimit: 2, todas acontecem com o SNS ainda fora. Quem pega os pendentes é a próxima execução agendada (num job diário, até 24 horas depois) ou um disparo manual assim que o SNS voltar: kubectl create job enviar-registros-manual --from=cronjob/enviar-registros. Não há mensagem parada numa DLQ nem redrive a fazer, mas há atraso. E, se o step usar skip para isolar itens inválidos, a exceção de infraestrutura não pode estar entre as puláveis: senão a queda do SNS vira uma leva de itens pulados (até o skipLimit), e uma falha de infraestrutura fica registrada como dado ruim.

Na B, dá para controlar o intervalo entre as tentativas: o Spring Cloud AWS traz um ExponentialBackoffErrorHandler, que, a cada falha, muda o visibility timeout da mensagem para um valor que cresce com o número de entregas, e dá para automatizar o redrive. Mas é desenho e código a mais, e o backoff precisa ser dimensionado junto com o maxReceiveCount. Há ainda o risco de retry em várias camadas ao mesmo tempo: SDK, eventual retry no listener e reentrega da fila. O artigo Timeouts, retries, and backoff with jitter, da Amazon Builders’ Library, recomenda concentrar o retry num único ponto da pilha, porque cada camada extra multiplica a carga sobre quem já está com problema.

6. Uma mensagem para o lote inteiro

Na abordagem B, a mensagem é só o gatilho: “processe os pendentes”. Quem sabe o que já foi feito é o banco, e quem lê a lista é o consumidor, não o endpoint. O desenho é simples, mas o lote inteiro fica preso a uma mensagem:

Um pod só. O lote roda inteiro no pod que recebeu a mensagem, que continua atendendo a sua parte das requisições (critério 1). As outras réplicas não têm o que consumir, então não há paralelismo entre pods.
O visibility timeout precisa cobrir o lote. Enquanto o consumidor trabalha, a mensagem continua na fila, só invisível para os outros. Se o prazo vence antes do fim, ela volta a ficar visível, outro consumidor a recebe e começa o mesmo lote: dois consumidores lendo os mesmos pendentes ao mesmo tempo. O padrão da fila é 30 segundos, e o Spring Cloud AWS, numa fila standard, define a visibilidade uma vez só, no recebimento (Spring Cloud AWS — SQS). Ou o prazo da fila cobre o lote inteiro, ou o consumidor o estende enquanto processa (o argumento Visibility do listener tem o método changeTo()). E há um teto: 12 horas contadas a partir do recebimento, que as extensões não renovam (SQS — Visibility timeout).
A retomada espera o prazo. Se o pod morre (deploy, OOM, redução do HPA), a mensagem só reaparece quando o visibility timeout expira. Um prazo longo, para cobrir o lote, atrasa a retomada na mesma medida; um curto, estendido enquanto processa, retoma logo, mas é código a mais.
Um registro ruim trava o lote. Se o consumidor lança exceção num registro, a mensagem inteira volta à fila e, depois de N tentativas, vai para a DLQ, parando no mesmo registro a cada vez. O consumidor precisa marcar o registro inválido e seguir, como a abordagem A também precisa (skip ou status).

Na abordagem A, o pod do job é a própria execução, sem prazo de visibilidade para dimensionar, e o reader do Spring Batch lê a lista em páginas, por chave (ver critério 11).

7. Um endpoint a mais para proteger

Na abordagem B existe uma rota HTTP que dispara processamento em lote. Ela precisa ser protegida, e o CronJob, se autenticar para chamá-la: obter um token e montar a requisição, geralmente num script shell. Em ambientes regulados, expor lógica de negócio como endpoint pode não ser permitido. É esse o argumento de Chris Jones, no artigo já citado, para trocar o CronJob que chama a API via curl por um CronJob que roda a própria imagem (The New Stack).

8. Visibilidade por execução

Na abordagem A, cada execução é um objeto com início, fim e resultado:

o exit code do container diz ao Kubernetes se o pod deu certo e, esgotadas as tentativas do backoffLimit, o Job fica como falho. O kube-state-metrics transforma isso em métricas, sem código adicional: kube_job_failed{condition="true"} indica o Job que falhou de vez. Não use kube_job_status_failed para esse alerta: ela conta pods com falha e passa de zero mesmo quando a retentativa deu certo (kube-state-metrics — métricas de Job);
falha não é o único risco: se o CronJob não criar o Job, ou se o Forbid pular horários atrás de um Job travado, nenhum Job falha e nenhum alerta de falha dispara. Para isso serve kube_cronjob_status_last_successful_time, o horário do último sucesso: time() - kube_cronjob_status_last_successful_time{cronjob="enviar-registros"} > 26 * 3600 avisa quando o job diário passa mais de 26 horas sem terminar com sucesso (kube-state-metrics — métricas de CronJob);
o Spring Batch grava cada execução nas tabelas de metadados, desde que o JobRepository esteja no banco (ver Como montar a abordagem A). BATCH_JOB_EXECUTION guarda início, fim e status. BATCH_STEP_EXECUTION guarda quantos itens foram lidos (READ_COUNT), gravados (WRITE_COUNT), filtrados (FILTER_COUNT) e pulados (READ_SKIP_COUNT, PROCESS_SKIP_COUNT, WRITE_SKIP_COUNT) (Spring Batch — Meta-Data Schema).

Na abordagem B, a fila só mostra o gatilho: se a mensagem foi consumida, se voltou, se foi para a DLQ. Responder “O lote de hoje terminou? Quantos registros foram enviados?” exige criar tabela, contadores e lógica próprios. Não é impossível; é trabalho que, na abordagem A, já vem pronto.

9. Resposta perdida na rede: o gatilho dispara duas vezes

Na abordagem B, entre o agendador e o processamento existe uma chamada HTTP, e chamadas HTTP falham de um jeito traiçoeiro. O endpoint recebe a requisição, publica a mensagem e responde 202, mas a resposta se perde no caminho: timeout do próprio curl, conexão resetada porque o pod que recebeu a chamada está sendo encerrado num deploy, um proxy no meio. O curl termina com erro, o pod do CronJob sai com exit code diferente de zero e o Kubernetes, seguindo o backoffLimit, tenta de novo. O endpoint recebe a segunda chamada e publica uma segunda mensagem. Se houver retry configurado em algum proxy intermediário, como ingress ou service mesh, a requisição pode ser reenviada sem que o CronJob sequer perceba.

Isso pressupõe um curl bem configurado. Sem --fail, ele sai com código 0 mesmo quando a API responde 500 ou 401, e o CronJob registra sucesso sem o lote ter rodado; sem --max-time, ele não tem prazo para desistir. Use curl --fail --max-time <segundos>.

O problema é estrutural: quem chama não consegue distinguir “a requisição não chegou” de “a requisição chegou, mas a resposta não voltou”. A Amazon Builders’ Library descreve exatamente esse dilema: depois de um timeout, quem chamou não sabe se a operação aconteceu, e repetir a chamada pode duplicar o efeito. A saída é tornar a operação idempotente (Making retries safe with idempotent APIs). Na abordagem B, isso significa uma chave de idempotência, como a data de referência. No gatilho, uma fila FIFO resolve parte do problema: com o MessageDeduplicationId igual à data, uma segunda mensagem enviada em até 5 minutos é aceita, mas não é entregue, o que cobre o retry rápido do Kubernetes, mas não uma nova chamada mais tarde (SQS — Exactly-once processing). O resto fica com o consumidor.

A coluna de status no banco ajuda, mas não resolve sozinha. Se a segunda mensagem chega depois que a primeira terminou, não encontra pendentes e não faz nada. O problema é quando as duas rodam juntas, que é justamente o caso do retry rápido: dois pods leem os mesmos registros como pendentes antes que qualquer um marque “enviado”, e cada registro sai duas vezes. Evitar isso exige que o consumidor reserve cada registro com uma atualização condicional antes de enviar, ou que só um consumidor processe o lote por vez, com um lock no banco que expire se o pod morrer (como o do ShedLock). Mais uma peça a construir.

Na abordagem A, esse modo de falha não aparece, mas não por falta de rede no caminho. O controlador do CronJob também cria o Job com uma chamada ao API server, e essa resposta também pode se perder. A diferença é que o Kubernetes já tornou essa chamada idempotente: o nome do Job é derivado do horário agendado, e uma nova tentativa para o mesmo horário recebe AlreadyExists em vez de criar outro Job (código do controlador). É a chave de idempotência que a abordagem B teria de construir. Dali em diante, o processamento é o próprio pod, e o resultado é o exit code dele, sem resposta HTTP no meio. O que sobra são os casos raros documentados (critério 10), barrados pelo JobRepository.

10. Outras fontes de duplicidade

Além do gatilho HTTP, há outras fontes de duplicidade, e nem todas dependem da escolha:

O próprio CronJob. A documentação do Kubernetes avisa que a criação é aproximada: em certas circunstâncias, um CronJob pode criar dois Jobs, ou nenhum, e por isso os jobs devem ser idempotentes (Kubernetes — CronJob). A página de Job acrescenta que, mesmo com um único pod e restartPolicy: Never, o mesmo programa pode às vezes ser iniciado duas vezes (Kubernetes — Jobs). Na abordagem A, quem cobre isso é o JobRepository do Spring Batch, desde que a data de referência seja o parâmetro identificador do job (ver Como montar a abordagem A). Ele recusa uma nova execução de uma instância que já terminou com sucesso ou que ainda está rodando; se a anterior falhou, a nova execução é um restart da mesma instância, que é o que se quer. Se dois pods tentarem criar a mesma instância ao mesmo tempo, só um consegue: a criação roda em transação SERIALIZABLE (Spring Batch — Configuring a JobRepository), e a tabela BATCH_JOB_INSTANCE tem restrição única em (JOB_NAME, JOB_KEY). Nos testes, com duas JVMs disparadas juntas para a mesma data, sempre uma processou e a outra saiu com erro, sem publicação duplicada. A execução recusada aparece como Job com falha no Kubernetes: é ruído esperado, não erro. O concurrencyPolicy: Forbid completa a proteção, impedindo, em regra, que uma execução comece antes de a anterior terminar. Na abordagem B, um segundo Job faz uma segunda chamada ao endpoint, e a proteção é a do critério 9.
A reentrega da fila (só na B). A fila standard do SQS entrega cada mensagem pelo menos uma vez e, ocasionalmente, mais de uma (SQS — Standard queues). Com uma mensagem por lote, uma cópia é um segundo consumidor rodando o mesmo lote: o cenário do critério 9, sem nenhuma falha de rede, e com a mesma proteção.
A publicação no SNS. Publicar e só depois marcar o registro deixa uma janela: se o processo cair entre as duas operações, o registro é enviado de novo na próxima tentativa. Na B, a janela é de um registro; na A, é do tamanho do chunk: se a transação do chunk é desfeita depois da publicação, todos os itens dele saem de novo. E, com PublishBatch, a chamada pode voltar 200 com parte das entradas recusadas, então o writer precisa conferir as falhas da resposta antes de marcar os registros como enviados (Amazon SNS — PublishBatch). Em qualquer caso, os assinantes do tópico devem ser idempotentes. É a mesma janela do post Efeito externo sem registro local, agora com o SNS no lugar do adquirente de pagamentos.

11. Retomar de onde parou: empate

As duas abordagens conseguem retomar de onde pararam. Na B, pela reentrega da mensagem e pela coluna de status, que diz o que ainda falta. Na A, pelo padrão process indicator descrito na documentação do Spring Batch: uma coluna marca os registros processados e o reader traz só os pendentes (Spring Batch — Preventing State Persistence).

Dois detalhes fazem esse padrão funcionar. O primeiro é o assunto da própria página citada: o reader deve usar saveState(false). Com o padrão (true), um reader por cursor, no restart, avança a quantidade de itens já lidos numa consulta que não traz mais os processados, e registros pendentes ficam para trás. O segundo: se a leitura for paginada, pagine por chave, não por offset. O JdbcPagingItemReader busca cada página a partir da última chave lida (o sortKey, que precisa ser única); já o JpaPagingItemReader e o RepositoryItemReader usam offset, então cada página marcada como enviada sai do filtro, e o offset da página seguinte pula a mesma quantidade de pendentes (Spring Batch — Database).

A diferença entre as abordagens não está em conseguir retomar, e sim em como cada uma se comporta quando a interrupção vem de um deploy (critério 2) ou de uma indisponibilidade do destino (critério 5).

Onde a abordagem B ganha

Retomada automática. Se o consumidor falha ou o pod morre, a mensagem volta sozinha depois do visibility timeout, e outro pod segue de onde parou, pelo status no banco. O Twelve-Factor recomenda exatamente isso para workers, no fator IX (Disposability): uma fila que devolva o trabalho quando o processo morre. Na abordagem A, o backoffLimit retoma uma falha comum, mas um pod morto no meio deixa a execução STARTED, e as novas tentativas são recusadas até alguém destravá-la (ver “O preço da abordagem A”). O modelo de worker com fila é legítimo; o problema é consumi-la dentro da API.
Um caminho para paralelizar. Com uma mensagem por execução, a B também processa o lote num pod só. Mas a fila já está lá: se o volume crescer, o lote pode ser dividido em várias mensagens (por faixa de ids, por exemplo), e os consumidores, escalados pela profundidade da fila, inclusive até zero, com o KEDA. A abordagem A também paraleliza, mas o grau de paralelismo é definido antes da execução e não cresce sozinho com o volume. No Spring Batch, o step multi-thread processa os itens de cada chunk em várias threads dentro do mesmo pod, enquanto a leitura e a escrita continuam em série; no particionamento, os dados são divididos no início, e o step só termina quando a última partição termina (um gridSize maior que o número de threads deixa os blocos menores e reduz essa espera). Com Indexed Jobs no Kubernetes, o trabalho de cada índice também é fixado de antemão. Antes de otimizar, vale o conselho da própria documentação do Spring Batch: muitos problemas se resolvem com um job de uma thread e um processo, então meça primeiro.
Sem custo de inicialização. Os pods já estão rodando, com a JVM aquecida. A abordagem A sobe uma JVM a cada execução, o que é irrelevante para um job diário, mas pesa num job que roda a cada minuto.
Disparo sob demanda e fluxo contínuo. Qualquer sistema pode disparar o processamento a qualquer momento, chamando o endpoint. E, se os itens chegam ao longo do dia como eventos, e não como uma lista fixa, a fila, aí com uma mensagem por item, é o modelo natural. Na abordagem A, o disparo fora de hora existe (kubectl create job --from=cronjob/…), mas é operação, não integração.
Menos conceitos novos. Não há Spring Batch para aprender nem tabelas de metadados para manter; em troca, entram DLQ, visibility timeout e redrive.

O preço da abordagem A

Uma JVM por execução. Alguns segundos de inicialização a cada rodada.
Idiossincrasias do CronJob. Ele pode criar dois Jobs ou nenhum: a idempotência é obrigatória, e o alerta de “não rodou” também (critério 8).
O pod do job não é imortal. Drenagem de nó, OOMKill e o próprio activeDeadlineSeconds também o encerram. Se o processo morre sem atualizar o JobRepository, a execução fica como STARTED, e toda nova tentativa com a mesma data, inclusive as do backoffLimit, é recusada (JobExecutionAlreadyRunningException) até alguém marcá-la como FAILED. Num teste com Spring Boot 4.1.1, até um SIGTERM terminou assim: o Spring Boot fechou o pool de conexões com o step ainda rodando. Até o Spring Batch 5, destravar exigia um UPDATE manual nas tabelas (Spring blog); no 6, existe JobOperator.recover(...), mas alguém ainda precisa chamá-lo (Spring Batch — Recovering a job). A execução do dia seguinte, com outra data, não é afetada.
Paralelismo definido antes da execução. Se um dia o lote precisar de elasticidade, a fila oferece o caminho (dividir o lote em várias mensagens), e o pod do job, não.
Release acoplado. Usar a mesma imagem significa que cada release da API leva junto uma nova versão do job, aplicada na próxima execução (desde que o pipeline atualize também a imagem do CronJob). Se os dois precisarem evoluir em ritmos diferentes, separe em módulos e imagens.
Curva de aprendizado e manutenção. Mais um framework e as tabelas de metadados, que crescem sem parar: o Spring Batch não tem equivalente ao ttlSecondsAfterFinished do Job, e a limpeza fica por sua conta. O Spring Batch, porém, é opcional: um ApplicationRunner com a coluna de status também funciona, sem o histórico por execução e a proteção do JobRepository.

Resumo

Critério	A — CronJob	B — Endpoint + SQS
Disputa de recursos com a API	Pod próprio	Mesmo processo
Deploy durante o processamento	Não afeta o job	Interrompe o lote, que só volta depois do visibility timeout, em outra versão
Recurso reservado	Só durante a execução	Folga para o pico do batch, o dia inteiro
Autoscaling da API	Reage só ao tráfego	Reage também ao batch
Destino fora do ar	Job falha; a próxima execução (ou um disparo manual) retoma	A mensagem volta à fila até cair na DLQ; retoma com redrive ou no próximo disparo
Leitura da lista	No pod do job	No consumidor, dentro da API
Lote longo	Só o `activeDeadlineSeconds` que você definir	O visibility timeout precisa cobri-lo (teto de 12 h)
Endpoint a proteger	Não existe	Existe
Visibilidade por execução	Pronta (Job + tabelas `BATCH_*`, com o JobRepository no banco)	Precisa ser construída
Resposta perdida na rede	Não acontece: a criação do Job já é idempotente	Segunda mensagem: dois pods no mesmo lote
Duplicidade do CronJob	JobRepository (data de referência) + `Forbid`	Controle próprio (critério 9)
Retomar de onde parou	Coluna de status (process indicator); pod morto exige `recover`	Coluna de status; a mensagem volta sozinha
Falha isolada por item	Precisa configurar (skip, status)	Precisa programar (status); senão, a mensagem inteira volta
Paralelismo	Definido antes da execução	Um pod só: a mensagem é uma
Custo de inicialização	JVM a cada execução	Pods já rodando
Disparo sob demanda	Manual (`kubectl create job --from`)	Natural
Conceitos novos	Spring Batch (opcional)	Fila, DLQ, visibility timeout, redrive

Como montar a abordagem A

O que segue foi testado com Spring Boot 4.1.1 (Spring Batch 6.0.5), Java 21 e PostgreSQL 16, nos cenários que os critérios descrevem: execução normal, falha no meio do lote, nova execução no mesmo dia e no dia seguinte, duas execuções simultâneas, SIGKILL e SIGTERM no meio do processamento.

A dependência. No Spring Boot 4, o spring-boot-starter-batch sozinho usa o modo sem banco do Spring Batch 6 (ResourcelessJobRepository): os metadados ficam em memória e somem quando o pod termina. Sem tabelas BATCH_*, sem histórico de execuções e sem proteção contra uma segunda execução, ou seja, sem o que os critérios 8 a 10 descrevem. O JobRepository no banco vem do spring-boot-starter-batch-jdbc (no Spring Boot 3, o spring-boot-starter-batch já trazia o JDBC; ver o Spring Boot 4.0 Migration Guide):

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

As tabelas precisam existir no banco. Por padrão (spring.batch.jdbc.initialize-schema: embedded), o Spring Boot só cria o schema do Spring Batch em banco embutido; num PostgreSQL, a primeira execução falha com relation "batch_job_instance" does not exist. No teste usei initialize-schema: always; em produção, o caminho natural é aplicar por Flyway ou Liquibase o schema-postgresql.sql que vem no spring-batch-core (em org/springframework/batch/core/).

Os perfis. Uma imagem, dois perfis. Os beans de Job e Step ficam sob @Profile("batch"). O application.yml é a base de todos os perfis e desliga a execução automática de jobs, que é o que vale na API (ela roda sem perfil ativo). O application-batch.yml só sobrescreve o que declara, por isso religa a execução explicitamente:

spring:
  batch:
    job:
      enabled: false

spring:
  main:
    web-application-type: none
  datasource:
    hikari:
      maximum-pool-size: 2        # pool pequeno: o banco é compartilhado com a API
  batch:
    job:
      enabled: true               # religa o que o application.yml desligou
      name: enviarRegistrosJob
    jdbc:
      initialize-schema: always   # ou migração por Flyway/Liquibase (ver acima)

Sem o enabled: true, o pod no perfil batch sobe, não executa job nenhum e sai com código 0, e o Kubernetes registra sucesso todo dia.

O web-application-type: none tira só o servidor web. O resto do contexto sobe igual no pod do job: listeners de fila (@SqsListener, @KafkaListener), tarefas @Scheduled e rotinas de aquecimento em ApplicationRunner passam a trabalhar ali dentro, disputando CPU, memória e conexões com o lote. Coloque esses beans, e a classe com @EnableScheduling, sob @Profile("!batch").

O exit code. O main propaga o exit code só no perfil batch:

@SpringBootApplication
public class App {

    public static void main(String[] args) {
        var ctx = SpringApplication.run(App.class, args);
        if (ctx.getEnvironment().acceptsProfiles(Profiles.of("batch"))) {
            System.exit(SpringApplication.exit(ctx));
        }
    }
}

Com o Spring Batch, o Spring Boot registra um ExitCodeGenerator que devolve código diferente de zero quando o job não termina COMPLETED; no teste, um job FAILED saiu com 5, a posição de FAILED no enum BatchStatus (Spring Boot — Application Exit). Sem o System.exit, o processo sai com 0 mesmo quando o job falha, e o Kubernetes registra sucesso. Na API, sem o perfil batch, o main não chama System.exit, e a aplicação continua no ar.

A data de referência. É ela que faz de cada dia uma instância própria no JobRepository e que permite recusar a execução duplicada dos critérios 9 e 10. O Kubernetes não calcula datas nos args sem um shell, e, no Spring Batch 6, quando o job tem um incrementer, os parâmetros passados na linha de comando são ignorados (fica só um aviso no log). Por isso quem gera a data é o incrementer do job, no mesmo fuso do timeZone do CronJob:

// Uma JobInstance por dia: a data de referência é o parâmetro identificador
@Bean
Job enviarRegistrosJob(JobRepository jobRepository, Step enviarRegistrosStep) {
    return new JobBuilder("enviarRegistrosJob", jobRepository)
            .incrementer(anteriores -> new JobParametersBuilder()
                    .addLocalDate("dataReferencia",
                            LocalDate.now(ZoneId.of("America/Sao_Paulo")))
                    .toJobParameters())
            .start(enviarRegistrosStep)
            .build();
}

O que aconteceu em cada caso, nos testes:

primeira execução do dia: COMPLETED, exit code 0;
nova execução no mesmo dia, depois de um COMPLETED: recusada (JobInstanceAlreadyCompleteException), exit code 1;
nova execução no mesmo dia, depois de um FAILED: restart da mesma instância, e o reader lê só os pendentes;
no dia seguinte: uma instância nova.

Sem parâmetro nenhum, o job roda uma vez na vida: no Spring Batch 6, a instância de parâmetros vazios fica COMPLETED no primeiro dia, e toda execução a partir do segundo é recusada. Com um RunIdIncrementer, acontece o contrário: cada execução vira uma instância nova, e nada é recusado.

Configuração completa do job (testada com Spring Boot 4.1.1 e Spring Batch 6.0.5)

O SNS está simulado (o writer grava numa tabela publicacao e registra no log); no serviço real, ali entra a chamada ao SnsClient. Três detalhes do Spring Batch 6 aparecem no código: as interfaces de item mudaram de pacote (org.springframework.batch.infrastructure.item); o step precisa de .transactionManager(...), senão usa um ResourcelessTransactionManager e o JDBC do writer fica fora da transação do chunk; e o reader pagina por chave, com saveState(false) (critério 11).

package br.com.exemplo;

import java.time.LocalDate;
import java.time.ZoneId;
import java.util.Map;

import javax.sql.DataSource;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.batch.core.job.Job;
import org.springframework.batch.core.job.builder.JobBuilder;
import org.springframework.batch.core.job.parameters.JobParametersBuilder;
import org.springframework.batch.core.repository.JobRepository;
import org.springframework.batch.core.step.Step;
import org.springframework.batch.core.step.builder.StepBuilder;
import org.springframework.batch.infrastructure.item.ItemProcessor;
import org.springframework.batch.infrastructure.item.ItemWriter;
import org.springframework.batch.infrastructure.item.database.JdbcPagingItemReader;
import org.springframework.batch.infrastructure.item.database.Order;
import org.springframework.batch.infrastructure.item.database.builder.JdbcPagingItemReaderBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.jdbc.core.simple.JdbcClient;
import org.springframework.transaction.PlatformTransactionManager;

@Configuration
@Profile("batch")
class EnviarRegistrosJobConfig {

    private static final Logger log = LoggerFactory.getLogger(EnviarRegistrosJobConfig.class);

    record Registro(long id, String payload, String status) {}

    // Uma JobInstance por dia: a data de referência é o parâmetro identificador
    @Bean
    Job enviarRegistrosJob(JobRepository jobRepository, Step enviarRegistrosStep) {
        return new JobBuilder("enviarRegistrosJob", jobRepository)
                .incrementer(anteriores -> new JobParametersBuilder()
                        .addLocalDate("dataReferencia",
                                LocalDate.now(ZoneId.of("America/Sao_Paulo")))
                        .toJobParameters())
                .start(enviarRegistrosStep)
                .build();
    }

    @Bean
    Step enviarRegistrosStep(JobRepository jobRepository, PlatformTransactionManager transactionManager,
            JdbcPagingItemReader<Registro> pendentes, JdbcClient jdbc) {
        return new StepBuilder("enviarRegistrosStep", jobRepository)
                .<Registro, Registro>chunk(100)
                .transactionManager(transactionManager)
                .reader(pendentes)
                .processor(validar())
                .writer(publicarEMarcar(jdbc))
                .build();
    }

    // Process indicator: só os PENDENTE; sem estado salvo, o restart relê o que falta
    @Bean
    JdbcPagingItemReader<Registro> pendentes(DataSource dataSource) throws Exception {
        return new JdbcPagingItemReaderBuilder<Registro>()
                .name("pendentes")
                .dataSource(dataSource)
                .selectClause("SELECT id, payload, status")
                .fromClause("FROM registro")
                .whereClause("WHERE status = 'PENDENTE'")
                .sortKeys(Map.of("id", Order.ASCENDING))
                .dataRowMapper(Registro.class)
                .pageSize(100)
                .saveState(false)
                .build();
    }

    private ItemProcessor<Registro, Registro> validar() {
        return r -> new Registro(r.id(), r.payload(),
                r.payload() == null || r.payload().isBlank() ? "INVALIDO" : "ENVIADO");
    }

    private ItemWriter<Registro> publicarEMarcar(JdbcClient jdbc) {
        return chunk -> {
            for (Registro r : chunk) {
                if (r.status().equals("ENVIADO")) {
                    // simula o SNS; no serviço real: snsClient.publish(...)
                    jdbc.sql("INSERT INTO publicacao (registro_id, payload) VALUES (?, ?)")
                            .params(r.id(), r.payload())
                            .update();
                    log.info("Publicado no SNS: registro {}", r.id());
                }
                jdbc.sql("UPDATE registro SET status = ? WHERE id = ?")
                        .params(r.status(), r.id())
                        .update();
            }
        };
    }
}

O CronJob. Usa a mesma imagem da API. O que cada campo garante, e o que não garante, está no post Kubernetes CronJob — concorrência, retries e tempo máximo de execução:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: enviar-registros
spec:
  schedule: "0 3 * * *"
  timeZone: America/Sao_Paulo
  concurrencyPolicy: Forbid
  startingDeadlineSeconds: 3600      # atrasou mais de 1 h: pula e espera o próximo dia
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 3
  jobTemplate:
    spec:
      backoffLimit: 2
      activeDeadlineSeconds: 7200    # com Forbid, um Job travado bloquearia os próximos
      template:
        spec:
          restartPolicy: Never
          containers:
            - name: worker
              image: meu-servico:1.2.3   # a mesma imagem do Deployment da API
              env:
                - name: SPRING_PROFILES_ACTIVE
                  value: batch
              resources:
                requests:
                  cpu: 500m
                  memory: 1Gi
                limits:
                  cpu: "1"
                  memory: 1Gi

timeZone: sem ele, o horário é lido no fuso do kube-controller-manager, em geral UTC, e as 03:00 viram meia-noite em Brasília, bem na virada da data que o incrementer calcula.
activeDeadlineSeconds: com Forbid, um Job travado faria o CronJob pular todas as execuções seguintes; o prazo derruba o Job e libera a agenda (e, como visto em “O preço da abordagem A”, a execução interrompida fica STARTED).
startingDeadlineSeconds: se o Job não for criado até uma hora depois do horário, a execução é pulada, e os pendentes ficam para o dia seguinte.
resources: os valores do exemplo do critério 3. Sem eles, o pod fica na classe BestEffort: não reserva nada no nó e é o primeiro a ser despejado. Com limits.memory: 1Gi, a JVM usa por padrão só 25% disso para o heap; se a imagem não ajusta o heap, defina -XX:MaxRAMPercentage (The java Command).

Se o CronJob sair do mesmo template do Deployment (Helm, Kustomize), deixe de fora as probes de liveness e de startup: sem servidor web, ninguém responde ao /actuator/health, o kubelet mata o container no meio do job, e cada nova tentativa do backoffLimit falha do mesmo jeito.

Referências para essa configuração: Spring Boot — Spring Batch (execução do job na inicialização e as propriedades spring.batch.*), Spring Boot — Application Exit e Kubernetes — CronJob.

Conclusão

Para uma lista fixa no banco, processada em horário agendado e com trabalho leve por item, a abordagem A vence nos critérios que mais pesam: isolamento de recursos, deploy da API sem interromper o job, recurso reservado só quando necessário, um gatilho que já nasce idempotente, nenhum lote preso ao prazo de uma mensagem e menos peças para operar. E a visibilidade por execução já vem pronta. Isso vale desde que ela seja montada com os cuidados da seção anterior: JobRepository no banco, data de referência como parâmetro identificador e um CronJob com fuso, prazos e recursos definidos.

A abordagem B passa à frente quando os itens chegam continuamente como eventos, quando o processamento por item é pesado ou variável, ou quando o volume pede elasticidade. Mas aí o desenho também muda: em vez de uma mensagem por execução, uma por item, ou por faixa de itens, consumidas num Deployment próprio, no estilo Web-Queue-Worker, e não dentro da API, onde os problemas dos critérios 1 a 4 continuam existindo. De preferência, escale esse Deployment pela profundidade da fila, inclusive até zero: parado o dia inteiro, ele volta ao problema do critério 3. E o gatilho nem precisa ser HTTP: o próprio CronJob da abordagem A pode ler a lista e enfileirar. Some o endpoint (critério 7), e a duplicidade do critério 9 só muda de lugar, para o produtor, que precisa marcar o que já enfileirou.

No cenário deste post, a fila consumida dentro da API também resolve. Mas, para chegar ao mesmo lugar, você constrói e opera mais peças, reserva recurso na API o dia inteiro, amarra o lote ao prazo de uma mensagem e mantém o processamento disputando espaço com quem atende o usuário.

Fontes

Michael T. Nygard — Release It! Design and Deploy Production-Ready Software, 2ª ed. (Pragmatic Bookshelf; padrão Bulkhead)
Martin Kleppmann — Designing Data-Intensive Applications, 1ª ed., cap. 10 (Batch Processing) (O’Reilly, 2017); na 2ª ed., com Chris Riccomini, o tema está no cap. 11
Verma et al. — Large-scale cluster management at Google with Borg (EuroSys 2015)
The Twelve-Factor App — VIII. Concurrency e IX. Disposability
Microsoft — Bulkhead pattern, Web-Queue-Worker architecture style e Best practices for background jobs
Amazon Builders’ Library — Timeouts, retries, and backoff with jitter e Making retries safe with idempotent APIs
Chris Jones — Rethinking Java @Scheduled Tasks in Kubernetes (The New Stack, 2023)
Chris Jones — Alternative JAR Entry Points Using Java Dependency Injection Frameworks (AWS Open Source Blog) e código de exemplo
Mahmoud Ben Hassine — Spring Batch on Kubernetes: Efficient batch processing at scale (Spring blog, 2021)
Rohit Raveendran — Decoding the pod termination lifecycle in Kubernetes: a comprehensive guide (blog da CNCF, 2024)
Kubernetes — CronJob, Jobs, término de pods, Resizing Pods, requests e limits, Horizontal Pod Autoscaling, Vertical Pod Autoscaling e Indexed Jobs
Kubernetes — código do controlador de CronJob (nome do Job derivado do horário agendado)
kube-state-metrics — métricas de Job e métricas de CronJob
Spring Boot — Profiles, Spring Batch, Application Exit e Graceful Shutdown
Spring Boot — Spring Boot 4.0 Migration Guide (Spring Batch sem banco por padrão e o spring-boot-starter-batch-jdbc)
Spring Batch — What’s new in Spring Batch 6, Configuring a JobRepository, Advanced Meta-Data Usage, Meta-Data Schema, Preventing State Persistence, Database e Scaling and Parallel Processing
Spring Cloud AWS — SQS (visibilidade da mensagem, listenerShutdownTimeout e ExponentialBackoffErrorHandler)
Amazon SQS — Standard queues, Visibility timeout, Dead-letter queues, DLQ redrive, Exactly-once processing (FIFO) e Pricing
Amazon SNS — PublishBatch
HikariCP — README
KEDA — AWS SQS Queue scaler
ShedLock — README
Oracle — The java Command (-XX:MaxRAMPercentage)

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 e o equivalente em Spring Data JPA. Depois, o terceiro caminho que muitas vezes dispensa ambos (o UPDATE condicional), o papel dos níveis de isolamento, um critério de escolha e as perguntas que eu faço antes de decidir.

O tema aparece de raspão no artigo sobre chave de idempotência, 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. Aparece em contador de estoque, em saldo, em qualquer campo calculado a partir do valor lido.

É a mesma família do problema da 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. A documentação do Spring Framework fixa a ordem dos dois interceptadores, retry por fora e transação por dentro, então 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 em julho de 2026 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 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. É 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. Em HTTP, a mesma ideia é o ETag com If-Match, que a RFC 9110 descreve justamente como proteção contra o lost update; no CouchDB, é o campo _rev, que recusa com 409 a gravação feita sobre uma revisão antiga.
Retry automático não serve para edição humana. Retentar às cegas só faz sentido quando a aplicação sabe recalcular a partir do dado novo: um débito, um contador, um status. Quando quem editou foi uma pessoa, a resposta certa para o conflito é devolver o erro com o estado atual (409 Conflict, ou 412 Precondition Failed quando a versão veio num If-Match) e deixar que ela decida o que fazer com as duas versões. Sobrescrever em silêncio é exatamente o lost update que a versão existia para impedir.
UPDATE em massa passa por fora do @Version. Um update em JPQL (com @Modifying) ou em SQL nativo não checa nem incrementa a versão: quem escreve o comando precisa incluir o version = version + 1 e, se a decisão depende do valor lido, o filtro pela versão, como no SQL puro acima. A proteção só é automática para entidades gerenciadas que passam pelo save.

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 in relation "conta"). 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, e a documentação do PostgreSQL cita exatamente esse uso: vários workers pegam itens diferentes sem disputar o mesmo, sem broker de mensagens. O relay do outbox em Efeito externo sem registro local funciona assim.
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; estourado, o erro é canceling statement due to lock timeout). 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.

Deadlock: o risco que vem junto

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 outra segue. Para a aplicação, é mais um erro que precisa de dono, igual ao conflito do otimista.

A prevenção é simples e quase nunca feita: travar sempre na mesma ordem. Quando a transação precisa de mais de uma linha, peça todas de uma vez, ordenadas:

SELECT id, saldo
  FROM conta
 WHERE id IN (7, 3)
 ORDER BY id
   FOR UPDATE;

O ORDER BY não é enfeite: no plano de execução, o nó que trava as linhas (LockRows) fica acima do Sort, então as travas são adquiridas na ordem do id, e duas transações que precisem das contas 3 e 7 nunca se cruzam. Some um lock_timeout para que a espera, deadlock ou não, tenha teto.

Deadlock é 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 travar mesmo sem FOR UPDATE, com ou sem coluna de versão.

Quando a trava precisa atravessar requisições

A trava de banco morre com a transação. Para um “só um por vez” que dura minutos, como reservar um assento enquanto a pessoa preenche o formulário ou fazer check-out de um documento para edição, a trava vira um registro da aplicação: uma linha numa tabela de travas dizendo quem está com o quê e até quando, obtida antes de começar e liberada no fim. Para que dois pedidos simultâneos não levem a trava juntos, a inserção usa a mesma restrição única do post de idempotência. O prazo de validade é obrigatório, porque o cliente pode sumir sem liberar. É o Pessimistic Offline Lock do catálogo do Fowler, o par do otimista da seção anterior.

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
RETURNING saldo;
-- UPDATE 1 -> debitou (e devolveu o saldo novo)
-- 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. O RETURNING devolve o saldo novo no mesmo comando, sem outra consulta.

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. E os 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, e nele o padrão “leu na aplicação, calculou, gravou” não está protegido: cada comando enxerga o que já foi confirmado, e a segunda gravação simplesmente passa por cima da primeira. Daí a necessidade de bloqueio explícito.

Em REPEATABLE READ e SERIALIZABLE, o PostgreSQL impede o lost update por conta própria: quando a transação tenta gravar uma linha que outra transação alterou e confirmou depois do início dela, o comando é abortado com could not serialize access due to concurrent update. Repare no que isso é: bloqueio otimista feito pelo banco, com a mesma consequência. Detecção produz erro, e o erro continua precisando de dono: alguém relê e tenta de novo. Subir o isolamento muda quem detecta o conflito, não elimina o tratamento dele.

O SERIALIZABLE vai além: pega anomalias que nenhuma trava de linha pega, como duas transações que leem um conjunto de linhas e cada uma grava numa linha diferente com base no que leu (write skew). O preço é mais abortos sob disputa e mais trabalho do banco para rastrear as dependências. E, como a trava, o isolamento vive dentro de uma transação: não protege o formulário aberto às 10h e salvo às 10h15.

6. 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”.

O critério prático que eu uso é a taxa de disputa pela mesma linha. Cadastro de cliente, limite, parâmetro de produto, qualquer coisa que uma pessoa edita numa tela: otimista. Saldo de uma única conta em dia de pico, contador de uso de limite, qualquer linha que o sistema atualiza por conta própria muitas vezes por segundo: pessimista ou, melhor ainda, um único UPDATE condicional.

Quando nenhum dos dois basta: a linha quente

Existe um caso em que a escolha não resolve: a linha quente, uma única linha que todo mundo grava. Um contador global, o saldo da conta que recebe todos os créditos do dia, o estoque do produto em promoção. O otimista vira avalanche de retentativas, porque quase toda gravação encontra a versão mudada. O pessimista e o UPDATE condicional funcionam, mas serializam: cada gravação espera a anterior confirmar, e a vazão daquela linha fica limitada pela duração de uma transação. Não há trava que resolva isso, porque o problema não é a concorrência, é o modelo.

A saída é mudar o que se grava. Em vez de atualizar o saldo, acrescente lançamentos (uma linha por crédito, só INSERT, sem disputa) e calcule ou materialize o saldo em outro momento, que é o desenho de ledger. Contadores podem ser divididos em várias linhas (sharded counters) somadas na leitura. E quando a ordem importa, uma fila que serializa as gravações de propósito, em lote, costuma render mais do que centenas de transações disputando a mesma linha.

7. Cinco perguntas antes de decidir

São as perguntas que eu faço a um desenho antes de aprová-lo, e a falta de resposta costuma ser exatamente onde ele quebra em produção.

Quem trata o conflito, e o que o usuário final vê? Se a aplicação sabe recalcular (débito, contador), retry com teto, e o usuário nem fica sabendo. Se quem editou foi uma pessoa, ela vê o conflito e decide; retry automático aqui é sobrescrever em silêncio.
Como você percebe a avalanche de retentativas antes do cliente? Contando: cada ObjectOptimisticLockingFailureException e cada retry esgotado viram métrica, com alerta na taxa. Se a taxa sobe junto com a carga, a aposta do otimista estava errada para aquela linha: é hora de UPDATE condicional, de pessimista ou de repensar o modelo.
Existe chamada externa dentro da trava? Não pode existir. A trava envolve só a gravação local; o adquirente, o e-mail e a fila ficam fora, e o desenho para não perder nenhum dos dois lados está em Efeito externo sem registro local.
A transação trava mais de uma linha? Então trava sempre na mesma ordem, com lock_timeout, e com a transação mais curta que der. Deadlock não é azar: é ordem de travamento que ninguém definiu.
“Vamos subir para SERIALIZABLE e resolver de uma vez”? Resolve a detecção, não o tratamento: a aplicação continua precisando retentar, e sob disputa aborta mais do que a coluna de versão. Vale quando o invariante atravessa várias linhas; não substitui a versão que vai e volta com o formulário.

Apresentação em slides, no site.

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 — UPDATE (cláusula RETURNING)
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, ordem com @Transactional)
Spring Retry — repositório (arquivado em julho de 2026, 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 percorre a cadeia inteira desse incidente: por que o processo congela (o pinning de virtual threads dentro de blocos synchronized), por que o CLOSE_WAIT é o rastro e não a causa, como diagnosticar com thread dump e JFR, e o que continua valendo 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 5 e 6 (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. O sintoma: vivo, mudo e cheio de CLOSE_WAIT

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.

A leitura imediata costuma ser uma destas duas: “acabaram as threads” ou “tem um vazamento de conexão, alguém não está fechando socket”. As duas apontam para o lugar errado, e para ver por que é preciso ter quatro conceitos no lugar.

2. Quatro conceitos antes do diagnóstico

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. O diagnóstico: faltou carrier, não faltou thread

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.

CLOSE_WAIT em massa tem outras causas conhecidas, e vale ter a lista na cabeça: close() que não roda por causa de uma exceção, cliente HTTP sem try-with-resources, pool que nunca devolve a conexão. Todas têm algo em comum com esta: o código parou de chegar à linha que fecha. A diferença é que aqui ele parou de chegar a qualquer linha. É um dos primeiros lugares a olhar quando o processo está vivo, mas mudo.

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

4. 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.

5. 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 mesmo deslocamento de sempre, em outra roupa: 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. Remover um limite não aumenta a capacidade, só empurra a fila para o próximo recurso escasso. 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.

6. 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.

O nome geral desse freio é backpressure: 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. Virtual threads não aplicam backpressure sozinhas, elas aceitam tudo o que chega; o semáforo é você declarando o freio.

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; o nome vem das anteparas que dividem o casco de um navio em compartimentos estanques.

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 Chave de idempotência.

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.

7. O que fica depois do conserto

Corrigido o pinning e declarados os limites, sobram decisões que o incidente deixa para o time. São as que eu levaria para a retrospectiva.

Um upgrade por vez. Java 25 e Spring Boot 4 no mesmo deploy apagam a pista: se algo quebrar, não dá para saber qual dos dois foi. Suba o Java primeiro, que é o que conserta o pinning, estabilize, e só então o framework. O guia de atualizações do Java detalha o processo.
O que faltava no teste de carga. Ele passou limpo porque não reproduzia o que derruba: concorrência suficiente para prender todas as carriers ao mesmo tempo, o mesmo número de vCPUs da produção (carriers = processadores), as mesmas bibliotecas e agentes (no caso da Netflix, o synchronized estava no tracing) e duração para acumular. Teste sem o gargalo da produção só mede o que não importa.
A métrica que avisa que o pinning voltou. O evento jdk.VirtualThreadPinned do JFR é a fonte direta: com uma gravação contínua ou com JFR event streaming (jdk.jfr.consumer.RecordingStream, JEP 349) exportando a contagem para o Micrometer, qualquer ocorrência acima do limiar vira alerta. Os sinais indiretos já estavam no incidente: latência subindo com CPU baixa e a contagem de sockets em CLOSE_WAIT no host. Vale manter mesmo no Java 25: ainda há pinning quando código nativo chama de volta código Java que bloqueia (JEP 491), e o Java 26 tirou um dos casos restantes, a espera pela inicialização de uma classe (post do Java 29).
ThreadLocal deixa de ser cache. 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, e, como elas podem ser muitas, o consumo de memória só aparece sob carga alta (JEP 444). Para propagar contexto (usuário autenticado, trace id, tenant), o substituto é Scoped Values, finalizado no Java 25 (JEP 506; detalhes no post do Java 25).
O disfarce caiu, o problema era antigo. Bulkhead e circuit breaker existem desde 2007 e servem igual aos serviços que continuam com pool de threads; ali a falha só demora mais para aparecer. Se a conclusão da retrospectiva for “circuit breaker é coisa de virtual thread”, ela saiu errada.

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)
OpenJDK — JEP 349: JFR Event Streaming (Java 14)
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, dá nome ao problema (a escrita dupla) e apresenta o desenho que garante que todo efeito externo deixa rastro local: gravar a intenção antes de agir, com tabela outbox, relay e conciliação, com o SQL testado no PostgreSQL. É a continuação de Chave de idempotência.

1. O cenário: a captura passou e o processo morreu

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.

Antes de desenhar qualquer coisa, três perguntas mudam a solução: com que frequência isso acontece, se o adquirente permite consultar o status de uma cobrança depois, e quanto tempo o cliente aceita esperar pela resposta. As respostas definem o tamanho da conciliação, se ela é possível e se a captura pode sair do request.

2. Por que retry e alerta não resolvem

A primeira ideia costuma ser envolver a chamada em try/catch: se a gravação falhar, retry algumas vezes; se ainda assim falhar, log e alerta para o time olhar.

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 anterior 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.

3. O problema tem nome: 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. A forma é sempre a mesma, mude o que mudar de nome: banco mais fila, banco mais cache, banco mais índice de busca, banco mais API de terceiro.

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): um coordenador pergunta a todos os participantes se podem confirmar e só então manda confirmar. Existe e funciona entre recursos que falam o protocolo (o PostgreSQL tem PREPARE TRANSACTION), 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. É 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.

4. Grave a intenção antes de causar o efeito

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ó.

Em SQL, com duas tabelas mínimas:

CREATE TABLE cobranca (
    id              bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    idempotency_key text   NOT NULL UNIQUE,
    valor_centavos  bigint NOT NULL,
    status          text   NOT NULL,   -- PENDENTE, CAPTURADO ou FALHOU
    criada_em       timestamptz NOT NULL DEFAULT now(),
    atualizada_em   timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE outbox (
    id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    tipo         text  NOT NULL,
    payload      jsonb NOT NULL,
    criado_em    timestamptz NOT NULL DEFAULT now(),
    publicado_em timestamptz             -- NULL = ainda não publicado
);

O passo 1 é uma transação com dois INSERTs:

BEGIN;

INSERT INTO cobranca (idempotency_key, valor_centavos, status)
VALUES ('7f3a9c1e-2b4d-4f60-9a71-0c5e8d2b3a44', 25000, 'PENDENTE');

INSERT INTO outbox (tipo, payload)
VALUES ('CobrancaIniciada',
        '{"idempotency_key": "7f3a9c1e-2b4d-4f60-9a71-0c5e8d2b3a44",
          "valor_centavos": 25000}');

COMMIT;

Se o processo cair entre um INSERT e o outro, ou antes do COMMIT, não fica nada: num teste forçando um erro no segundo INSERT, a cobrança do primeiro sumiu junto no rollback. E o passo 3 tem a mesma forma, um UPDATE na cobrança e um INSERT no outbox dentro de BEGIN e COMMIT.

Se o processo cair depois do commit, 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, as duas fora do request.

Relay do outbox

Um processo separado lê a tabela outbox, publica os eventos no broker de mensagens e os marca como enviados:

BEGIN;

SELECT id, tipo, payload
  FROM outbox
 WHERE publicado_em IS NULL
 ORDER BY id
 LIMIT 100
   FOR UPDATE SKIP LOCKED;   -- outro relay em paralelo pega outras linhas

-- publica cada evento no broker

UPDATE outbox
   SET publicado_em = now()
 WHERE id IN (1, 2, 3);       -- os ids do lote publicado

COMMIT;

O SKIP LOCKED permite rodar mais de um relay sem que dois publiquem o mesmo lote: num teste com dois workers ao mesmo tempo, cada um levou três eventos diferentes. Se o relay cair depois de publicar e antes do COMMIT, o lote volta a ficar disponível e é publicado de novo, então a entrega é pelo menos uma vez e quem consome precisa ser idempotente. É o mesmo princípio do post anterior, agora do lado de quem lê. No post sobre W3C Trace Context, o traceparent viaja por esse mesmo outbox.

Conciliação

Um job varre os PENDENTE antigos e pergunta o status ao adquirente:

SELECT id, idempotency_key
  FROM cobranca
 WHERE status = 'PENDENTE'
   AND criada_em < now() - interval '2 minutes'
 ORDER BY criada_em
 LIMIT 100
   FOR UPDATE SKIP LOCKED;

Para cada linha, o job consulta o adquirente pela chave. Se a captura passou, atualiza para CAPTURADO e grava o evento no outbox, na mesma transação; se não passou, marca como falha ou tenta de novo com a mesma chave. Os dois minutos são o prazo que uma cobrança pode ficar sem desfecho antes de alguém perguntar: vêm do tempo normal do request com folga, não de chute. É a rede que pega o que escapou.

O princípio por trás das três peças é o do write-ahead log do banco, em que a mudança é registrada no log antes de ser aplicada, levado para o nível da aplicação. O artigo de Brandur Leach sobre chaves de idempotência formaliza a mesma ideia como fases atômicas com pontos de recuperação. Aparece em upload em duas etapas, emissão de nota fiscal, provisionamento de recurso em nuvem: sempre que a falha precisa deixar rastro em vez de silêncio.

5. Variações: CDC e event sourcing

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. O post Arquitetura de ledger mostra esse modelo, e a conciliação, aplicada a saldos.

6. Decisões que o desenho deixa com você

Relay parado em silêncio. A métrica certa não é “o relay está rodando”, é o atraso: a idade do evento mais antigo não publicado (min(criado_em) onde publicado_em IS NULL), com alerta acima de alguns segundos. Relay vivo com fila crescendo é relay parado.
Quanto tempo um PENDENTE pode ficar. Defina o prazo (minutos, não horas), rode a conciliação em intervalo menor que ele e exponha a contagem de PENDENTE acima do prazo como métrica. Um PENDENTE velho é dinheiro em lugar desconhecido.
O adquirente responde “não sei”. Não adivinhe. A cobrança fica PENDENTE, a consulta se repete com espera crescente e, passado um prazo de negócio, entra a regra combinada: cancelar com a mesma chave, se a API permitir, ou escalar para tratamento manual. O que não pode é virar CAPTURADO ou FALHOU sem confirmação.
A tabela outbox cresce sem parar. Evento publicado é lixo depois de alguns dias: um job apaga (ou move para arquivo) as linhas com publicado_em mais antigo que N dias; em volume alto, particione por dia e solte a partição inteira.
Conciliação como CronJob. Se ela roda como CronJob no Kubernetes, concurrencyPolicy: Forbid evita duas execuções sobrepostas, e o SKIP LOCKED da consulta acima faz com que, mesmo que se sobreponham, cada uma pegue linhas diferentes.
Polling ou CDC. Comece pelo polling: funciona com qualquer banco SQL e sem peça nova. Troque por CDC quando o atraso do intervalo não couber no requisito ou quando as consultas ao outbox pesarem.

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 — SELECT: cláusula de trava (FOR UPDATE SKIP LOCKED)
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

Chave de idempotência — como impedir a 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. Este post mostra onde ela falha e o desenho que funciona: uma chave de idempotência gerada pelo cliente, uma restrição única no banco e a resposta guardada, com SQL testado no PostgreSQL e os cuidados de produção.

1. O que o timeout não diz

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.

Animação: a resposta do serviço se perde no caminho e o app, sem saber, envia o pedido de novo. A animação está no site.

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.

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, e que muda o desenho: o volume, se o cliente controla o reenvio, por quanto tempo a garantia precisa valer e o que acontece se o reenvio vier no dia seguinte.

2. Por que consultar antes de gravar não basta

A primeira ideia que aparece é verificar antes de gravar: 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.

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. Na forma mais geral, é catalogada como TOCTOU (time-of-check to time-of-use, CWE-367), e aparece em reserva de estoque, cadastro por e-mail, débito de saldo e no clássico “verifica se o arquivo existe antes de criar”.

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.

3. 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. A mesma técnica vale para webhooks, APIs públicas de pagamento e comandos consumidos de fila.
Restrição única (UNIQUE) no banco sobre essa chave. É ela que transforma “duas gravações” em “uma gravação e uma recusa”. É 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, o mesmo mecanismo que garante slug de URL, número de matrícula e qualquer regra do tipo “só pode existir um”.
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. Role devagar: a lousa acompanha a leitura e avança um passo a cada parágrafo.

Diagrama: o app, o serviço, o adquirente e a tabela cobranca. A segunda tentativa, com a mesma chave, bate na restrição única e recebe a resposta guardada, sem nova cobrança. O diagrama, passo a passo, está no site.

O app pede a cobrança de R$ 250 e manda junto a chave de idempotência que ele gerou, 5b0e7a52…. A chave é a mesma em todas as tentativas desse pedido.

Antes de cobrar, o serviço grava a chave na tabela cobranca, que tem restrição UNIQUE sobre ela. Quem grava primeiro fica com a chave, e o status começa como PROCESSANDO.

O serviço confirma o registro, cobra no adquirente e guarda a resposta junto da chave: CAPTURADA, com o 201 que devolveu ao app.

A resposta se perde no caminho de volta. Para o app, é como se nada tivesse acontecido, então ele tenta de novo, com a mesma chave.

O INSERT da segunda tentativa bate na restrição UNIQUE. Em vez de cobrar de novo, o serviço devolve a resposta que já estava guardada.

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; qualquer que seja, precisa estar escrito no contrato da API, porque o cliente que reenvia no dia seguinte vai descobrir na prática.
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.

4. O que a restrição única não cobre

A chave resolve o caso em que a decisão cabe numa chave: “esta intenção já foi processada?”. Três situações vizinhas pedem outra ferramenta.

A decisão depende do valor lido. Débito de saldo, controle de estoque, qualquer “leu, calculou, gravou”: não existe chave que expresse “o saldo ainda é o que eu li”. As alternativas são o bloqueio pessimista (SELECT ... FOR UPDATE, que trava a linha e faz os concorrentes esperarem) e o otimista (uma coluna de versão, e só grava quem leu a versão atual). Os dois precisam de uma linha que já exista; aqui 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 ela basta. Os dois são detalhados em Bloqueio otimista e pessimista.
O efeito externo antes do registro. A chave só protege o que chegou a ser gravado. Se a captura no adquirente passar e a gravação da resposta falhar, ou se o processo morrer antes de gravar qualquer coisa, sobra dinheiro cobrado sem registro. O desenho que fecha esse buraco, gravar a intenção antes de causar o efeito, está em Efeito externo sem registro local.
A cobrança vira um evento numa fila. Quando o pedido chega de um tópico em vez de uma chamada síncrona, a repetição é ainda mais certa: a garantia padrão do Kafka, da fila Standard do SQS e do RabbitMQ com confirmações (acks) é entrega pelo menos uma vez (at-least-once). “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, com a mesma tabela e a mesma restrição única deste post, usando o id da mensagem (ou a chave que veio dentro dela) como chave de idempotência. É por isso que idempotência e mensageria andam juntas.

5. Regra prática

A mesma falha de rede, com e sem a chave de idempotência. Avance no tempo e compare as duas linhas.

Linha do tempo comparando o reenvio com e sem chave de idempotência: sem a chave, o cliente é cobrado duas vezes; com a chave, a restrição única devolve a resposta guardada. A linha do tempo interativa está no site.

A chave é gerada pelo cliente, uma por intenção, e repetida em todas as tentativas dessa intenção. Id de pedido só serve se o pedido só puder ser cobrado uma vez.
Quem decide é o banco: UNIQUE na chave e INSERT ... ON CONFLICT DO NOTHING RETURNING antes de qualquer efeito externo. Nunca “consulta, depois grava”.
Confirme o registro antes de chamar o adquirente; a chamada externa fica fora da transação.
A primeira resposta fica guardada e é devolvida igual nas repetições; parâmetros diferentes com a mesma chave são recusados.
O prazo da chave e o tratamento de erro são decisões de contrato: escolha, documente e meça o armazenamento.

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.

Apresentação em slides, no site.

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

Como o Spring aplica log, transação e métricas fora da regra de negócio: conceitos de AOP, JDK Dynamic Proxy ou CGLIB (e por que o Boot prefere CGLIB), a self-invocation e aspects próprios.

AopUtils.getTargetClass() — desembrulhando os proxies do Spring

Tue, 19 May 2026 00:00:00 GMT

Com o bean envolto em proxy, bean.getClass() devolve a classe do proxy e a leitura de anotações falha. Como AopUtils.getTargetClass() recupera a classe real e quando usar ultimateTargetClass().

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.