Versionamento de Eventos

customer.created.v1 vs v2

Tutorial comparando payloads e implementação de convivência entre versões.

Avançado 30 min 25 pontos Leitura 0%

Nesta aula você vai

  • Comparar diferenças entre customer.created v1 e v2
  • Publicar versão correta sem quebrar consumidores existentes
  • Testar parsing de duas versões no mesmo serviço

customer.created.v1 vs v2

Nesta aula você vai implementar a coexistência real do evento customer.created em duas versões.

Diferença de payload

v1:

{
  "eventType": "customer.created",
  "eventVersion": "v1",
  "customerId": "cus-1",
  "name": "Ana",
  "email": "ana@acme.com"
}

v2 adiciona document e marketingConsent:

{
  "eventType": "customer.created",
  "eventVersion": "v2",
  "customerId": "cus-1",
  "name": "Ana",
  "email": "ana@acme.com",
  "document": "12345678900",
  "marketingConsent": true
}

Arquivos usados

  • contracts/events/customer.created/v1/schema.json
  • contracts/events/customer.created/v2/schema.json
  • services/customer-service/src/main/java/.../CustomerCreatedPublisher.java
  • services/order-service/app/consumers/customer_created_consumer.py

Passo 1 - Publique versão por feature flag

String version = flags.isEnabled("customer_created_v2") ? "v2" : "v1";
publisher.publish(CustomerCreatedMapper.toEvent(customer, version));

Passo 2 - Consuma com parser por versão

def parse_customer_created(payload: dict) -> CustomerCreated:
    version = payload.get("eventVersion")
    if version == "v1":
        return CustomerCreatedV1(**payload).to_domain()
    if version == "v2":
        return CustomerCreatedV2(**payload).to_domain()
    raise ValueError("UNSUPPORTED_EVENT_VERSION")

Passo 3 - Teste convivência v1/v2

cd services/order-service
pytest tests/contract/test_customer_created_versions.py -q

Passo 4 - Verifique tráfego por versão

curl -s http://localhost:9090/metrics | rg customer_created_events_total

Métrica sugerida:

customer_created_events_total{version="v1|v2"}

Resumo

Você implementou e validou customer.created v1 e v2 em convivência, com publicação controlada, parsing explícito e observabilidade por versão.