Por Onde Começar: Entendendo o Básico

Antes de pegar a estrada, vamos conhecer alguns termos chave do nosso sistema de transporte:

Eventos vs Mensageria: Entendendo a Diferença

Antes de mergulharmos nos padrões técnicos, é crucial entender a distinção fundamental entre eventos e mensagens. Embora sejam possam ser confundidos, eles servem a propósitos diferentes.

Eventos são veículos ágeis que apenas notificam ocorrências, enquanto mensagens são transportadores comprometidos com a entrega completa de dados. Os eventos não se preocupam com quem vai reagir à sua passagem, já as mensagens têm destino e expectativas bem definidas.

Em nossa Autoestrada do Kafka temos temos o propósito de trafegar exclusivamente Eventos.

Para uma comparação mais aprofundada, consulte a documentação da Microsoft: Comparar os serviços de mensagens do Azure.

Documentação Técnica

Projetando Nossos Veículos: Como Criar um Evento Perfeito

Agora, vamos ver como construir nossas "mensagens" (eventos) da maneira correta.

// Localização: contracts/_shared/envelope/v1/envelope.proto
syntax = "proto3";
package nstech.nsportal.shared; // Nosso "endereço" organizacional
import "google/protobuf/timestamp.proto"; // Usando um tipo padrão para data/hora

// Nossa caixa de envio padrão
message EventEnvelope {
  string                     event_id       = 1; // Identificador único (UUID v7)
  google.protobuf.Timestamp  timestamp      = 2; // Quando o evento foi criado
  string                     version        = 3; // Versão SemVer do payload (ex: "1.0.0")
  string                     correlation_id = 4; // Para rastrear a jornada completa
  string                     source         = 5; // Sistema de origem (ex: "pedidos-api")
  bytes                      payload        = 6; // A carga útil binária (Protobuf)
  string                     api_url        = 7; // Opcional: URL para mais detalhes
  string                     tenant_id      = 8; // Opcional: Identificador do cliente/tenant
}

contracts/
├─ _shared/              # Projetos compartilhados por todos
│  └─ envelope/
│     └─ v1/             # Versão 1 do nosso envelope padrão
│        ├─ envelope.proto  # O projeto do envelope
│        ├─ catalog-info.yaml # Info para o catálogo Backstage
│        └─ README.md       # Documentação
└─ sales/                # Projetos da área de Vendas
   └─ order-created/      # Evento "Pedido Criado"
      └─ v1/             # Versão 1 deste evento
         ├─ event.proto     # O projeto do payload (conteúdo)
         ├─ catalog-info.yaml # Info para o Backstage
         └─ README.md       # Documentação
         └─ sample.json   # Exemplo de dados (útil para testes)

# Exemplo de como o fiscal verifica o tamanho
./scripts/check-size.sh \
  contracts/sales/order-created/v1/event.proto \ # O projeto do payload
  nstech.standard.sales.v1.OrderCreated \       # O tipo específico de payload
  contracts/sales/order-created/v1/sample.json \ # Um exemplo de dados
  65536                                          # O limite em bytes (64 * 1024)

// Exemplo de um especialista em "Pedido Criado"
public class OrderCreatedHandler : IEventHandler<OrderCreated> // Diz que sabe lidar com OrderCreated
{
    public Task HandleAsync(EventEnvelope envelope, OrderCreated payload, CancellationToken ct)
    {
        // Aqui vai a lógica: o que fazer quando um pedido é criado?
        // Ex: Atualizar estoque, notificar cliente, etc.
        Console.WriteLine($"Recebido Pedido: {payload.OrderId} do cliente {payload.CustomerId}");
        return Task.CompletedTask;
    }
}

// Como configuramos o "posto de recebimento" (Consumer)
builder.Services.AddKafkaConsumer(config =>
{
    // "Fique atento à faixa 'order-created.v1'..."
    config.Topic("nstech.standard.sales.order-created.v1")
          // "...e entregue os pacotes para o especialista OrderCreatedHandler."
          .WithHandler<OrderCreatedHandler>();
});

Uma Viagem Completa: Exemplos do Dia a Dia

Vamos ver como um evento faz sua jornada completa na nossa autoestrada: