Índice do curso
Lição 30 — Não perder ao publicar
Por Dorian Chávez · cofundador e Chief Executive Officer da Hábil ·
O que será alcançado: fechar a última brecha do curso. Se o Kafka está fora do ar justo quando chega um pedido, o pedido é guardado, a loja recebe o
202e, quando o Kafka volta, o pedido sai sozinho para os três canais dele, sem que ninguém faça um rerun.
Antes de começar é preciso ter: as lições 17 e 29 concluídas, o ambiente da 00 ligado e o Kafka no ar
(docker compose -f infra/compose.yaml --profile kafka up -d --wait).
A novidade de hoje, em uma frase
Desde a lição 28 o router faz duas coisas seguidas: guarda o pedido na base de estado e depois publica o
evento no Kafka. São dois sistemas diferentes, e nenhuma transação abrange os dois. Se o Kafka está fora do ar nesse
instante, o pedido ficou guardado e a loja já tem o 202, mas o evento não saiu, e ninguém volta a
tentar. Ao contrário também não serve: publicar antes de guardar deixa um evento de um pedido que, se a base falhar, não
existe. Hoje o router guarda o que é preciso publicar na mesma transação do pedido, em uma tabela chamada
outbox, e uma sondagem o publica quando o Kafka pode recebê-lo. O padrão se chama Transactional Outbox.
A imagem: a bandeja de «a enviar» de um escritório. Quem atende o cliente não sai correndo para a transportadora com cada envelope: preenche o formulário e, no mesmo instante, deixa o envelope na bandeja. O mensageiro passa de tempos em tempos e leva o que houver. Se um dia a transportadora está fechada, os envelopes ficam na bandeja, não no bolso de alguém, e saem quando ela abrir.
antes: guardar (transacción) → 202 → publicar en Kafka ← si Kafka está caído aquí, se pierde
hoy: guardar orden + operaciones + outbox (UNA transacción) → 202
cada 1 s: outbox pendiente → publicar → ¿Kafka lo recibió? sí → «publicado» · no → espera la siguiente vuelta
1. Prepare a pasta
cd lecciones/30-no-perder-al-publicar
cp -R inicio mio
Abra infra/postgres/01-estado.sql e procure CREATE TABLE outbox: cada linha aponta para uma operacion e tem uma
coluna publicado, vazia até que o Kafka tenha recebido o evento.
A sondagem já está feita: é a rota sondeo-outbox de mio/orden-router/reparto.camel.yaml. Leia-a. A cada segundo
ela pega o que está pendente na ordem em que entrou e, se algo não sai, o que vem depois espera a volta seguinte
(stopOnException): assim o que é de um mesmo pedido não sai fora de ordem. A varredura da lição 17 já deixa no outbox o que
libera.
O trabalho fica em dois arquivos:
| TODO | Arquivo | O que fazer |
|---|---|---|
| 1 | mio/orden-router/estado.camel.yaml |
Ao guardar um pedido novo, deixar no outbox uma linha para cada operação (evento do ciclo de vida creada) |
| 2 | O mesmo | Ao guardar um evento novo (embarque, entrega), o mesmo para as operações que nasceram pendiente |
| 3 | mio/orden-router/orden-router.camel.yaml |
Tirar o envio direto a seda:repartir: a partir de hoje, só o outbox publica |
2. Faça a previsão
Responda em um papel:
- Com a versão da lição 29, o Kafka está fora do ar e chegam o 4002 e o 4003. A loja recebe o
202? Quantas linhas há no outbox? O que acontece com os pedidos quando o Kafka volta? - Por que a linha do outbox tem de ser escrita na mesma transação da operação, e não logo depois?
- Se o envio direto ficar e além dele houver o outbox, o que acontece com cada evento? A API o criaria duas vezes?
Veja como está hoje:
./verifica inicio
Com o Kafka fora do ar, o router guarda os dois pedidos e responde 202, mas o outbox fica vazio. Quando o Kafka
volta, as 6 operações continuam pendentes: ninguém volta a mandá-las.
3. A bandeja de «a enviar»
TODO 1: o pedido novo
Em mio/orden-router/estado.camel.yaml procure o TODO 1. Está dentro da transação que guarda o pedido e as
operações dele. Ali mesmo, um INSERT … SELECT deixa uma linha para cada operação que acaba de ser guardada:
- to:
uri: "sql:INSERT INTO outbox (operacion) SELECT id FROM operacion WHERE orden = :#${variable.orden} AND momento = 'creada' ORDER BY id"
parameters:
dataSource: "#estado"
O ORDER BY id faz as linhas entrarem na ordem em que as operações nasceram, e a sondagem publica nessa
ordem.
TODO 2: um evento novo
Mais abaixo, na mesma transação que guarda o embarque ou a entrega, o TODO 2. É o mesmo INSERT, com duas
diferenças:
| TODO 1 | TODO 2 | |
|---|---|---|
| Que evento | 'creada' |
:#${variable.momento} |
| Que operações | Todas | Só as que nasceram pendiente: AND estado = 'pendiente' |
Por que só as pendentes? Porque as estacionada (lição 17) ainda não podem sair. Essas quem deixa no outbox é a
varredura, quando as libera.
TODO 3: um único caminho
Em mio/orden-router/orden-router.camel.yaml, na rota contestar-y-repartir, tire o passo to: seda:repartir.
Se ele ficar, cada evento sai por dois caminhos: o direto e o outbox. A API o reconheceria pela chave (lição 18),
mas cada canal receberia dois eventos e o router anotaria duas tentativas. Um único caminho é mais fácil de explicar e de
rastrear.
4. Quebre um de propósito
Com a versão própria concluída, apague o INSERT do TODO 1 e rode ./verifica.
Antes, faça a previsão: o Kafka está no ar no começo. O 4001 chega?
Não. O verifica para na segunda marca: o 4001 não chega a nenhum dos canais dele. O envio
direto já foi tirado (TODO 3), então o outbox é o único caminho, e um pedido que não deixa a própria linha ninguém publica. Antes
do outbox, «o Kafka está no ar» bastava; agora o que manda é a linha guardada. Devolva-o.
5. Confira
./verifica
O verifica manda o 4001 com tudo no ar, para o Kafka, manda o 4002 e o 4003, confere o outbox e a API
durante alguns segundos, volta a subir o Kafka e espera que tudo saia. Está concluída quando aparecem as oito marcas
verdes:
✅ Arrancaron el router, los tres canales con su puente y el sondeo
✅ La 4001 llegó a sus tres canales
✅ Con Kafka caído, el router guardó la 4002 y la 4003 y contestó 202 a las dos
✅ En el outbox esperan 6 filas sin publicar, una por operación de la 4002 y la 4003
✅ Control: mientras Kafka está caído, la API no tiene ninguna de las dos
✅ Kafka volvió y lo guardado salió solo: la API, el ERP y el socio tienen la 4002 y la 4003
✅ En la API se creó cada una UNA vez (2 creaciones para 2 órdenes)
✅ El outbox quedó sin pendientes: todo lo que se guardó, salió
A quinta é um controle: se com o Kafka fora do ar a API já tivesse os pedidos, a sexta marca não provaria que o outbox os tirou de lá.
Veja o outbox à mão, com os serviços no ar:
docker compose -f ../../infra/compose.yaml exec estado psql -U router -d estado \
-c "SELECT x.id, p.orden, p.canal, x.publicado FROM outbox x JOIN operacion p ON p.id = x.operacion ORDER BY x.id"
Não roda? ./verifica solucion testa a nossa, e diff -r mio solucion mostra em que são diferentes.
| O que aparece | O que fazer |
|---|---|
A la base de estado le falta la tabla outbox |
A base é de antes da lição 30: recrie-a com o comando que a mensagem traz (--force-recreate -V estado) |
La 4001 no llegó a sus tres canales |
Falta o TODO 1: com o TODO 3 feito, sem linha no outbox não se publica nada |
En el outbox esperaba 6 filas sin publicar … y hay 0 |
O INSERT do TODO 1 não roda: confira que esteja dentro da transação, depois de guardar as operações |
Kafka volvió y lo guardado no salió |
Veja que canal ficou em que estado (a mensagem diz) e confira a rota sondeo-outbox no log do router |
En la API hubo … creaciones para 2 órdenes |
A API criou algum duas vezes: a chave que o int-rest manda para ela foi alterada? (lição 18) |
El outbox tiene … filas sin publicar |
Algo ficou travado: confira o log do router, embaixo de sondeo-outbox |
El puerto 8080 está ocupado |
Os serviços de outra execução ficaram no ar: DONDE=mio docker compose -f compose.yaml down |
O que isto ensina fora do curso
Dois sistemas não compartilham uma transação. A base e o Kafka confirmam cada um o que é dele. Se uma ação tem de ficar nos dois, guarda-se em um só (a base, com o pedido) e o outro é alimentado a partir dali.
O que foi guardado é o que sai. A sondagem publica o que o outbox diz, lendo a base. Se o router é reiniciado na metade, a linha continua ali.
Publicar a mais se tolera; publicar a menos, não. Se o router cai na metade do envio, ou depois de
publicar e antes de marcar publicado, a linha sai outra vez. Por isso quem lê tem de reconhecer repetidos (lições 18 e 29). Perder um evento, ao contrário,
ninguém nota até que um cliente reclame.
Um único caminho. Manter o envio direto «por via das dúvidas» junto ao outbox duplica tudo e não conserta nada: o outbox já cobre o caso em que o Kafka está no ar.
Exercício: a bandeja
- Pare o Kafka com os serviços no ar, mande um pedido e rode a consulta do passo 5. O que diz a coluna
publicado? Suba o Kafka e rode-a de novo. - Em papel: o router guardou o pedido e a linha dele no outbox, a sondagem a publicou e o router caiu antes de marcar
publicado. O que acontece na volta? Que peça evita que a API o crie duas vezes? - Faça uma lista das formas de perder um pedido vistas no curso (a loja que não recebe o
202, o ERP fora do ar, o 997 que não chega, o evento confirmado sem desfecho…). Ao lado de cada uma, a lição que a fecha.
Por que foi feito assim
O que decidimos nesta lição, com o que descartamos e o que nos faria mudar de ideia:
- O que é preciso publicar é guardado na mesma transação (outbox), e uma sondagem o publica
Revisão
- Que brecha fica entre guardar e publicar, e por que ela não se resolve publicando primeiro?
- O que a tabela
outboxguarda, e em que transação ela é escrita? - Por que o TODO 2 deixa de fora as operações
estacionada? - O que aconteceria se o envio direto ficasse junto ao outbox?
- A pergunta de encerramento: uma loja manda um pedido com o Kafka fora do ar. Conte, passo a passo, o que acontece desde o
202até que o parceiro tenha o 850 dele, e em que tabelas fica a trilha.
A seguir: com esta lição termina o curso em Docker Compose. Se a equipe trabalha com Kubernetes ou quer ver a integração sem contêineres, o apêndice (lições 31 e 32) é de leitura e é opcional.
O que a Hábil faz
Ao concluir este curso:
- um aviso repetido não duplica nada;
- se não se sabe se algo chegou, fica pendente de conciliar em vez de ser dado por falho;
- o que foi depositado não é dado por confirmado até que o parceiro confirme o recebimento;
- um canal fora do ar não freia os demais;
- cada destino recebe só as chamadas que aguenta;
- cada pedido pode ser acompanhado sem mostrar dados pessoais.
Em uma empresa, isto costuma soar assim: «Não sabemos se essa operação chegou. Tenta-se de novo à mão, e às vezes duplica». E há falhas que não marcam erro: o envio saiu, mas a resposta nunca chegou.
Na Hábil construímos sob medida a integração entre a loja, o ERP, os parceiros e os canais da empresa. Hábil MDW foi projetada para operar 24/7, com trilha de auditoria de cada operação: o que foi mandado a cada sistema, o que ele respondeu, a que horas e, se falhou, por quê. Cada envio fica com a resposta ou com o motivo da falha, e as novas tentativas são projetadas para não repetir o efeito. Um envio que saiu errado é tentado de novo pela equipe de operação da empresa como um envio novo, com trilha de quem o fez e sem mexer no banco de dados à mão.
Prefere e-mail? Escreva para hola@habil.mx