Event-Driven Architecture e REST vs eventos

Objetivos

• Comparar acoplamento temporal entre REST e Kafka
• Mapear pontos de domínio que devem virar eventos
• Definir estratégia inicial de integração assíncrona

Pré-requisitos

• APIs REST dos cinco serviços implementadas
• Conhecimento básico de HTTP e JSON
• Docker Compose com Kafka disponível

Conceito

REST é excelente para leitura imediata e comandos síncronos. O problema aparece quando um fluxo depende de vários serviços em sequência: qualquer indisponibilidade intermediária derruba toda a operação. Esse é o acoplamento temporal.

Event-Driven Architecture (EDA) muda o eixo: o serviço publica fatos de domínio (customer.created) e outros serviços reagem quando possível. Isso aumenta resiliência e escalabilidade, mas exige consistência eventual e cuidado com idempotência.

No e-commerce do curso, vamos manter REST para operações de consulta e usar eventos para transições de estado importantes. Essa combinação é prática e muito comum em sistemas reais.

Estrutura de arquivos

docs/architecture/integration-style.md
contracts/events/customer-created.v1.json
services/customer-service/src/main/java/.../CustomerService.java
services/order-service/app/consumers/customer_created_consumer.py
infra/docker-compose.yml

Passo a passo

1. Documentar quando usar REST vs evento (docs/architecture/integration-style.md)

# Estratégia de integração

- REST:
  - consultas síncronas (ex.: GET /customers/{id})
  - operações que exigem resposta imediata ao usuário

- Eventos Kafka:
  - fatos de domínio (ex.: customer.created, order.created)
  - reações assíncronas sem dependência temporal

2. Criar contrato de evento customer-created.v1.json

{
  "title": "customer.created.v1",
  "type": "object",
  "required": ["eventId", "customerId", "email", "occurredAt"],
  "properties": {
    "eventId": { "type": "string" },
    "customerId": { "type": "string" },
    "email": { "type": "string" },
    "occurredAt": { "type": "string", "format": "date-time" }
  }
}

3. Inserir ponto de publicação no customer-service (Java)

public void createCustomer(String fullName, String email) {
  String id = repository.create(fullName, email);
  eventPublisher.publishCustomerCreated(id, email);
}

4. Inserir ponto de consumo no order-service (Python)

def handle_customer_created(event: dict) -> None:
    customer_id = event["customerId"]
    print(f"[order-service] cliente disponível para pedidos: {customer_id}")

Como testar

1. Subir Kafka e serviços:

docker compose -f infra/docker-compose.yml up --build -d kafka customer-service order-service

2. Criar cliente (gera evento):

curl -s -X POST http://localhost:8081/customers \
  -H "Content-Type: application/json" \
  -d '{"fullName":"Maria Souza","email":"maria@aprendi.dev"}'

3. Verificar logs:

docker compose -f infra/docker-compose.yml logs -f customer-service order-service

Saída esperada: log de publicação no customer-service e log de consumo no order-service.

Dicas de projeto

• Evento descreve fato ocorrido, não comando remoto.
• Payload mínimo e sem dados internos do banco.
• Inclua eventId e occurredAt desde a primeira versão.
• Decida chave de partição com base em necessidade de ordenação.

Erros comuns

• Tentar usar evento para obter resposta síncrona.
• Considerar publicação como confirmação de processamento.
• Publicar payload "gigante" para evitar lookup.
• Ignorar observabilidade do fluxo.

Resumo

Você definiu a estratégia híbrida REST + eventos para o projeto e preparou os pontos de publicação/consumo do primeiro evento. O próximo passo é estruturar Kafka corretamente com tópicos, partições e offsets.