Contratos de interface e evidência de aceitação

1. Dar significado aos dados

O campo limite pode estar ausente, conter null ou conter zero. Estas três mensagens têm estruturas distinguíveis; o negócio ainda precisa de definir o seu significado. No exercício, ausência conserva o limite atual, null remove um limite opcional e zero define um limite de zero. Um adaptador que converte os três casos em zero destrói duas intenções. Regista ainda unidade, precisão, domínio de valores e regras de arredondamento quando existam. Uma coluna valor sem moeda ou escala pode ser interpretada de forma diferente por dois consumidores. Para uma instrução fictícia, 1250 representa 12,50 unidades porque o contrato fixou centésimos inteiros. Isso não é uma regra universal para todas as moedas ou produtos. Revê exemplos inválidos, fronteiras e a informação que deve voltar ao utilizador quando um valor é recusado.

Exercício de precisão: três encargos de 0,335, arredondados individualmente a dois decimais com empate para cima, somam 1,02. Somar antes de arredondar dá 1,005 e depois 1,01. Regista qual percurso foi acordado; não escolhas apenas o resultado mais conveniente. Para datas, declarar uma string com format: date-time pode acrescentar apenas uma anotação na ferramenta usada. Em OpenAPI, o comportamento de validação depende do suporte e da configuração. Se o requisito exige um instante inequívoco, verifica efetivamente valores inválidos e offsets em vez de assumir que o documento executa essa verificação.

2. Avaliar compatibilidade com consumidores concretos

A versão inicial só devolve pendente ou concluído. A nova versão acrescenta revisão manual. Um consumidor ignora campos desconhecidos, mas rejeita estados fora desses dois valores.

Acrescentar um estado pode quebrar esse consumidor, embora o documento continue válido e nenhum campo antigo tenha desaparecido. Identifica comportamentos reais de leitura, validação e apresentação. Define que versões coexistem, como um estado novo é representado para cada uma e como se impede que uma situação não terminal seja apresentada como concluída.

Uma opção pode adiar a exposição do novo estado até atualizar o consumidor; outra pode fornecer uma tradução acordada que preserve significado e capacidades necessárias. Não escolhas uma tradução apenas para fazer o parser passar. A decisão deve conservar o resultado de negócio e as restrições identificadas.

3. Proteger decisões tomadas sobre uma versão

Duas pessoas consultam a instrução na versão v5. A primeira muda a conta de destino e cria v6. A segunda tenta mudar o montante usando o documento v5 completo.

Sem uma condição, pode repor involuntariamente a conta antiga. No exemplo HTTP, If-Match com o ETag forte da versão lida permite condicionar a alteração à representação esperada. Se a condição não corresponder, o serviço não deve executar essa alteração como se nada tivesse mudado.

O caso assume pedidos diferentes e uma rejeição 412; não trata a exceção de um pedido já aplicado. Define a experiência de recuperação: obter o estado atual, mostrar a diferença relevante e confirmar a alteração pretendida antes de a reenviar.

Substituir automaticamente o ETag pela versão mais recente pode contornar a proteção sem resolver o conflito de negócio.

4. Separar descrição de segurança e acesso demonstrado

Uma interface exige dois mecanismos em conjunto, aqui chamados token e certificado. Em OpenAPI, dois esquemas no mesmo Security Requirement Object representam requisitos conjuntos; objetos diferentes na lista representam alternativas. Por isso, security: [{token: [], certificado: []}] tem significado diferente de security: [{token: []}, {certificado: []}].

Estes nomes pressupõem esquemas definidos no documento e servem apenas para ler o contrato. A descrição não demonstra que o servidor aplica a regra. O plano de aceitação precisa de pedidos com ambos os mecanismos e com cada um em falta, conforme o âmbito autorizado do teste.

Precisa também de verificar que uma identidade válida só consulta operações que lhe pertencem. Uma chave de correlação conhecida não deve, por si só, conceder acesso ao resultado de outro cliente.

5. Especificar critérios que possam falhar

Um bom exemplo de aceitação identifica estado inicial, ação, observação esperada e ponto de observação. Para identidade repetida, não basta contar respostas HTTP: confirma o número de movimentos autorizados e a relação entre cada resposta e a operação.

Inclui tentativas simultâneas, conteúdo diferente com a mesma chave, perda de resposta e a fronteira de retenção. Para o prazo, define qual evento começa e termina o relógio. Num conjunto fictício de 100 operações elegíveis, 100 recebem confirmação em dois segundos e 98 concluem em dois minutos.

