Diagrama de arquitectura de microservicios: un ejemplo y siete reglas para mantenerlo legible

Pídele a un equipo que dibuje sus microservicios y a menudo obtendrás la misma imagen: treinta cajas, todas conectadas con todas, flechas sin etiquetas. Es exacta y no responde a ninguna de las preguntas que la gente se hace. Los ingenieros lo llaman el diagrama de la Estrella de la Muerte.

Un diagrama de arquitectura de microservicios útil es un conjunto de decisiones sobre qué mostrar. Esta guía recorre un ejemplo, una tienda online con cinco servicios, y las siete reglas que lo hacen legible. Las mismas reglas sirven tanto si tienes cinco servicios como si tienes cincuenta.

Qué tiene que responder el diagrama

Antes de dibujar, escribe las preguntas. Un buen diagrama de microservicios responde cinco de ellas de un vistazo:

1. ¿Por dónde entran las peticiones? Los clientes, el API gateway, los backends for frontends (BFF).
2. ¿Qué servicio es dueño de qué datos? Cada base de datos debería tener exactamente un dueño.
3. ¿Quién llama a quién de forma síncrona? Estas llamadas comparten latencia y fallos.
4. ¿Qué ocurre de forma asíncrona? Los eventos y las colas desacoplan los servicios en el tiempo.
5. ¿Qué queda fuera de nuestro control? Proveedores de pago, servicios de email, APIs de partners.

Si una caja o una flecha no ayuda a responder ninguna de ellas, probablemente pertenece a otro diagrama.

El ejemplo: una tienda online con cinco servicios

La tienda tiene clientes web y móvil, un API gateway y cinco servicios:

• Catalog sirve los productos desde su propia base de datos PostgreSQL.
• Cart guarda los carritos en Redis.
• Orders crea los pedidos en su propia base de datos PostgreSQL y publica OrderPlaced en el topic orders de Kafka.
• Payments consume OrderPlaced, cobra la tarjeta a través de Stripe, guarda el resultado y publica PaymentSucceeded o PaymentFailed en el topic payments.
• Notifications consume el topic payments y, a través de un proveedor de email, envía un recibo o un aviso de pago fallido.

Orders también consume el topic payments para marcar un pedido como pagado. Nadie llama a Payments directamente; el flujo de checkout es una cadena de eventos. Esa decisión de diseño es justo lo que el diagrama tiene que hacer visible:

Léelo de izquierda a derecha: el gateway es el único punto de entrada, las flechas continuas son llamadas síncronas, las discontinuas son eventos a través de topics con nombre y cada base de datos cuelga de un único servicio.

Siete reglas para un diagrama de microservicios legible

1. Empieza por los puntos de entrada

Dibuja primero los clientes y el API gateway, a la izquierda. Marcan la dirección de lectura y muestran qué servicios están realmente expuestos. Un servicio al que no llega ningún camino desde el gateway es interno, y eso vale la pena verlo.

2. Conecta cada base de datos con su dueño

Coloca cada almacén de datos junto al único servicio que es su dueño y conecta solo ese servicio. Si hoy dos servicios comparten una base de datos, dibújalo también. Es una señal de alarma conocida, y un diagrama que la oculta hace más difícil planificar la próxima migración.

3. Separa las llamadas síncronas de los eventos

Usa dos estilos de línea y explícalos en una leyenda: continua para petición y respuesta (REST, gRPC), discontinua para mensajes a través de un broker. Dibuja los topics o las colas como nodos. Una única caja de "bus de eventos" con todos los servicios conectados oculta quién produce y quién consume qué.

4. Etiqueta cada conexión con lo que circula por ella

GET /products, POST /orders, OrderPlaced, PaymentFailed. Una etiqueta convierte una flecha en un contrato, y es lo que la gente busca en el diagrama durante un incidente.

5. Agrupa por dominio, no por tecnología

Si necesitas marcos, agrupa los servicios por dominio de negocio o por equipo responsable: compras, checkout, comunicación con el cliente. Marcos como "servicios Node.js" o "servicios Java" responden a una pregunta que nadie se hace.

6. Deja la infraestructura en su propia vista

