Reversão em caso de erro e resolução de conflitos

Reverter uma adição otimista (remover o item) ou uma exclusão (restaurar o item) é simples. Reverter uma atualização é mais complexo: é preciso restaurar o valor anterior exato. Se o item tiver sido atualizado várias vezes de forma otimista, será necessário acompanhar cada valor anterior separadamente, não apenas o estado original do servidor.

Considere este cenário: o servidor tem um item com valor Z. Você o atualiza de forma otimista para X. Enquanto sua solicitação está em andamento, outro usuário atualiza o mesmo item para Y no servidor. Sua solicitação chega, e o servidor a rejeita (conflito). O alvo da sua reversão é Z, mas o estado atual do servidor é Y. Restaurar Z substituiria Y incorretamente.

A estratégia mais segura para reverter atualizações é buscar novamente o item no servidor após qualquer erro de mutação, em vez de restaurar uma captura armazenada localmente. Isso garante que você exiba o estado oficial do servidor, independentemente do que outros usuários possam ter alterado simultaneamente. Buscar novamente é mais lento, mas sempre correto.

Uma API bem projetada retorna HTTP 409 Conflito quando uma atualização otimista falha devido a uma modificação simultânea. O corpo da resposta normalmente inclui o estado atual do servidor. Seu manipulador de erros deve detectar 409, usar o corpo da resposta para atualizar o estado local com o valor atual do servidor e informar ao usuário que as alterações não foram salvas.

Uma mutação idempotente produz o mesmo resultado quando aplicada várias vezes. Projetar mutações para serem idempotentes (usando PUT em vez de POST, incluindo o estado completo do recurso e usando chaves de idempotência) torna seguro tentar novamente após uma falha, sem risco de aplicar a alteração duas vezes. Isso simplifica significativamente a lógica de reversão.

Cliques duplos em um botão de envio podem disparar duas mutações idênticas. Evite isso com um sinalizador isSubmitting: defina-o como verdadeiro quando a mutação começar e redefina-o quando ela terminar (tanto em caso de sucesso quanto de falha). Desative o elemento acionador quando isSubmitting for verdadeiro. Isso elimina mutações duplicadas no nível da interface.

Para fazer a desduplicação no servidor, inclua um cabeçalho exclusivo Idempotency-Key em cada solicitação de mutação. Gere-o com crypto.randomUUID() quando o usuário iniciar a ação. O servidor detecta chaves duplicadas e retorna a mesma resposta da solicitação original sem reaplicar a operação.

Enquanto uma mutação estiver em andamento, você pode exibir um indicador sutil de que o estado otimista ainda não foi confirmado: um pequeno ponto pulsante, o texto "Salvando..." ou uma opacidade reduzida no item. Isso comunica a incerteza sem bloquear a interação. Remova o indicador em caso de sucesso ou faça a reversão em caso de falha.

Erros inesperados na lógica de reversão (por exemplo, acessar propriedades de um valor indefinido durante a restauração do estado) podem fazer o componente falhar. Envolva componentes que usam muitas mutações em um limite de erro para que falhas catastróficas na reversão exibam uma interface de erro adequada em vez de uma tela em branco. Registre esses erros para depuração.

Uma estratégia confiável de detecção de conflitos é incluir um número de versão ou ETag em cada mutação. O servidor compara a versão enviada pelo cliente com a versão atual. Se forem diferentes (outra atualização ocorreu), ele retorna 409. Esse é o controle de concorrência otimista: você presume que não haverá conflito, mas o detecta quando ele ocorre.

A lógica de reversão costuma não ser testada porque é difícil simular falhas de rede. Use ferramentas como Mock Service Worker (MSW) para retornar respostas de erro nos testes. Escreva testes explícitos para: tratamento do conflito 409, reversão após tempo limite da rede, desduplicação de cliques duplos e consistência do estado após uma falha. É nesses casos extremos que os defeitos se escondem.

Qual código de status HTTP uma API bem projetada retorna quando uma atualização otimista falha devido a uma modificação simultânea feita por outro usuário?

Reverter uma atualização é mais complexo que reverter uma adição ou exclusão — sempre faça uma nova busca em caso de erro para evitar problemas causados por capturas obsoletas. HTTP 409 Conflito sinaliza falhas de concorrência otimista; use o corpo da resposta para restaurar o estado atual do servidor. Projete mutações idempotentes para permitir novas tentativas seguras. Evite disparos duplos usando isSubmitting e chaves de idempotência no servidor. Teste explicitamente os caminhos de reversão usando MSW para simular erros.