Catalog Service: Microservicio con Arquitectura Hexagonal

  ┌─────────────────────────────────────────────┐
  │             INFRAESTRUCTURA                 │
  │   ┌─────────────────────────────────────┐   │
  │   │           APLICACIÓN                │   │
  │   │   ┌─────────────────────────────┐   │   │
  │   │   │          DOMINIO            │   │   │
  │   │   │   (núcleo, sin framework)   │   │   │
  │   │   └─────────────────────────────┘   │   │
  │   └─────────────────────────────────────┘   │
  └─────────────────────────────────────────────┘

  Las flechas de dependencia apuntan siempre hacia dentro:
  Infraestructura → Aplicación → Dominio

catalog-service/
├── catalog-domain/            ← DOMINIO: entidades, puertos, excepciones
│   └── (sin dependencias de framework)
├── catalog-application/       ← APLICACIÓN: casos de uso, mediator
│   └── (depende sólo de catalog-domain)
├── catalog-infrastructure/    ← INFRAESTRUCTURA: adaptadores técnicos
│   ├── catalog-infrastructure-api-rest/     (adaptador REST entrante)
│   ├── catalog-infrastructure-api-grpc/     (adaptador gRPC entrante)
│   └── catalog-infrastructure-persistence-jpa/ (adaptador BD saliente)
└── catalog-bootstrap/         ← BOOTSTRAP: arranque, configuración Spring Boot
    └── (ensambla todos los módulos)

Cliente HTTP
    │
    ▼
PaisesApiDelegateImpl (Adaptador REST)
    │  GET /paises/{id}
    ▼
GetPaisByIdUseCase (Puerto de entrada)
    │
    ▼
GetPaisByIdUseCaseImpl (Caso de uso)
    │
    ▼
PaisRepositoryPort (Puerto de salida)
    │
    ▼
PaisRepositoryAdapter (Adaptador de persistencia)
    │
    ▼
JpaPaisRepository (Spring Data JPA)
    │  SELECT * FROM paises WHERE id = ?
    ▼
PostgreSQL 16
    │  País encontrado
    ▼  (respuesta sube por el mismo camino)
HTTP 200 OK + PaisDTO

// Las dependencias entre capas se validan en CI/CD:
// ✅ Dominio no depende de aplicación ni infraestructura
// ✅ Aplicación sólo depende de dominio
// ✅ Infraestructura puede depender de aplicación y dominio
// ✅ Bootstrap puede depender de todos los módulos

catalog-service/                          (POM padre)
├── catalog-domain/                       (módulo de dominio)
├── catalog-application/                  (módulo de aplicación)
├── catalog-infrastructure/               (módulo de infraestructura — padre)
│   ├── catalog-infrastructure-api-rest/
│   ├── catalog-infrastructure-api-grpc/
│   └── catalog-infrastructure-persistence-jpa/
├── catalog-bootstrap/                    (módulo de arranque)
└── catalog-doc/                          (módulo de documentación)

                ┌────────────────┐
                │ catalog-domain │  (sin dependencias externas)
                └───────┬────────┘
                        │ ←depende
          ┌─────────────┴─────────────┐
          │                           │
 ┌────────┴─────────┐        ┌────────┴──────────────────┐
 │catalog-application│        │  catalog-infrastructure   │
 └────────┬─────────┘        │  (api-rest, api-grpc, jpa)│
          │ ←depende          └────────┬──────────────────┘
          └────────────┬──────────────┘
                       │ ←depende
              ┌────────┴────────┐
              │catalog-bootstrap│
              └─────────────────┘

DomainException (base)
├── NotFoundException      ← HTTP 404 en el adaptador REST
└── ValidationException    ← HTTP 422 en el adaptador REST

@Service
@Transactional(readOnly = true)
public class GetPaisByIdUseCaseImpl implements GetPaisByIdUseCase {

    private final PaisRepositoryPort repository;

    @Override
    public Pais getPorId(String id) {
        return repository.getPorId(id)
            .orElseThrow(() -> new NotFoundException(PaisErrorType.NO_ENCONTRADO, id));
    }
}

// Marcador para cualquier petición que puede ser enviada por el mediator
public interface Request<R> { }

// Handler que procesa un tipo específico de Request
public interface RequestHandler<Req extends Request<Res>, Res> {
    Res handle(Req request);
}

// Interfaz principal del Mediator
public interface Mediator {
    <R> R send(Request<R> request);
}

Request
   │
   ▼
ValidationBehavior.handle()     ← valida la petición con Bean Validation
   │
   ▼
LoggingBehavior.handle()        ← registra la petición y el tiempo de respuesta
   │
   ▼
DomainEventsBehavior.handle()   ← recoge y publica eventos de dominio
   │
   ▼
RequestHandler.handle()         ← lógica del caso de uso
   │
   ▼ (resultado)

// Query (objeto de petición)
public record GetLocalidadByIdQuery(String id) implements Request<Localidad> { }

// Handler (procesador de la query)
@Component
public class GetLocalidadByIdHandler
    implements RequestHandler<GetLocalidadByIdQuery, Localidad> {

    @Override
    public Localidad handle(GetLocalidadByIdQuery query) {
        return repository.getPorId(query.id())
            .orElseThrow(() -> new NotFoundException(...));
    }
}

// En el adaptador REST se usa el Mediator (no el UseCase directamente):
mediator.send(new GetLocalidadByIdQuery(id));

Petición
   │
   ▼
┌──────────────────────────────────────────┐
│         Caffeine Cache (L1)              │
│   Heap JVM · hasta 10.000 entradas       │
│   TTL: 5 minutos · Eviction: LFU         │
│   Acceso: < 1 microsegundo               │
└──────────────────────────────────────────┘
   │ (miss L1)
   ▼
