Especifica como a interface aplica estado provisório, reconcilia a verdade do servidor, reverte em caso de conflito ou falha, e apresenta evidências duráveis para que os usuários nunca confiem silenciosamente em dados otimistas desatualizados.
Status do pacote: Pacote de referência assistido por IA. A validação estática do pacote foi aprovada; cenários de implementação ainda não foram executados e revisão humana do domínio é necessária antes da adoção estável.
Decisão
Aplicar atualizações otimistas na interface para mutações responsivas, tratando as respostas do servidor como autoritativas. Cada alteração otimista carrega uma identidade de mutação do cliente, preserva um snapshot restaurável e reconcilia para estados de sucesso, reversão, conflito ou timeout incerto com feedback explícito ao usuário.
Escopo
- Regras de aplicação provisória, indicadores pendentes e armazenamento de snapshot.
- Reconciliação em sucesso, falha, conflito e timeout.
- Retentativas idempotentes usando identificadores de mutação do cliente alinhados com idempotência do servidor.
- Telemetria para taxas de aplicação, sucesso, reversão e conflito.
Fora deste bloco
- Persistência da fila offline (veja o bloco de fila de mutações offline).
- Esquema de bloqueio otimista no lado do servidor (veja o bloco de bloqueio otimista).
- UX geral de validação de formulários.
Contrato
- A aplicação otimista ocorre apenas para mutações explicitamente marcadas como otimistas no contrato do cliente; caminhos de leitura nunca são fabricados otimisticamente.
- Cada mutação gera um id de mutação do cliente estável enviado em todas as retentativas até a reconciliação terminal.
- A interface armazena um snapshot para reversão antes da aplicação; a reconciliação falhada restaura exatamente os campos do snapshot.
- Conflitos do servidor (perfil escolhido: HTTP 409) disparam um caminho UX de conflito que não sobrescreve silenciosamente edições locais concorrentes.
- Reconciliação que excede o timeout do perfil entra em estado incerto e resolve via fetch-by-id ou polling, não pendente indefinidamente.
- Reconciliação bem-sucedida limpa o estado pendente e substitui os campos exibidos pelos valores do servidor, incluindo metadados de versão da entidade.
Orientações de implementação
- Centralize o middleware de mutação otimista para que todos os recursos compartilhem a semântica de reconciliação.
- Alinhe os ids de mutação do cliente com as chaves de idempotência da API onde o servidor as suporta.
- Use indicações sutis de pendência em vez de bloquear vistas inteiras, a menos que a política exija.
- Emita eventos de telemetria listados em
example.yamlpara revisão das operações.
Tratamento de falhas e salvaguardas
- Respostas de sucesso duplicadas não devem aplicar efeitos colaterais duas vezes nas máquinas de estado da interface.
- Não encadeie mutações otimistas que dependam de ids provisórios não resolvidos; mutações dependentes aguardam a reconciliação do predecessor ou referenciam identidade estável do servidor.
- Em caso de conflito, prefira mostrar a diferença do servidor em vez de retentar cegamente para evitar perda de edição.
Verificação e operações
- Monitore a taxa de reversão, taxa de conflito e taxa de timeout incerto por tipo de mutação.
- Testes automatizados cobrem caminhos de sucesso, falha, conflito, timeout e retentativa idempotente.
- Revise mutações com altas taxas de reversão para problemas no servidor ou validação.
Os exemplos executáveis neste pacote são fixtures e contratos de aceitação. Valide a estrutura do pacote antes da adoção; então implemente e execute os cenários no repositório alvo.
Premissas para adoção
- Timeout, códigos de status e nomes de cabeçalho em
example.yamlsão escolhas de perfil para um SPA de quadro de tarefas, não padrões universais. - As equipes devem mapear campos de versão da entidade para seus esquemas de API.
Referências
- Nenhuma fonte normativa externa é requerida; alinhe o comportamento de idempotência com seu bloco de idempotência da API quando adotado.