Índice do curso
Lição 08 — O router
Por Dorian Chávez · cofundador e Chief Executive Officer da Hábil ·
O que será alcançado: dividir a integração em dois serviços que rodam separados: um router que recebe o pedido e um serviço int-rest que sabe falar com a API. Escreve-se a chamada que os une, pelo nome do serviço e nunca por um endereço.
Antes de começar é preciso ter: as lições 02 a 07 concluídas e o ambiente da 00 ligado:
docker compose -f infra/compose.yaml up -d --wait # desde la carpeta raíz de la práctica
A novidade de hoje, em uma frase
Até agora cada lição era uma rota que fazia tudo: receber, traduzir e entregar. Com três destinos (a API, o ERP e o parceiro), essa rota cresceria sem parar. Hoje ela é dividida: um serviço decide para onde vai o pedido e outro sabe entregá-lo. Cada um roda no próprio contêiner.
tienda ──POST /ordenes──▶ [orden-router] ──POST http://int-rest:8080/integrar──▶ [int-rest] ──▶ API de pedidos
A imagem: a recepção de um hospital. A recepcionista não opera ninguém: pergunta qual é o problema e encaminha para o especialista. Se amanhã abrir uma especialidade nova, a recepção continua igual; só aprende uma porta a mais.
1. Prepare a pasta
cd lecciones/08-el-router
cp -R inicio mio
Veja o que foi copiado: mio/ tem duas pastas, uma por serviço.
| Pasta | Serviço | O que traz |
|---|---|---|
mio/orden-router/ |
O router | A rota dele: recebe o pedido da loja e o passa para o int-rest |
mio/int-rest/ |
int-rest | A rota dele e o mapeamento v2 da lição 03: traduz o pedido e o entrega à API |
2. Leia o compose da lição
Esta lição não usa herramientas/camel. Os dois serviços sobem juntos com um compose.yaml próprio, como o
ambiente da lição 00. Abra-o:
x-camel: &camel
image: apache/camel-jbang:4.22.1
command: ["run", "."] # corre todos los *.camel.yaml de su carpeta
services:
orden-router:
<<: *camel
volumes:
- ./${DONDE:-mio}/orden-router:/work
ports: ["8080:8080"]
int-rest:
<<: *camel
volumes:
- ./${DONDE:-mio}/int-rest:/work
# sin ports: no se ve desde tu máquina; por dentro de la red, cualquier servicio lo alcanza
Duas coisas que vale a pena ver:
- Os dois serviços são a mesma imagem do Camel. A única diferença é a pasta que cada um monta.
&cameldefine a parte comum uma vez e<<: *camela reutiliza. Para criar um serviço novo não é preciso programar outro programa: basta outra pasta com as rotas dela. - Só o router tem
ports. É o único que se vê a partir da máquina. O int-rest não se vê de fora, mas dentro da rede do Docker qualquer serviço pode chamá-lo; neste curso, o único que o chama é o router.
DONDE é uma variável que diz que pastas montar: mio (a própria, por padrão) ou solucion (a nossa).
3. Leia as duas rotas
mio/int-rest/int-rest.camel.yaml já vem completa. Recebe em /integrar, traduz com o mapeamento v2 e chama
a API, igual à rota da lição 03.
mio/orden-router/orden-router.camel.yaml recebe em /ordenes e prepara o pedido para passá-lo adiante. Antes da
chamada coloca nele alguns cabeçalhos que começam com ce-:
| Cabeçalho | Valor para o pedido 1003 |
|---|---|
ce-specversion |
1.0 |
ce-type |
mx.tienda.orden.creada |
ce-source |
/tiendas/T-022 |
ce-subject |
1003 |
ce-id |
orden-1003-creada |
São o envelope do pedido, em um formato padrão que se chama CloudEvents: dizem o que aconteceu, onde e com quem. Hoje eles só serão vistos viajando; na lição 09 servem para acompanhar um pedido de serviço em serviço.
No fim da rota há um TODO: falta a chamada ao int-rest.
4. Faça a previsão
Antes de escrever a chamada, responda em um papel:
- Se o pedido 1003 for enviado ao router tal como está, sem a chamada, o que ele responde à loja? Chega algo à API?
- Quando a chamada já estiver lá, em que ordem se espera ver o pedido passar pelos logs dos dois serviços?
- Dentro do contêiner do router, para que máquina
localhostdeve apontar?
5. Escreva a chamada
No lugar do TODO, acrescente um passo to que faça um POST na rota /integrar do int-rest, na porta 8080 dele.
Chame-o pelo nome de serviço, int-rest, como o int-rest chama a API por api-pedidos. Use
throwExceptionOnFailure: false para que, se o int-rest responder com erro, o router o anote em vez de falhar:
a linha seguinte do log diz o que ele respondeu.
Se travar, a chamada do int-rest à API tem exatamente a mesma forma.
6. Suba os serviços e mande um pedido
A partir da pasta da lição:
DONDE=mio docker compose -f compose.yaml up -d
DONDE=mio docker compose -f compose.yaml logs -f
O segundo comando mostra os logs dos dois serviços juntos, cada linha com o nome de quem a escreveu.
Espere até ver Started orden-router e Started int-rest. Em outro terminal, a partir da raiz do curso:
curl -i -XPOST localhost:8080/ordenes -H 'Content-Type: application/json' -d @datos/ordenes/orden-1003.json
Nos logs deve aparecer o pedido passando pelos dois serviços:
orden-router-1 | Orden 1003: se la paso a int-rest
int-rest-1 | Recibí del router la orden 1003 (sobre orden-1003-creada, tipo mx.tienda.orden.creada)
int-rest-1 | La API contestó 201 para la orden 1003
orden-router-1 | Orden 1003: int-rest contestó 201
Coincide com a previsão 2? A resposta volta pelo mesmo caminho: a API responde ao int-rest, o int-rest ao router e o router à loja.
Se a API responder 200 em vez de 201, ela já tinha o pedido 1003 da lição 03. Reinicie-a para que comece vazia:
docker compose -f infra/compose.yaml restart api-pedidos.
7. Quebre de propósito: localhost
Agora a pergunta 3. Na rota do router, troque int-rest por localhost:
uri: http://localhost:8080/integrar
Desligue e suba de novo os serviços para que peguem a mudança, e mande o pedido outra vez:
DONDE=mio docker compose -f compose.yaml down
DONDE=mio docker compose -f compose.yaml up -d
A loja recebe um 404 e o log do router diz int-rest contestó 404. Mas o int-rest nunca recebeu nada.
Dentro de um contêiner, localhost é esse mesmo contêiner. O router chamou a si mesmo, procurou uma rota
/integrar que ele não tem e respondeu a si mesmo «não existe». Na máquina de quem faz a lição, localhost é essa máquina; em cada contêiner,
é o contêiner.
Por isso os serviços se chamam pelo nome: o Docker sabe em que contêiner vive o int-rest, mesmo que amanhã
ele mude de endereço. Devolva o nome e desligue:
DONDE=mio docker compose -f compose.yaml down
8. Confira
./verifica
O verifica reinicia a API para que comece vazia, sobe os dois serviços, manda o pedido 1003 e no fim os
desliga. Está concluída quando aparecem as seis marcas verdes:
✅ El router arrancó
✅ int-rest arrancó (la misma imagen, otra carpeta)
✅ La tienda mandó la 1003 al router y la respuesta final fue 201
✅ La API registró la orden 1003: el recorrido tienda → router → int-rest → API se completó
✅ int-rest recibió el sobre CloudEvents de la orden (id orden-1003-creada)
✅ int-rest no se ve desde tu máquina: solo el router lo alcanza
A quarta quem confirma é a API, a partir do próprio registro: não basta o router dizer que passou o pedido.
Não roda? ./verifica solucion testa a nossa, e
diff mio/orden-router/orden-router.camel.yaml solucion/orden-router/orden-router.camel.yaml mostra em que são
diferentes.
| O que aparece | O que fazer |
|---|---|
La tienda esperaba 201 y le llegó 200 |
O router devolveu o pedido sem chamar ninguém: falta o passo to |
La tienda esperaba 201 y le llegó 404 |
A chamada aponta para localhost: volte ao passo 7 |
El puerto 8080 está ocupado |
Ficou outra rota rodando, ou os serviços desta lição: DONDE=mio docker compose -f compose.yaml down |
El router no arrancó |
O verifica mostra as últimas linhas do log: quase sempre é a indentação do passo novo |
Exercício: um especialista a mais
Sem escrever código, responda em um papel: para ter amanhã um serviço int-erp que entregue o pedido ao ERP
com a rota da lição 05, que pasta seria criada, o que iria nela e que linhas seriam acrescentadas ao compose.yaml?
Ele teria ports? O que mudaria no router?
Por que foi feito assim
O que decidimos nesta lição, com o que descartamos e o que nos faria mudar de ideia:
- Uma única imagem; cada serviço é uma pasta
- Os serviços se falam pelo nome, sobre HTTP
- CloudEvents em modo binário como envelope
Revisão
- O que faz o router e o que faz o int-rest? Por que convém separá-los?
- Se os dois serviços usam a mesma imagem, o que os torna diferentes?
- Por que o router chama
int-reste nãolocalhost? - Por que o int-rest não tem
portsno compose? - O que dizem os cabeçalhos
ce-type,ce-subjectece-iddo pedido 1003?
A seguir: na lição 09 acompanha-se um pedido de serviço em serviço com o envelope CloudEvents, e descobre-se o que acontece quando um serviço não o reenvia.
Prefere e-mail? Escreva para hola@habil.mx