Pular para o conteúdo
Sistemas próprios. Conhecimento aplicado.
Agência A2CRConte seu projeto
Sistemas

Event sourcing e CQRS: reconstrua o estado sem confundir eventos com logs

Um manual para decidir quando eventos devem ser fonte de verdade, separar comandos e consultas e reconstruir projeções sem repetir efeitos externos.

Event sourcing e CQRS: reconstrua o estado sem confundir eventos com logs

Uma empresa pode saber o saldo atual de um pedido e ainda não conseguir reconstruir como ele chegou àquele ponto. Guardar eventos de negócio como fonte de verdade é uma maneira de enfrentar essa necessidade, mas muda profundamente o desenho da aplicação. Não se trata de acrescentar uma tabela de logs e passar a chamar o sistema de orientado a eventos.

Event sourcing preserva uma sequência de fatos que permite reconstruir estados. CQRS separa responsabilidades de comando e consulta. Os padrões podem ser combinados, mas não são sinônimos e não precisam aparecer em todos os módulos de um produto. A decisão deve partir do domínio, das invariantes e da capacidade de operar a solução ao longo do tempo.

1. Declare o problema que justifica a mudança

Comece descrevendo uma pergunta que o sistema atual não consegue responder com segurança. Pode ser reconstruir um compromisso em uma data anterior, explicar a sequência de reservas de um recurso ou produzir diferentes visões de fatos preservados. A pergunta deve continuar compreensível sem usar o nome de uma arquitetura.

A referência de event sourcing da Microsoft ressalta a complexidade do padrão e indica que a gestão tradicional de dados é suficiente para muitos sistemas. Portanto, não use dificuldade genérica de manutenção como justificativa automática. Compare o ganho esperado com o custo de modelar eventos, reconstruir estados, evoluir versões e sustentar ferramentas de operação.

2. Diferencie comando, evento e log

Um comando expressa uma intenção: reservar uma quantidade, aprovar um pedido ou cancelar uma etapa. Ele pode ser recusado se as regras não forem atendidas. Um evento registra um fato que foi aceito no domínio: a quantidade foi reservada ou a etapa foi cancelada. Um log técnico registra informações úteis para diagnóstico, sem necessariamente constituir a fonte de verdade do negócio.

Essa distinção influencia nomes e responsabilidades. Receber um comando não significa que o evento correspondente deva existir. Uma tela pode informar que a solicitação foi recebida enquanto aguarda processamento, mas não pode declarar que a reserva está concluída antes da validação prevista. A trilha de auditoria em sistemas complementa a investigação, porém não deve ser confundida com o modelo transacional escolhido.

3. Defina o limite de cada fluxo de eventos

Escolha qual entidade ou agregado terá uma sequência ordenada de fatos. A fronteira precisa conter as regras que devem ser verificadas juntas. Se a reserva de um recurso depende de uma capacidade disponível, descreva onde essa capacidade é protegida e quais decisões podem ser concorrentes.

Não coloque toda a empresa em uma única sequência apenas para obter uma ordem global simples. Também não fragmente o domínio até tornar impossível verificar suas invariantes. Documente o identificador do fluxo, a versão esperada e a regra de concorrência. Dois comandos que leem a mesma versão precisam de um tratamento explícito quando tentam produzir mudanças incompatíveis.

4. Modele eventos que preservem significado

Um evento deve ter informação suficiente para representar o fato aceito e permitir as reconstruções previstas. Inclua identidade, tipo, versão do contrato, referência do fluxo e dados do domínio necessários. A origem de uma correção deve ser rastreável, mas não exige copiar indiscriminadamente dados pessoais ou documentos inteiros para um histórico de longa duração.

Evite eventos excessivamente vagos, como registro alterado, quando a reconstrução depende de saber qual decisão ocorreu. Ao mesmo tempo, não transforme uma estrutura de tela temporária no contrato permanente do negócio. Uma nova interface não deveria obrigar a reescrever fatos passados apenas porque um componente mudou de nome ou posição.

