|
Download documentation/integrations/M10_integration.md from Modulo-6/api: direct link, hf CLI and curl.
- Browser
- Download file 14.3 kB
-
https://huggingface.co/spaces/Modulo-6/api/resolve/main/documentation/integrations/M10_integration.md
- Command line
-
hf download hf://spaces/Modulo-6/api/documentation/integrations/M10_integration.md
-
curl -L -o M10_integration.md https://huggingface.co/spaces/Modulo-6/api/resolve/main/documentation/integrations/M10_integration.md
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: | |
| ```json | |
| { | |
| "correlation_id": "9b9cfd23-8cc4-4ec3-a6e8-6d83f8f73b45", | |
| "patient_id": 123, | |
| "appointment_id": 987 | |
| } | |
| ``` | |
| ## Grafico del flujo | |
| ```mermaid | |
| 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: | |
| ```text | |
| 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`: | |
| ```text | |
| 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: | |
| ```http | |
| POST /auth/login | |
| Content-Type: application/json | |
| { | |
| "email": "user@mail.com", | |
| "password": "1234" | |
| } | |
| ``` | |
| Usar el token devuelto: | |
| ```http | |
| Authorization: Bearer <token> | |
| ``` | |
| ## 3. Crear colas desde el Core | |
| Endpoint: | |
| ```http | |
| 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: | |
| ```json | |
| { | |
| "queue_name": "billing", | |
| "queue_type": "requests" | |
| } | |
| ``` | |
| Resultado: | |
| ```json | |
| { | |
| "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: | |
| ```json | |
| { | |
| "queue_name": "appointments", | |
| "queue_type": "responses" | |
| } | |
| ``` | |
| Resultado: | |
| ```json | |
| { | |
| "queue_name": "appointments.responses", | |
| "queue_type": "responses", | |
| "dlq_name": "appointments.responses.dlq", | |
| "rabbit_username": "user@mail.com" | |
| } | |
| ``` | |
| ## 4. Crear eventos desde el Core | |
| Endpoint: | |
| ```http | |
| 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: | |
| ```json | |
| { | |
| "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: | |
| ```json | |
| { | |
| "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: | |
| ```text | |
| 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: | |
| ```http | |
| 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`: | |
| ```json | |
| { | |
| "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`: | |
| ```json | |
| { | |
| "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: | |
| ```text | |
| 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: | |
| ```json | |
| { | |
| "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`: | |
| ```json | |
| { | |
| "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`: | |
| ```json | |
| { | |
| "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: | |
| ```json | |
| { | |
| "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: | |
| ```text | |
| 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: | |
| ```text | |
| 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: | |
| ```text | |
| 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: | |
| ```http | |
| POST /events/log | |
| Authorization: Bearer <token> | |
| Content-Type: application/json | |
| ``` | |
| Body base: | |
| ```json | |
| { | |
| "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. | |
| ```json | |
| { | |
| "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. | |
| ```json | |
| { | |
| "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. | |