As expectativas do consumidor, incluindo autenticação e formatos de erro, são verificadas contra o provedor real no CI antes do merge; códigos de status HTTP não podem ser simulados em nenhum dos lados do contrato.
Status do pacote: contexto de referência pronto para revisão humana. O contrato e os cenários de teste estão completos, mas não se afirma que uma implementação adotante os tenha aprovado.
Decisão
Interfaces de serviço são governadas por contratos orientados pelo consumidor: o consumidor publica as requisições que enviará e as respostas que requer, incluindo cabeçalhos de autenticação e corpos de erro. O CI do provedor verifica essas expectativas contra o provedor em execução antes que uma mudança breaking possa ser mesclada. Testes que substituem códigos de status por mocks sempre 200 não são testes de contrato.
Escopo
- Pares consumidor-provedor HTTP ou de mensagens, publicação de contrato, verificação do provedor no CI e classificação de mudança breaking versus aditiva.
- Presença de cabeçalhos de autenticação/autorização, formato do objeto de erro e payloads de sucesso.
- Serviços backend que evoluem independentemente.
Fora deste bloco
- Jornadas completas de produto end-to-end e testes de snapshot de UI.
- Evolução de esquema de eventos para tópicos assíncronos, que possui suas próprias regras de compatibilidade.
Contrato
- Cada contrato do consumidor nomeia o provedor, operação, cabeçalhos de requisição obrigatórios e códigos de status permitidos, incluindo pelo menos um status de erro documentado.
- A verificação do provedor falha o merge se um campo obrigatório desaparecer, um código de status mudar de significado ou um código de erro for renomeado.
- Esquemas de autenticação usados em produção (por exemplo, tokens de acesso bearer) aparecem no contrato como cabeçalhos ou claims obrigatórios, não apenas omitidos no caminho feliz.
- Respostas de erro mantêm um
codede máquina estável e classe de status HTTP acordada no contrato. - Campos de resposta opcionais aditivos são compatíveis; remover ou alterar o tipo de um campo consumido é breaking.
- Testes de contrato executam contra o processo do provedor ou uma fixture gravada do provedor que ainda retorna códigos de status reais, nunca um stub que mapeia todas as falhas para 200.
Implementação
- Publique contratos a partir dos testes do consumidor como artefatos que o pipeline do provedor busca em alterações de handler, serializer ou autenticação.
- Inclua operações não autorizadas e não encontradas na suíte padrão do consumidor.
Tratamento de falhas
- Se o provedor não puder iniciar, o pipeline falha em vez de pular contratos.
- Mudanças breaking aumentam a versão da API e migram consumidores; não enfraquecem o contrato antigo em vigor.
Verificação
- Remova um campo consumido em uma branch e assegure que o CI do provedor falhe.
- Reproduza requisições não autorizadas e espere o corpo 401 ou 403 contratado.
Os exemplos executáveis neste pacote são fixtures e contratos de aceitação. Execute
python tools/validate.py a partir da raiz da coleção para verificar a estrutura e metadados do pacote; então
implemente e execute os cenários no repositório alvo.
Suposições de adoção
- Nomes e valores numéricos em
example.yamlsão um perfil de adoção, não padrões universais. - A equipe adotante deve mapear atores, classes de dados, vocabulário de erro e propriedade para seu sistema.
Referências
- Contratos orientados pelo consumidor são descritos por Fowler em https://martinfowler.com/articles/consumerDrivenContracts.html.
- Descrições de interface HTTP podem seguir OpenAPI 3.1; este bloco não requer um fornecedor específico de broker.