O critério exige pelo menos 99 conclusões dentro desses dois minutos. A confirmação rápida cumpre outra observação; não satisfaz este critério. Conserva resultados que falham e os que não foram executados como situações diferentes, sem mudar o denominador depois de ver a resposta.

6. Decidir por item num lote parcial

O contrato de um lote permite resultados independentes por item e identidade estável para cada instrução. A está confirmada, B foi enviada ao parceiro mas tem resultado desconhecido e C ainda não foi enviada. O reprocessamento de todo o lote com novas identidades pode repetir A e B.

Marcar o lote inteiro como falhado também oculta o movimento de A. Prepara um quadro por item: efeito confirmado, efeito por apurar ou ausência de envio demonstrada. No exercício, C pode seguir a via normal, A conserva o resultado e B entra em reconciliação pela identidade original.

Esta conclusão depende das regras dadas. Se o contrato exigir atomicidade do lote inteiro, é necessário outro desenho e outra evidência. Não transportes a política de resultados independentes para um lote com obrigação de tudo ou nada.

7. Interpretar a ordem da evidência

O serviço emite uma sequência crescente por operação: 16 em execução e 17 concluída. A rede entrega primeiro 17 e depois 16. Uma interface que aplica simplesmente a última notificação recebida faz a operação recuar indevidamente.

Na política do exercício, a sequência atribuída pela fonte é monotónica dentro da mesma operação e não reinicia. Logo, 17 prevalece e 16 pode ser mantida como evidência histórica sem substituir o estado atual. Se a sequência reiniciar entre instâncias, faltar uma parte da identidade ou existirem fontes concorrentes, esta regra deixa de estar suficientemente definida.

Pede a clarificação dessas condições antes de generalizar. Ao reportar um incidente, separa a ordem em que o efeito ocorreu da ordem em que suporte recebeu os registos. A hora do ecrã pode medir receção, não execução.

8. Exercício: construir o pacote de aceitação

A versão candidata R2 declara proteção durante 72 horas, consulta limitada ao cliente e resultados independentes por item. Tens três evidências: E1 repetiu A/K7 ao fim de uma hora em R1; E2 criou duas tentativas simultâneas de A/K8 em R2 e encontrou um movimento; E3 mostrou o resultado de B/K9 a uma sessão autenticada como A em R2.

Prepara o relatório antes de ler a análise. E2 apoia o caso simultâneo que executou; não cobre sozinho 72 horas. E1 é evidência histórica cuja aplicabilidade e janela são insuficientes para essa afirmação.

E3 demonstra falha do isolamento acordado. Propõe testes para 71h59, exatamente 72h e comportamento depois da janela, usando o relógio definido no requisito. Regista a diferença entre requisitos satisfeitos, requisitos sem evidência e requisitos com falha; encaminha a decisão segundo a autoridade acordada. O ficheiro OpenAPI correto não elimina E3.

Ensaiar a fronteira sem reescrever o histórico

Exercício independente: a proteção vale até 48 horas inclusive desde o primeiro commit e repetições não mudam esse instante. Depois disso, a mesma chave com novo conteúdo e autorização válida deve permitir uma nova operação. Um ensaio começa em zero, repete sem novo efeito em 47 e volta a repetir o conteúdo original em 48, criando outro efeito. Um segundo ensaio independente faz a mesma preparação e cria corretamente uma operação autorizada com novo conteúdo em 49. Identifica a evidência por condição antes de atribuir estado ao requisito inteiro.

O primeiro ensaio falha na fronteira inclusiva; o segundo passa a condição de novo uso após expiração. Não há duas falhas nem cumprimento integral. Um ensaio antigo a duas horas pode continuar válido se a sua equivalência tiver sido confirmada, mas não resolve a falha em 48. Repetições em 47 não deslocam a fronteira para 95. Os registos permitem identificar a condição violada, mas não provam se o defeito vem de comparação temporal, armazenamento ou outra causa. No trabalho, conserva instante inicial, versão, autorização, conteúdo e efeito observado. Liga cada teste à condição exata e planeia recolha para as lacunas. Resumo: ampliar um requisito temporal exige evidência das novas fronteiras, preservando o alcance honesto dos resultados antigos.

Armadilhas comuns

Tratar null como ausência; supor que toda adição é compatível; aceitar só exemplos felizes; confundir descrição de segurança com aplicação real; usar chegada de notificações como ordem de execução; reenviar um lote parcial com identidades novas.