Microservicio Multitenant
Un microservicio de dominio pensado para vivir dentro de un ecosistema Zutun — multi-tenant, hexagonal y event-driven por defecto.
Contexto
Este arquetipo no genera un servicio aislado: genera un microservicio que encaja en un ecosistema mayor, donde conviven otros servicios de dominio, un bus de eventos compartido y una base de datos con aislamiento por tenant.
El servicio expone una API REST al exterior. Cada request incluye la cabecera x-tenant-id, que resuelve el tenant activo y se propaga automaticamente al resto del servicio. La integracion con otros microservicios del ecosistema ocurre principalmente de forma asincrona a traves del message broker compartido, usando el patron outbox/inbox tanto para eventos como para comandos; en casos puntuales se admite una llamada HTTP sincrona directa, reenviando la misma cabecera.
Capacidades
Multi-tenant por diseno
Aislamiento de datos a nivel de schema de base de datos. El tenant activo se resuelve por request a partir de x-tenant-id y se propaga automaticamente a base de datos, auditoria, publicacion y consumo de mensajes sin que el codigo de dominio tenga que conocerlo.
Arquitectura hexagonal
Codigo organizado en capas de dominio, puertos y adaptadores. Aggregate roots, entidades y eventos de dominio separados de la infraestructura, con reglas que las hacen cumplir automaticamente en cada build.
Mensajeria confiable
Publicacion y consumo de eventos y comandos con garantias de entrega via patron outbox/inbox. Un servicio generado con este arquetipo puede integrarse con sus hermanos sin perder mensajes ni generar duplicados.
Despliegue flexible
El servicio se puede empaquetar como imagen de contenedor para orquestadores (Kubernetes, Docker Compose) o ejecutarse como aplicacion standalone sobre una JVM en un servidor. La misma build cubre ambos modos.
Listo para produccion
Seguridad configurada con puntos de extension, API REST documentada con un contrato legible para quien integra, auditoria automatica de registros (quien creo o modifico que y cuando), migraciones versionadas de la base de datos, configuracion por entorno y tests automatizados en dos capas (servicio y end-to-end).
Cuando usar este arquetipo
| Usa este arquetipo cuando… | Considera otra opcion si… |
|---|---|
Tu servicio es un microservicio de dominio dentro de un ecosistema de microservicios. |
Tu servicio tiene responsabilidades de orquestacion o soporte tecnico — busca un arquetipo orientado a ese rol. |
Tu servicio necesita aislar datos por tenant a nivel de schema. |
Tu servicio opera en un unico tenant — usa el arquetipo single-tenant. |
Tu servicio publica o consume eventos de dominio en el bus compartido. |
Tu servicio no participa en flujos event-driven — el overhead del outbox/inbox no se justifica. |
Documentacion
- Primeros Pasos
-
Instala los pre-requisitos y genera tu primer proyecto en minutos.
- Tutorial: Task Manager
-
Construye un servicio completo paso a paso, desde la generacion del proyecto hasta la configuracion multi-tenant.
- Guias
-
Recetas orientadas a tareas especificas: crear endpoints, agregar casos de uso, configurar tenants y mas.
- Arquitectura
-
Capas hexagonales, convenciones de nombres y reglas de dependencia.
- Referencia
-
Propiedades de configuracion, perfiles de Spring y reglas ArchUnit.
- Agentes IA
-
Como operar el proyecto generado con agentes de IA.