5. Use CQRS para separar necessidades de leitura e escrita

A documentação de CQRS da Microsoft descreve a separação entre modelos para atualizar e consultar informações. Isso permite desenhar consultas orientadas à apresentação sem obrigar o comando a usar a mesma estrutura. Essa separação não determina, sozinha, quantos bancos ou serviços deverão existir.

NecessidadeModelo possívelPergunta de validação
Aceitar uma reservaComando e regras de capacidadeA operação impede compromissos incompatíveis?
Preservar fatos aceitosFluxo versionado de eventosA sequência explica a evolução do agregado?
Mostrar agendaProjeção orientada à consultaA tela indica a atualidade da informação?
Consultar históricoVisão de eventos ou projeção históricaO significado continua compreensível após evolução?
Acelerar reconstruçãoSnapshot validadoO estado equivale à reprodução completa?
Notificar outro sistemaEfeito externo controladoUma reconstrução pode reenviar a notificação indevidamente?

Uma arquitetura simples pode separar responsabilidades dentro da mesma aplicação. A distribuição física deve ser uma decisão adicional, fundamentada por requisitos de carga, segurança ou organização da equipe.

6. Construa projeções que possam ser refeitas

Uma projeção transforma eventos em uma visão útil, como uma lista de saldos ou um calendário de ocupação. Defina quais eventos ela consome, como reconhece a posição processada e como lida com repetição. Se uma falha ocorrer depois de atualizar parte do estado, a retomada precisa produzir um resultado coerente.

Crie um procedimento para construir uma projeção nova sem destruir a atual. Durante a conferência, compare quantidades, totais e amostras de entidades. Depois, promova a nova visão por uma mudança controlada. Essa capacidade de reconstrução deve ser demonstrada com evidências, e não apenas descrita em um diagrama de arquitetura.

7. Mostre a consistência disponível ao usuário

Quando a projeção é atualizada de forma assíncrona, o comando pode ser aceito antes de todas as telas refletirem a mudança. A aplicação precisa explicar essa janela. Não é suficiente pedir que o usuário atualize repetidamente a página até enxergar o resultado desejado.

Uma estratégia é acompanhar a referência da operação e indicar processamento enquanto a consulta ainda não alcançou o ponto esperado. Outra é oferecer uma resposta direta do comando para a confirmação imediata, mantendo a listagem como visão atualizada separadamente. A escolha depende da jornada, mas o usuário não deve confundir demora de projeção com autorização para repetir uma ação que já foi aceita.

8. Controle efeitos externos durante o replay

Reconstruir uma projeção não pode enviar novamente cobranças, e-mails ou comandos para equipamentos. Separe a transformação de estado dos efeitos externos. Cada consumidor precisa de identidade da operação e política de repetição coerente com o efeito produzido.

O padrão de transactional outbox ajuda a discutir a publicação confiável de uma mudança junto de sua persistência, mas não elimina a necessidade de consumidores preparados para repetição. Um replay de teste deve acontecer em ambiente isolado, com destinos externos bloqueados ou substituídos por simuladores autorizados. O teste é valioso justamente quando comprova que reconstruir informação não repete compromissos.

9. Caso hipotético: reserva de uma sala técnica

Considere a empresa fictícia Vetor Ensaios. Um recurso possui dez unidades de capacidade em um período. O fluxo didático registra capacidade inicial de dez, reserva de quatro e reserva de três. A disponibilidade reconstruída é três. Um cancelamento posterior de duas unidades de uma reserva eleva a disponibilidade para cinco, conforme a regra definida no exemplo.

Dois operadores tentam reservar quatro unidades ao mesmo tempo quando a disponibilidade é cinco. O primeiro comando pode ser aceito; o segundo precisa ser reavaliado ou recusado pela regra de concorrência adotada. A existência de eventos não autoriza exceder a capacidade. Na homologação, a equipe reconstrói a projeção e verifica que os mesmos fatos produzem a mesma disponibilidade, sem criar outra reserva ou disparar novas mensagens.

