Modulo-6 / documentation /integrations /M10_integration.md
juampisor's picture
Organizacion de documentacion
3ac37aa
|
Raw History Blame Contribute Delete
14.3 kB

Tutorial: Comunicacion entre microservicios

Esta guia va al grano: como conectar microservicios usando el Core como punto de configuracion y publicacion.

La idea, cortita y al pie ( • ̀ω•́ )✧:

  • Las colas se crean desde el Core.
  • Los eventos se crean desde el Core.
  • Los bindings entre eventos y colas se hacen desde el Core.
  • Los microservicios escuchan sus propias colas de respuesta en RabbitMQ.
  • Los microservicios publican mensajes llamando al Core.

Regla mental: RabbitMQ para escuchar; Core para configurar y publicar. Asi evitamos colas creadas a mano y bindings fantasma. ദ്ദി ˉ͈̀꒳ˉ͈́ )✧

Conceptos

Requests

Una request es un pedido que un microservicio le manda a otro.

Ejemplo:

appointments le pide a billing que cree una factura.

Responses

Una response es la respuesta a una request anterior.

Ejemplo:

billing le responde a appointments que la factura fue creada.

Correlation ID

Si una request espera respuesta, agreguen un correlation_id.

La response tiene que devolver ese mismo correlation_id.

Sirve para que quien hizo la request pueda saber a que pedido corresponde la respuesta.

Ejemplo de request:

{
  "correlation_id": "9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45",
  "patient_id": 123,
  "appointment_id": 987
}

Grafico del flujo

sequenceDiagram
    participant A as Appointments
    participant Core as Core API
    participant Rabbit as RabbitMQ
    participant B as Billing

    A->>Core: Crea cola appointments.responses
    A->>Core: Crea evento de response
    B->>Core: Crea cola billing.requests
    B->>Core: Crea evento de request
    A->>B: Comparte response_event_id
    B->>A: Comparte request_event_id
    A->>Core: POST /events/log request + correlation_id + response_event_id
    Core->>Rabbit: Publica request en health_grid_exchange
    Rabbit->>B: Entrega mensaje en billing.requests
    B->>B: Procesa request
    B->>Core: POST /events/log response + mismo correlation_id
    Core->>Rabbit: Publica response
    Rabbit->>A: Entrega mensaje en appointments.responses
    A->>A: Relaciona response usando correlation_id

1. Configurar cliente RabbitMQ ₍ ᐢ.ˬ.ᐢ₎

Cada microservicio recibe credenciales RabbitMQ con permisos limitados.

Ejemplo:

RABBITMQ_HOST=localhost
RABBITMQ_PORT=5672
RABBITMQ_USER=admin@admin.com
RABBITMQ_PASSWORD=123123
RABBITMQ_VHOST=/

Si arman una URL AMQP, el @ del email tiene que ir escapado como %40:

amqp://admin%40admin.com:123123@localhost:5672/

El microservicio usa RabbitMQ solo para escuchar sus colas.

2. Login en el Core

Todos los endpoints del Core usan JWT.

Primero obtener token:

POST /auth/login
Content-Type: application/json

{
  "email": "user@mail.com",
  "password": "1234"
}

Usar el token devuelto:

Authorization: Bearer <token>

3. Crear colas desde el Core

Endpoint:

POST /rabbit/queues
Authorization: Bearer <token>
Content-Type: application/json

El Core agrega automaticamente el sufijo:

  • requests crea <queue_name>.requests
  • responses crea <queue_name>.responses

Tambien crea la DLQ:

  • <queue_name>.requests.dlq
  • <queue_name>.responses.dlq

Si el microservicio recibe requests

Crear una cola de requests:

{
  "queue_name": "billing",
  "queue_type": "requests"
}

Resultado:

{
  "queue_name": "billing.requests",
  "queue_type": "requests",
  "dlq_name": "billing.requests.dlq",
  "rabbit_username": "user@mail.com"
}

Si el microservicio espera responses

Crear una cola de responses:

{
  "queue_name": "appointments",
  "queue_type": "responses"
}

Resultado:

{
  "queue_name": "appointments.responses",
  "queue_type": "responses",
  "dlq_name": "appointments.responses.dlq",
  "rabbit_username": "user@mail.com"
}

4. Crear eventos desde el Core

Endpoint:

POST /events/types
Authorization: Bearer <token>
Content-Type: application/json

Evento para requests

Crear este evento si otros microservicios tienen que mandarle requests a tu servicio.

Este evento lo crea el microservicio que recibe la request.

Ejemplo: billing recibe pedidos para crear facturas, entonces billing crea:

{
  "name": "billing.invoice.create.requested",
  "description": "Request para que billing cree una factura",
  "source_module": "billing"
}

Guardar el id devuelto. Ese es el event_type_id que otros microservicios usaran para pedirle cosas a billing.

Evento para responses

Crear este evento si tu servicio hizo una request y necesita recibir una response.

Ejemplo: appointments le pide a billing que cree una factura y quiere recibir respuesta. Entonces appointments crea:

{
  "name": "billing.invoice.create.responded",
  "description": "Response de billing para la creacion de factura",
  "source_module": "appointments"
}

Guardar el id devuelto. Ese ID se comparte con billing y tambien viaja en la request como response_event_id.

Mini resumen:

Recibo requests: creo el evento request.
Espero responses: creo el evento response.
Proceso requests: NO creo el evento response; uso el response_event_id recibido.

5. Vincular eventos con colas

Endpoint:

POST /rabbit/bindings
Authorization: Bearer <token>
Content-Type: application/json

Bind de requests

Si billing recibe requests, bindear el evento request con la cola billing.requests:

{
  "event_id": 10,
  "queue_name": "billing.requests"
}

Desde ese momento, todo mensaje publicado al evento 10 llega a billing.requests.

Bind de responses

Si appointments espera responses, bindear el evento response con la cola appointments.responses:

{
  "event_id": 11,
  "queue_name": "appointments.responses"
}

Desde ese momento, toda respuesta publicada al evento 11 llega a appointments.responses.

6. Escuchar una cola

El microservicio escucha su cola directamente en RabbitMQ.

Ejemplo conceptual:

Conectar a RabbitMQ
Abrir canal
Consumir cola: appointments.responses
Por cada mensaje:
  1. Parsear mensaje externo del Core
  2. Parsear campo payload
  3. Leer correlation_id
  4. Procesar
  5. ACK

El mensaje que llega por Rabbit tiene este formato externo:

{
  "event_type_id": 11,
  "event_type_name": "billing.invoice.create.responded",
  "source_module": "appointments",
  "publisher_module": "billing",
  "log_id": 456,
  "payload": "{\"correlation_id\":\"9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45\",\"status\":\"created\",\"invoice_id\":321}",
  "published_at": "2026-07-03T12:00:00Z"
}

Ojo tecnico: payload llega como string. Primero parsean el mensaje externo y despues ese JSON interno.

7. Definir payloads por evento

Cada evento necesita un contrato claro.

Ese contrato lo definen y lo comparten los equipos duenos del flujo.

Payload de request

Ejemplo para billing.invoice.create.requested:

{
  "correlation_id": "9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45",
  "appointment_id": 987,
  "patient_id": 123,
  "amount": 15000,
  "currency": "ARS",
  "response_event_id": 11
}

Campos recomendados:

  • correlation_id: obligatorio si se espera respuesta.
  • response_event_id: evento donde se publica la respuesta. Este ID lo define y lo comparte quien espera recibir la response.
  • Datos de negocio necesarios para procesar la request.

Payload de response

El payload de response lo acuerdan los microservicios del flujo.

Regla practica:

  • Quien espera la response crea el evento de response.
  • Quien procesa la request publica esa response usando el response_event_id recibido.

Ejemplo para billing.invoice.create.responded:

{
  "correlation_id": "9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45",
  "status": "created",
  "invoice_id": 321,
  "error": null
}

Reglas:

  • Usar el mismo correlation_id recibido en la request.
  • Publicar al event_type_id recibido como response_event_id.
  • Incluir status.
  • Si falla, incluir informacion simple de error.

Ejemplo de error:

{
  "correlation_id": "9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45",
  "status": "failed",
  "invoice_id": null,
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "El monto debe ser mayor a cero"
  }
}

8. Que comparte cada microservicio

Si tu microservicio recibe requests

Compartir con los demas equipos:

  • ID del evento de request.
  • Nombre del evento de request.
  • Payload que tienen que enviarte.
  • Payload de response.

No tenes que crear ni compartir el evento de response.

Ese evento lo crea quien hizo la request y espera recibir la respuesta.

Si tu microservicio va a responder, lee el response_event_id del payload de la request (o solicitalo al microservicio emisor) y publica ahi la response.

Ejemplo:

Microservicio: billing
Request event id: 10
Request event name: billing.invoice.create.requested
Request payload: ver contrato billing.invoice.create.requested

Si tu microservicio espera responses

Compartir con el servicio que va a responder:

  • ID del evento de responses.
  • Nombre del evento de responses.

Este ID tambien viaja en la request como response_event_id.

Ejemplo:

Microservicio: appointments
Response event id: 11
Response event name: billing.invoice.create.responded
Response queue: appointments.responses
Response payload: ver contrato billing.invoice.create.responded