┌──────────────────────────────────────────┐
│         Redis Cache (L2)                 │
│   Distribuida · compartida entre pods    │
│   TTL: 10 minutos · Serialización: JSON  │
│   Acceso: < 1 milisegundo (red local)    │
└──────────────────────────────────────────┘
   │ (miss L2)
   ▼
┌──────────────────────────────────────────┐
│         PostgreSQL                       │
│   Fuente de verdad · Query con índice    │
└──────────────────────────────────────────┘

@Configuration
@EnableCaching
public class CacheConfiguration {

    @Bean("caffeineCacheManager")
    public CacheManager caffeineCacheManager(CaffeineSpec spec) {
        return new CaffeineCacheManager() {{ setCaffeineSpec(spec); }};
    }

    @Bean("redisCacheManager")
    public RedisCacheManager redisCacheManager(
            RedisConnectionFactory factory, ObjectMapper objectMapper) {
        var config = RedisCacheConfiguration.defaultCacheConfig()
            .entryTtl(Duration.ofMinutes(10))
            .serializeValuesWith(
                RedisSerializationContext.SerializationPair.fromSerializer(
                    new GenericJackson2JsonRedisSerializer(objectMapper)));
        return RedisCacheManager.builder(factory).cacheDefaults(config).build();
    }

    @Primary
    @Bean
    public CacheManager compositeCacheManager(
            @Qualifier("caffeineCacheManager") CacheManager l1,
            @Qualifier("redisCacheManager")   CacheManager l2) {
        var composite = new CompositeCacheManager(l1, l2);
        composite.setFallbackToNoOpCache(true); // No falla si Redis no está
        return composite;
    }
}

spring:
  threads:
    virtual:
      enabled: true    # Habilita virtual threads para Tomcat y tareas async

ENV JAVA_OPTS="\
  -XX:+UseContainerSupport \
  -XX:InitialRAMPercentage=50.0 \
  -XX:MaxRAMPercentage=75.0 \
  -XX:+UseZGC \
  -XX:+ZGenerational \
  -XX:+UseStringDeduplication \
  -XX:MaxMetaspaceSize=256m \
  -XX:+ExitOnOutOfMemoryError"

# =============================================
# ETAPA 1: BUILDER
# =============================================
FROM eclipse-temurin:25-jdk-alpine AS builder

WORKDIR /app
COPY target/*.jar app.jar
RUN java -Djarmode=layertools -jar app.jar extract

# =============================================
# ETAPA 2: RUNTIME
# =============================================
FROM eclipse-temurin:25-jre-alpine

# Usuario no root — seguridad en contenedor
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

WORKDIR /app

# Capas ordenadas de menor a mayor frecuencia de cambio
COPY --from=builder /app/dependencies/ ./
COPY --from=builder /app/spring-boot-loader/ ./
COPY --from=builder /app/snapshot-dependencies/ ./
COPY --from=builder /app/application/ ./

EXPOSE 8080

ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS org.springframework.boot.loader.launch.JarLauncher"]

services:
  backend:
    image: catalog-service:latest
    ports:
      - "8080:8080"
    depends_on:
      database:
        condition: service_healthy
      cache:
        condition: service_healthy
    deploy:
      resources:
        limits:
          memory: 512m
          cpus: "1.0"

  database:
    image: postgres:16-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U catalog -d catalog"]

  cache:
    image: redis:8.0-alpine
    command: redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]

          ┌─────────────────────┐
          │   E2E / Contract    │  ← Pocos, lentos, frágiles
          │  (gRPC / OpenAPI)   │
          ├─────────────────────┤
          │  Integración / BDD  │  ← Cucumber con Spring context
          │  (Persistence + UC) │
          ├─────────────────────┤
          │    Unitarios        │  ← Muchos, rápidos, sin Spring
          │  (Domain + App)     │
          └─────────────────────┘

class PaisTest {

    @Test
    void deberiaCrearPaisValido() {
        var pais = new Pais("ESP", "España");
        assertThat(pais.id()).isEqualTo("ESP");
        assertThat(pais.denominacion()).isEqualTo("España");
    }

    @Test
    void deberiaFallarSiIdEsNulo() {
        assertThatThrownBy(() -> new Pais(null, "España"))
            .isInstanceOf(ValidationException.class);
    }
}

Feature: Obtener país por identificador

  Background:
    Given un repositorio de países con los siguientes datos:
      | id  | denominacion |
      | ESP | España       |
      | FRA | Francia      |

  Scenario: Obtener un país existente
    When se solicita el país con id "ESP"
    Then se obtiene el país con denominación "España"

  Scenario: País no encontrado lanza excepción
    When se solicita el país con id "XXX"
    Then se lanza una NotFoundException con el id "XXX"

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Testcontainers
class PaisRepositoryAdapterTest {

    @Container
    static PostgreSQLContainer<?> postgres =
        new PostgreSQLContainer<>("postgres:16-alpine")
            .withDatabaseName("catalog_test");

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
    }

    @Test
    void deberiaObtenerPaisPorId() {
        var resultado = adapter.getPorId("ESP");
        assertThat(resultado).isPresent();
        assertThat(resultado.get().denominacion()).isEqualTo("España");
    }
}

git clone https://github.com/iCesofT/arquitectura-hexagonal.git
cd arquitectura-hexagonal/catalog-service
./mvnw clean compile

docker-compose up -d

# Health Check
curl http://localhost:8080/actuator/health

# API REST — Países
curl http://localhost:8080/api/v1/paises

# Swagger UI
open http://localhost:8080/openapi/ui.html

# Tests unitarios
./mvnw test

# Tests de integración (requiere Docker)
./mvnw verify

# Tests Cucumber (BDD)
./mvnw test -Dtest="*CucumberTest"