Esses números são hipotéticos e servem para testar invariantes. Um produto real precisa considerar as regras específicas do recurso, como períodos sobrepostos, reservas provisórias e expiração, antes de adotar o modelo.

10. Evolua contratos e snapshots com cuidado

Eventos antigos continuarão existindo quando o código mudar. Defina como leitores novos interpretarão versões anteriores e quais transformações serão necessárias. Não altere silenciosamente o significado de um campo já publicado. Uma quantidade que antes representava peças não pode passar a representar caixas sem uma distinção explícita.

Snapshots aceleram a recuperação de um estado, mas precisam indicar a posição do fluxo e a versão do modelo utilizado. Teste a reconstrução a partir do snapshot contra a reprodução completa. Se o resultado divergir, o snapshot não deve ser aceito como atalho confiável. Preserve meios de investigação e recuperação que não dependam de uma única implementação antiga ainda rodando.

11. Oficina: prove uma reconstrução antes da expansão

Escolha um domínio pequeno com uma invariante clara. Escreva uma sequência de eventos sintéticos, os comandos que podem ser recusados e três consultas que a equipe precisa realizar. Depois, construa duas projeções diferentes a partir do mesmo conjunto: uma para operação e outra para conferência histórica.

Interrompa o processamento no meio, repita uma entrada e reconstrua a visão em um armazenamento separado. Registre o ponto de retomada e compare os resultados com a referência calculada manualmente. O exercício deve revelar se o time entende os fatos e suas consequências, não apenas se consegue iniciar uma ferramenta de mensageria.

12. Checklist de aceite arquitetural

  • Existe uma necessidade concreta que justifica event sourcing.
  • Comandos, eventos e logs possuem papéis diferentes.
  • Os limites dos fluxos e suas invariantes estão documentados.
  • A concorrência impede aceitar mudanças incompatíveis.
  • Tipos e versões de eventos permanecem interpretáveis.
  • Projeções reconhecem repetição e posição de processamento.
  • Uma reconstrução pode ser comparada com uma referência independente.
  • Efeitos externos não são repetidos durante o replay.
  • A interface explica a atualização assíncrona das consultas.
  • Snapshots são confrontados com a reprodução completa.
  • Há política de acesso, retenção e recuperação do histórico.
  • A equipe consegue operar e investigar falhas sem reescrever eventos manualmente.

Perguntas frequentes

CQRS exige event sourcing?

Não. Separar responsabilidades de comando e consulta não obriga a usar eventos como fonte de verdade. É possível aplicar essa separação com persistência tradicional. Avalie cada padrão pelo problema que ele resolve e pelo custo que introduz.

Uma tabela de auditoria já transforma meu sistema em event sourced?

Não. Em event sourcing, os eventos são a referência usada para reconstruir o estado do domínio. Uma auditoria pode registrar alterações de um estado mantido de outra forma. As duas soluções atendem necessidades relacionadas, mas têm responsabilidades diferentes.

Devo migrar todos os cadastros para esse modelo?

Não como ponto de partida. Delimite um domínio em que a reconstrução e o histórico de fatos tenham valor claro. Muitos cadastros funcionam adequadamente com transações e auditoria tradicionais. A adoção gradual permite aprender sobre operação e evolução antes de ampliar a dependência arquitetural.

Transforme a decisão de arquitetura em evidência

Se sua operação precisa explicar e reconstruir compromissos ao longo do tempo, prepare um exemplo de eventos, invariantes e consultas. O serviço de desenvolvimento de sistemas personalizados da Agência A2CR pode avaliar esse material para propor uma arquitetura proporcional ao domínio e à capacidade de manutenção da empresa.

Modelo para aplicar na sua empresa

Baixar o checklist de event sourcing CQRS projeções. Use-o para registrar evidências, responsáveis e pendências da avaliação.

Fontes consultadas

Revisão documental: 18/11/2026. Cenários e números didáticos não representam resultados medidos de clientes. A aplicação exige conferir a documentação e as condições do projeto.

Compartilhar