Resumen mini:

Recibo requests: comparto mi event_id.
Espero responses: comparto mi event_id.
Proceso requests: respondo al response_event_id que me mandaron.

9. Publicar mensajes al Core

Los microservicios publican llamando al Core.

Endpoint:

POST /events/log
Authorization: Bearer <token>
Content-Type: application/json

Body base:

{
  "event_type_id": 10,
  "publisher_module": "appointments",
  "payload": "{\"correlation_id\":\"9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45\"}"
}

Ojo tecnico: payload va como string.

Publicar una request

La request incluye el response_event_id si se espera respuesta.

Ese response_event_id lo creo el microservicio solicitante.

{
  "event_type_id": 10,
  "publisher_module": "appointments",
  "payload": "{\"correlation_id\":\"9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45\",\"appointment_id\":987,\"patient_id\":123,\"amount\":15000,\"currency\":\"ARS\",\"response_event_id\":11}"
}

Si el evento 10 esta bindeado a billing.requests, billing recibe la request.

Publicar una response

La response se publica al event_type_id que llego como response_event_id en la request.

El correlation_id tiene que ser el mismo.

{
  "event_type_id": 11,
  "publisher_module": "billing",
  "payload": "{\"correlation_id\":\"9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45\",\"status\":\"created\",\"invoice_id\":321,\"error\":null}"
}

Si el evento 11 esta bindeado a appointments.responses, appointments recibe la response.

10. Checklist rapido

Para recibir requests:

  • Tener credenciales RabbitMQ.
  • Crear cola <servicio>.requests.
  • Crear evento de request.
  • Bindear evento de request con <servicio>.requests.
  • Escuchar <servicio>.requests.
  • Compartir request event id, payload esperado y payload de respuesta si corresponde.

Para esperar responses:

  • Tener credenciales RabbitMQ.
  • Crear cola <servicio>.responses.
  • Crear evento de response.
  • Bindear evento de response con <servicio>.responses.
  • Escuchar <servicio>.responses.
  • Compartir response_event_id con el servicio que va a responder.
  • Enviar ese ID en la request como response_event_id.

Para publicar:

  • Generar correlation_id si se espera respuesta (random UUID).
  • Armar payload segun contrato del evento.
  • Enviar POST /events/log al Core.

11. Errores comunes ༼;´༎ຶ ۝ ༎ຶ༽

No llega ningun mensaje

Checklist rapido para debuggear:

  • La cola existe.
  • El evento existe.
  • El evento esta bindeado a la cola correcta.
  • El microservicio escucha la cola con el sufijo correcto.
  • El mensaje se publico con el event_type_id correcto.

El responder publico a un evento incorrecto

Checklist rapido para debuggear:

  • La request incluia response_event_id.
  • El responder publico la response usando ese response_event_id.
  • El evento de response fue creado y bindeado por quien espera la response.

No se puede relacionar una response con una request

Checklist rapido para debuggear:

  • La request tenia correlation_id.
  • La response copio exactamente el mismo correlation_id.

El payload llega como texto

Esto es normal: el mensaje externo trae payload como string.

Primero parseen el mensaje externo y despues parseen payload.

12. Resumen final: que tiene que hacer cada uno (❀ˆᴗˆ)(•́ᴗ•̀✿)

Si tu microservicio recibe requests:

  • Pedir credenciales RabbitMQ al equipo del Core.
  • Crear desde el Core una cola tipo requests, por ejemplo billing.requests.
  • Crear desde el Core el evento de request, por ejemplo billing.invoice.create.requested.
  • Vincular ese evento con tu cola requests.
  • Escuchar tu cola en RabbitMQ con las credenciales recibidas.
  • Definir y compartir el payload que esperas recibir y que pretendes devolver.
  • Compartir con los demas equipos el request_event_id.
  • Si vas a responder, leer de la request el response_event_id y publicar la response ahi.

Si tu microservicio hace requests y espera responses:

  • Pedir credenciales RabbitMQ al equipo del Core.
  • Crear desde el Core una cola tipo responses, por ejemplo appointments.responses.
  • Crear desde el Core el evento de response, por ejemplo billing.invoice.create.responded.
  • Vincular ese evento con tu cola responses.
  • Escuchar tu cola de responses en RabbitMQ.
  • Compartir el response_event_id con el microservicio que va a responder.
  • Enviar en la request un correlation_id y el response_event_id.
  • Cuando llegue la response, matchearla usando el mismo correlation_id.

Para publicar mensajes:

  • Usar POST /events/log del Core.
  • Mandar el event_type_id correcto.
  • Enviar payload como string JSON.
  • Incluir correlation_id si despues necesitas reconocer la response.