Los Pods, los sidecars, los service meshes y los dashboards importan, pero no en la vista lógica. Dibuja el despliegue en un diagrama aparte, por ejemplo un diagrama de arquitectura de Kubernetes, y enlaza ambos.

7. Muestra un flujo crítico

Elige el flujo del que vive el negocio, aquí el checkout, y haz que sea fácil de seguir: numera los pasos en las conexiones o resalta su recorrido. Un flujo por diagrama; un segundo flujo merece su propia copia de la vista.

Cuando el sistema es demasiado grande para un solo diagrama

A partir de unas veinte cajas, divide. Un patrón que funciona:

• Un mapa general con los dominios como marcos y solo las conexiones más importantes entre ellos.
• Un diagrama por dominio con sus servicios, almacenes de datos y topics, dibujado con las reglas anteriores.
• Diagramas de flujo para los pocos recorridos que importan, como el checkout o el registro.

Esto encaja muy bien con el modelo C4: el mapa general se parece a una vista de contexto del sistema, y cada diagrama de dominio es una vista de contenedores en la que los servicios y sus bases de datos son los contenedores.

Errores comunes

• Flechas sin etiquetas. Quien lee adivina, y cada uno adivina algo distinto.
• El gateway conectado a bases de datos. Si de verdad lee una base de datos, es una decisión de diseño que hay que discutir, no un atajo para dibujar.
• Mezclar vistas. Pods, servicios de AWS y capacidades de negocio en el mismo lienzo hacen que nadie pueda leer ninguno de ellos.
• Ocultar el broker. Kafka no es una tubería; los topics tienen nombres, dueños y consumidores.
• Una foto que nunca cambia. Un diagrama de la última rearquitectura es un documento histórico. Ponle fecha o mantenlo vivo.

Constrúyelo en Archboard

Archboard tiene packs de nodos para cada parte de este diagrama, así que los servicios, los almacenes y los topics son nodos tipados con puertos en lugar de cajas que se parecen entre sí:

1. Inicia sesión con Google o GitHub y crea un diagrama.
2. Añade una Caja del pack Básico para los clientes y una Puerta de enlace de API del pack Nube.
3. Añade los servicios como nodos Contenedor del pack Modelo C4, con el lenguaje o el framework en el campo Tecnología.
4. Añade Postgres y Redis del pack Datos junto a sus dueños, y nodos Tema para orders y payments.
5. Añade nodos Sistema externo del pack Modelo C4 para Stripe y el proveedor de email.
6. Conecta los puertos. Deja las llamadas síncronas con línea continua, cambia los eventos a línea discontinua y luego etiqueta cada conexión.
7. Comparte el enlace en vivo con el equipo o, con Pro, embébelo en tu documentación.

El ejemplo de arriba tiene 15 nodos de diagrama, así que cabe en el plan Free. Para ver ejemplos relacionados, abre /examples/kubernetes-microservices para la parte de despliegue y /examples/api-gateway-infographic para una infografía del patrón API gateway.

Preguntas frecuentes

¿Cuántos servicios debería mostrar un diagrama? Tantos como puedas leer sin hacer zoom, normalmente hasta unas veinte cajas. A partir de ahí, divide por dominio y mantén un mapa general por encima.

¿Debería usar el modelo C4 para microservicios? Funciona bien. Los servicios y sus bases de datos pasan a ser contenedores en una vista de contenedores. Algunos equipos modelan cada servicio con un dueño independiente como un sistema de software propio; elige una convención y déjala por escrito.

¿Cómo muestro Kubernetes, el service mesh y el monitoreo? En un diagrama de despliegue aparte. La vista lógica responde quién habla con quién; la vista de despliegue responde dónde se ejecuta.

¿Los eventos deberían apuntar del consumidor al topic, ya que los consumidores hacen pull? Dibuja la dirección en la que fluyen los datos, del productor al topic y del topic al consumidor, y anota que los consumidores hacen pull si eso importa para la discusión.

¿Cómo lo mantengo al día? Asigna un dueño al diagrama, actualízalo en el mismo pull request que el cambio y enlaza el diagrama en vivo desde tu documentación en lugar de pegar capturas de pantalla.

Empieza gratis — un puesto, sin tarjeta de crédito.