Serviço de cadastro de usuários com envio de e-mail de boas-vindas, construído sobre o Transactional Outbox Pattern para garantir entrega consistente do e-mail sem depender de transações distribuídas entre banco de dados e AWS.
Stack:
- Java 21
- Spring Boot 3 (Web, Data JPA, Validation)
- PostgreSQL
- Debezium (Embedded Engine) para CDC — Change Data Capture
- AWS SES para o envio do e-mail de boas-vindas
- Lombok
O caso de uso é simples: ao cadastrar um usuário, o sistema precisa enviar um e-mail de boas-vindas. O ponto central deste serviço é como essa notificação é entregue de forma confiável, resolvendo o problema da dupla escrita (dual write problem) que aparece sempre que uma mesma operação de negócio precisa atualizar o banco de dados e chamar um serviço externo (aqui, o SES).
Uma implementação "ingênua" do cadastro de usuário faria algo assim:
userRepository.save(user); // 1) grava no Postgres
sesClient.sendEmail(...); // 2) chama a AWS diretamenteO problema é que são duas operações contra dois sistemas diferentes, sem nenhuma garantia atômica entre elas:
- Se o processo cair, ou a rede falhar, ou o SES estiver fora do ar depois do passo 1 e antes/durante o passo 2, o usuário fica cadastrado e nunca recebe o e-mail — e não há como saber que isso aconteceu, pois do ponto de vista do banco a transação foi um sucesso.
- Se você inverter a ordem (enviar o e-mail primeiro), corre o risco inverso: o usuário recebe o e-mail de boas-vindas para um cadastro que acabou não sendo persistido (ex.: violação de constraint, rollback etc.).
Não existe transação distribuída de verdade entre "commit no Postgres" e "chamada HTTP para a AWS" — por isso o nome dual write: duas escritas que deveriam ser atômicas, mas não são.
Em vez de chamar o SES diretamente dentro da mesma requisição, o serviço grava dois registros na mesma transação de banco de dados:
- a linha na tabela
users; - um "evento" na tabela
outbox_users, descrevendo o que precisa acontecer depois (NEW_USER_REGISTERED, com o payload necessário para montar o e-mail).
@Transactional
public User registerUser(CreateUserRequest request) {
User user = userRepository.save(...);
outboxEventRepository.save(outboxEvent); // mesma transação
return user;
}Como as duas tabelas fazem parte da mesma transação do Postgres, ou as duas linhas existem, ou nenhuma existe — a atomicidade que faltava entre "banco" e "efeito colateral" passa a existir entre "banco" e "banco".
O envio do e-mail em si deixa de ser responsabilidade da requisição HTTP. Quem cuida disso é um processo assíncrono e desacoplado, que só existe depois que a transação já foi confirmada com sucesso:
Service --> Postgres (transação: INSERT users + INSERT outbox_users)
|
v
WAL (write-ahead log)
|
v
Debezium (lê o WAL via replicação lógica)
|
v
Outbox Consumer (nossa aplicação)
|
v
AWS SES --> e-mail entregue
Uma alternativa mais simples seria ter um job que faz
SELECT * FROM outbox_users WHERE status = 'PENDING' de tempos em tempos.
Funciona, mas tem dois problemas: gera carga extra no banco o tempo todo
(mesmo quando não há nada novo) e introduz atraso proporcional ao intervalo
do polling.
O Debezium, em vez de "perguntar" ao banco se há novidade, se conecta como
um réplica lógica do Postgres e é notificado assim que uma
transação com um INSERT em outbox_users é confirmada — sem select,
sem polling, com latência mínima. Ele lê diretamente o WAL
(write-ahead log), o mesmo mecanismo que o Postgres usa para replicação
física.
Neste serviço o Debezium roda como uma Embedded Engine — ou seja,
dentro do próprio processo Java, sem precisar de Kafka Connect nem de um
broker de mensagens dedicado (classe OutboxDebeziumConsumer).
A versão atual roda com Debezium Embedded Engine no mesmo processo da API, o que já resolve o problema de dupla escrita e atende bem a um volume moderado de eventos. Para cargas maiores ou múltiplos serviços consumindo os mesmos eventos, a evolução natural é:
| Atual | Próximo passo |
|---|---|
| Debezium Embedded Engine, no mesmo processo da API | Debezium Server ou Kafka Connect, publicando em um tópico Kafka |
| Consumidor chama o SES diretamente ao receber o evento | Serviço consumidor dedicado, lendo do Kafka, desacoplado da API |
Offset da leitura salvo em arquivo local (outbox-offsets.dat) |
Offset gerenciado pelo próprio Kafka Connect / tópico de offsets |
| Sem deduplicação explícita de e-mail enviado | Consumidor idempotente (chave de deduplicação, tabela de eventos já processados) |
Vale reforçar: o Debezium entrega os eventos com garantia at-least-once
(pelo menos uma vez) — ou seja, o mesmo evento pode, em cenários de falha e
reprocessamento, ser entregue mais de uma vez. Por isso o consumidor deve
ser tratado como idempotente (checar se aquele outbox_id já foi
processado antes de reenviar o e-mail). O campo status da tabela
outbox_users já dá a base para essa checagem.
outbox-notifier/
├── docker-compose.yml # sobe só o Postgres (wal_level=logical)
├── postgres/init.sql # cria as tabelas users e outbox_users
├── pom.xml
└── src/main/
├── resources/application.yml
└── java/com/example/outbox/
├── OutboxDemoApplication.java
├── config/
│ ├── SecurityBeansConfig.java # bean do PasswordEncoder
│ └── AwsSesConfig.java # SesClient apontando pro LocalStack
├── domain/
│ ├── User.java
│ └── OutboxEvent.java # mapeia outbox_users
├── repository/
│ ├── UserRepository.java
│ └── OutboxEventRepository.java
├── dto/CreateUserRequest.java
├── service/UserService.java # @Transactional: grava user + outbox juntos
├── controller/UserController.java # POST /api/users
└── outbox/
├── OutboxDebeziumConsumer.java # lê o WAL via Debezium Embedded Engine
└── WelcomeEmailSender.java # envia o e-mail via SES
- JDK 21
- Docker e docker-compose
- Uma IDE com suporte a Maven (IntelliJ IDEA, por exemplo)
- Credenciais AWS com permissão de uso do SES (ou LocalStack, em ambiente local)
Para desenvolver e validar o fluxo sem depender de custos ou limites reais
do SES, use o LocalStack como substituto
local da AWS — é o que o application.yml já assume por padrão
(aws.ses.endpoint: http://localhost:4566, credenciais fake test/test).
Na raiz do projeto:
docker-compose up -dIsso cria o container outbox-postgres, já com wal_level=logical e as
tabelas users e outbox_users (via postgres/init.sql).
awslocal ses verify-email-identity --email-address no-reply@outbox-demo.comAbra o projeto na sua IDE (pom.xml como projeto Maven), deixe o Maven
baixar as dependências e rode a classe OutboxDemoApplication.
Ao subir, além do Spring Boot, a OutboxDebeziumConsumer inicializa a
engine do Debezium e começa a observar public.outbox_users.
Cadastre um usuário:
curl -X POST http://localhost:8080/api/users \
-H "Content-Type: application/json" \
-d '{"name":"Joao Silva","email":"joao@gmail.com","password":"123456"}'O que deve acontecer, em sequência:
- A API responde
201 Createdcom o usuário criado. - Nos logs da aplicação:
Usuário X e evento de outbox gravados na mesma transação. - Alguns instantes depois (assíncrono):
Evento de outbox capturado: ...eE-mail de boas-vindas enviado para joao@gmail.com. - Consultando o Postgres, a linha em
outbox_usersestará comstatus = 'SENT'.
Para apontar para o SES de verdade, basta sobrescrever as propriedades de
aws.* (via variáveis de ambiente, application-prod.yml ou secrets do
seu orquestrador — nunca comitando credenciais):
aws:
region: us-east-1
ses:
endpoint: https://email.us-east-1.amazonaws.com
sender: no-reply@seudominio.comPontos de atenção antes de ir para produção:
- Credenciais: troque
StaticCredentialsProvider(usado hoje para simplificar o dev local) porDefaultCredentialsProvider, permitindo o uso de IAM Role da instância/task em vez de chaves fixas. - Verificação de domínio: no SES real, verifique o domínio remetente (ou o endereço específico) e, se a conta estiver em sandbox do SES, solicite a saída do sandbox para poder enviar a qualquer destinatário.
- Réplica lógica no Postgres gerenciado: se o banco for RDS/Aurora,
confirme que
rds.logical_replicationestá habilitado e que o usuário de conexão tem permissão de replicação.
outbox_usersestá comREPLICA IDENTITY FULL: isso instrui o Postgres a incluir a linha inteira nos eventos de WAL — prática recomendada pela documentação do Debezium para tabelas de outbox.- O
ddl-autodo Hibernate está comononede propósito: quem define o schema é opostgres/init.sql, garantindo que a configuração de replicação da tabela não seja perdida numa recriação automática.