Contratos de Eventos

Compatibilidade e evolução

Tutorial para classificar e aplicar mudanças breaking e non-breaking em contratos de evento.

Avançado 30 min 25 pontos Leitura 0%

Nesta aula você vai

  • Classificar mudanças de schema com critérios objetivos
  • Aplicar estratégia de convivência entre versões
  • Automatizar bloqueio de mudanças breaking sem plano

Compatibilidade e evolução

Nesta aula você vai evoluir contrato sem quebrar consumidores, usando uma política simples e executável no CI.

Matriz prática de mudanças

Mudanças geralmente compatíveis:

  • Adicionar campo opcional.
  • Adicionar novo valor em enum quando consumidor ignora desconhecidos.

Mudanças geralmente breaking:

  • Remover campo existente.
  • Tornar obrigatório algo que era opcional.
  • Alterar tipo (number para string).

Passo 1 - Proponha evolução segura

Exemplo em order.created:

  • couponCode entra como opcional em v1.
  • Consumidores antigos continuam funcionando.

Trecho do schema:

"couponCode": { "type": "string", "minLength": 1 }

Sem incluir em required.

Passo 2 - Registre changelog

Crie contracts/events/CHANGELOG.md:

## 2026-07-03
- order.created v1: campo opcional `couponCode` adicionado.
- Compatibilidade: backward compatible.

Passo 3 - Adicione verificação automática

Script shared/scripts/check-contract-breaking.sh:

#!/usr/bin/env bash
set -euo pipefail
npm run contracts:diff -- --fail-on-breaking

Comando de CI:

bash shared/scripts/check-contract-breaking.sh

Passo 4 - Defina janela de depreciação

Para mudanças breaking:

  1. Publicar v2.
  2. Rodar convivência (v1 + v2) por período acordado.
  3. Medir consumo de v1 antes de remover.

Checklist de aprovação de PR

  • Mudança classificada (breaking/non-breaking).
  • Consumidores impactados listados.
  • Plano de rollout e rollback descrito.
  • Testes de contrato atualizados.

Resumo

Você estabeleceu um fluxo de evolução contratual com critérios claros, automação em CI e transição segura entre versões.