Eventos fora de ordem numa integração: como evitar que uma atualização antiga sobrescreva dados novos

Uma integração recebe primeiro uma atualização de endereço e, depois, um evento que indica que o cliente ainda tem o endereço anterior. Se aplicar as mensagens pela ordem de chegada, o registo fica desatualizado. O problema não é o segundo evento ser falso: pode ser válido e ter ocorrido antes.

Gerir eventos fora de ordem exige distinguir quando uma alteração ocorreu de quando foi recebida e decidir que fonte de informação permite determinar qual deve prevalecer. Não existe uma regra universal baseada na data. A decisão depende do tipo de evento, da forma como os dados são gerados e do sistema que tem autoridade sobre eles.

Porque chegam eventos fora de ordem

Uma fila, um webhook ou um processo de integração podem introduzir atrasos entre a geração de um evento e o seu consumo. As entregas podem ser repetidas, processadas em paralelo ou seguir percursos com latências diferentes. Assim, dois eventos da mesma entidade podem chegar numa ordem diferente daquela em que foram criados. Também podem ser duplicados se o emissor tentar novamente após não receber uma confirmação.

A ordem pode ser preservada num fluxo específico, mas não entre fluxos diferentes. Por exemplo, as alterações de uma conta podem ser distribuídas por partições, enquanto as alterações das respetivas encomendas são processadas de forma independente. Não presuma que uma fila ou API garante uma ordem global, a menos que essa propriedade esteja documentada e seja válida no percurso real.

O efeito depende do conteúdo:

• Um evento de estado completo descreve o estado de um registo num determinado momento. Se for aplicado depois, um estado antigo pode substituir campos mais recentes.
• Um evento delta descreve uma alteração, como adicionar uma etiqueta ou incrementar um contador. Descartá-lo por ser antigo pode eliminar uma alteração legítima que ainda não tinha sido aplicada.

Antes de escolher uma regra, identifique se as mensagens representam estados completos, alterações parciais ou uma combinação dos dois. A estratégia adequada para uma atualização de perfil pode não servir para uma operação financeira ou uma transição de encomenda.

Receção, hora do evento e sequência de negócio

A hora de receção indica quando o sistema consumidor observou a mensagem. É útil para medir atrasos e ordenar o que foi recebido nesse consumidor, mas não prova quando ocorreu a alteração original.

A hora do evento pretende indicar quando a alteração ocorreu ou foi registada. Pode ajudar no diagnóstico, mas depende do relógio, da precisão e das convenções do emissor. Dois sistemas podem ter relógios dessincronizados, e um evento gerado durante uma retoma pode ter uma hora que não representa com exatidão a ordem de negócio. Uma data mais recente não prova, por si só, que um evento aconteceu depois de outro.

A sequência de negócio expressa a ordem relevante para a entidade: por exemplo, a versão 12 de um registo sucede à versão 11, ou uma operação é confirmada depois de outra. Se o sistema de origem fornecer uma versão monotónica ou um número de sequência fiável, associado à mesma entidade, essa indicação costuma ser mais sólida do que a hora. Confirme o seu âmbito: pode reiniciar, ser local a um processo ou não permitir comparar alterações de entidades diferentes.

Registe estes valores separadamente. Não reutilize um único campo chamado «data» para determinar precedência, medir atrasos e manter uma auditoria; cada finalidade exige uma interpretação clara.

Como reconhecer uma atualização obsoleta sem perder alterações válidas

Uma atualização só é obsoleta em relação a uma regra definida e ao estado atual conhecido pelo consumidor. Por exemplo, se este guardou a versão 18 de um cliente e recebe um estado completo da versão 16, pode rejeitá-lo por ser anterior. Em contrapartida, não deve descartar automaticamente um delta válido apenas porque a respetiva marca temporal é mais antiga: pode acrescentar uma informação ausente do evento posterior.

Para avaliar cada mensagem, verifique:

• Identidade e âmbito: a entidade, o campo ou o conjunto de dados a que diz respeito. Duas alterações podem ser independentes e não exigir que se escolha entre elas.
• Tipo e versão: se contém um estado completo ou um delta e se a sua sequência pode ser comparada com a já aplicada.
• Pré-condições: se a transição é válida a partir do estado atual. Uma alteração para «enviada» não deve fazer um pedido já «entregue» regredir sem explicação.
• Autoridade: que sistema pode determinar o valor do campo. Uma atualização de perfil e uma correção proveniente do sistema principal não têm necessariamente o mesmo peso.

A comparação e a escrita têm de ser coerentes. Se dois consumidores lerem a versão 16 e tentarem guardar alterações, uma verificação feita antes da escrita pode ficar desatualizada. Use uma atualização condicionada pela versão observada ou uma operação equivalente no armazenamento. Assim, o consumidor consegue detetar que o registo mudou antes de confirmar a sua alteração.

Critérios para resolver conflitos

Dê prioridade à indicação mais fiável que realmente exista; não invente uma hierarquia com campos que não garantem a ordem. Estes critérios podem ser combinados, desde que o seu significado esteja documentado:

1. Versão ou sequência por entidade: aceite o estado completo se a versão avançar; ignore uma versão já aplicada ou anterior. Defina como tratar saltos, reinícios e versões em falta.
2. Estado e transição permitida: valide a alteração com base numa máquina de estados ou em regras de negócio. Uma transição inválida deve ser encaminhada para análise, não convertida silenciosamente numa atualização.
3. Autoridade por campo: atribua cada dado a um sistema responsável. Se duas fontes puderem legitimamente editar o mesmo campo, estabeleça uma política explícita, como análise ou prioridade acordada, em vez de improvisar uma regra de «última mensagem recebida».
4. Comparação do conteúdo: aplique deltas idempotentes sempre que possível e evite substituir um registo inteiro por uma mensagem parcial. Se o evento não permitir identificar o que mudou, consulte a fonte de verdade antes de sobrescrever.

«A última escrita prevalece» pode ser aceitável para campos pouco críticos, se os relógios e a política estiverem suficientemente controlados. Não é uma regra neutra: pode apagar alterações válidas e ocultar conflitos. Para decisões sensíveis, é preferível conservar ambas as versões ou impedir a resolução automática.

O que fazer quando não há uma sequência fiável

Quando o emissor não fornece uma versão comparável, não tente inferir uma ordem exata a partir da hora de receção. Escolha uma resposta adequada ao impacto de uma decisão errada:

• Consultar o estado atual no sistema de origem antes de atualizar, se existir uma API de leitura fiável. Isto reduz a dependência de uma mensagem atrasada, embora seja necessário considerar que a leitura e a escrita também podem coincidir com alterações posteriores.
• Aplicar apenas campos independentes se o evento identificar claramente o que alterou. Mantenha os restantes valores e evite substituições completas.
• Reservar o conflito para reconciliação quando faltar contexto ou o dado for importante. Guarde a mensagem, a entidade e o motivo da decisão para permitir uma análise posterior.
• Definir uma prioridade de origem quando a atividade tiver determinado qual sistema prevalece para um dado. Comunique a regra às equipas e reveja as exceções.

Uma fila de análise ou uma consulta posterior não devem transformar-se num limbo invisível. Defina quem trata dos casos, como são repetidas as tentativas e que indicador confirma a resolução. Se não for possível decidir automaticamente, é mais seguro mostrar a incerteza do que apresentar como atual um dado duvidoso.

Testes e registos para verificar o comportamento

Teste o contrato de integração, não apenas o percurso ideal. Para a mesma entidade, envie duas alterações pela ordem inversa; repita um evento já processado; atrase outro durante uma nova tentativa; e provoque a gravação quase simultânea de duas atualizações. Inclua versões iguais, em falta ou inesperadas, se estas situações forem possíveis na origem.

Verifique não só o valor final, mas também a decisão: aceite, ignorado como duplicado ou obsoleto, combinado, reservado ou rejeitado por transição inválida. Confirme que as mensagens repetidas não produzem efeitos adicionais e que os eventos válidos não se perdem por causa de uma regra baseada apenas em datas.

Registe o identificador do evento, a entidade, a origem, a versão ou sequência disponível, a hora do evento e a hora de receção, a versão anterior e a posterior e o motivo da decisão. Evite incluir dados pessoais desnecessários nos registos. Acompanhe a antiguidade das mensagens e o volume de conflitos: um aumento pode indicar atrasos, novas tentativas ou uma alteração do emissor, não necessariamente uma falha do consumidor.

Lista de decisões antes de ativar a integração

• Cada mensagem representa um estado completo, um delta ou ambos?
• Que campo determina a precedência e quem garante o seu âmbito e continuidade?
• Que sistema é a autoridade para cada dado e que alterações pode aceitar cada origem?
• Como são evitados duplicados e escritas concorrentes que invalidam uma verificação?
• O que acontece perante sequências em falta, transições inválidas e conflitos ambíguos?
• Quem analisa os casos reservados e como é medido o tempo até à sua resolução?

A decisão prática consiste em usar a indicação de ordem mais fiável disponível, limitar cada evento aos dados que realmente altera e tornar explícita a incerteza. Assim, é possível identificar uma mensagem atrasada sem descartar às cegas alterações legítimas nem deixar que uma atualização antiga sobrescreva o estado atual.