Mock de API com base em contrato

Porque começar com um contrato

Construí o MockDeck após ver equipes desperdiçarem semanas à espera de um backend que nunca chegava a tempo. O primeiro passo que dou com qualquer nova funcionalidade é escrever uma breve descrição do endpoint que tanto os engenheiros frontend como backend possam rever. Essa descrição torna-se o contrato. Quando o contrato está fixo, o frontend pode começar a codificar contra um mock que se comporta exatamente como o serviço real fará, enquanto a equipe backend trabalha na implementação em paralelo. Isso elimina o período de inatividade em que os desenvolvedores olham para um 404 ou um placeholder que retorna apenas códigos de sucesso. Ao ancorar o trabalho a um artefacto concreto, cortamos o ciclo de feedback de dias para horas e evitamos a reexecução dispendiosa que acontece quando as suposições sobre a forma da carga ou o tratamento de erros se revelam erradas.

Quando um contrato existe desde cedo, os designers podem criar componentes de UI que consomem a forma de dados exata, a QA pode escrever casos de teste com base nas respostas de erro definidas, e a DevOps pode configurar servidores mock em ambientes de staging sem esperar pelo serviço real. O contrato torna-se uma única fonte de verdade que reduz a má comunicação entre disciplinas. Ferramentas como o o o podem ser úteis no desenvolvimento de contratos e na implementação de políticas de segurança, como descrito no.

Escrever o contrato

Um contrato precisa capturar todos os comportamentos observáveis do endpoint. Começo com o caminho HTTP e o método, então anoto qualquer esquema de autenticação (chave de API, token de portador, TLS mútuo). Em seguida, listo os parâmetros da solicitação: strings de consulta, cabeçalhos e campos do corpo, marcando cada um como obrigatório ou opcional. Para cada campo, adiciono um tipo (cadeia de caracteres, número, booleano, matriz, objeto) e um formato, se necessário (e-mail, data-hora, uuid). Em seguida, defino a resposta de sucesso: código de status, qualquer cabeçalho e a forma completa da carga útil com tipos e formatos. Por fim, adiciono casos de erro que o frontend deve lidar: erros de validação (400), não encontrado (404), não autorizado (401), limitado por taxa (429) e erros do servidor (5xx). Para cada erro, incluo um corpo de amostra que mostra a forma da mensagem de erro.

Elemento do contrato | Valor de exemplo | Notas Caminho | /v1/pedidos | Recurso com versão Método | POST | Cria um novo pedido Autenticação | Token de portador | Cabeçalho de autorização obrigatório Corpo da solicitação – obrigatório | customer_id (cadeia de caracteres, uuid) | Deve existir no banco de dados Corpo da solicitação – opcional | nota (cadeia de caracteres, máximo 500) | Comentário de forma livre Resposta de sucesso | 201, {order_id, created_at} | Cabeçalho de localização com URL Erro de validação | 400, {errors: [{field: "customer_id", message: "must be uuid"}]} | Ajuda o frontend a mostrar avisos inline Não encontrado | 404, {error: "pedido não encontrado"} | Ocorre em GET /v1/pedidos/:id quando o id é desconhecido

Mantenho o contrato em um arquivo de texto simples (YAML ou JSON) que vive ao lado da branch de recurso. Isso facilita a diferença de alterações durante a revisão de código e armazena o artefato no controle de versão ao lado do código-fonte. Quando um contrato muda, a diferença mostra exatamente qual campo foi adicionado, removido ou teve seu tipo alterado, provocando uma conversa entre os proprietários do frontend e do backend antes que qualquer código seja escrito.

Gerar a especificação mock

Uma vez que o contrato esteja escrito em um ficheiro markdown ou JSON simples, o MockDeck lê-o e produz três artefactos: um documento OpenAPI 3, uma coleção Postman e um ficheiro de rotas brutas (JSON simples com caminho, método e respostas de exemplo). A saída OpenAPI inclui os esquemas exactos que definiu, mais exemplos gerados automaticamente que parecem dados reais — pense em nomes que seguem padrões típicos, números que caem dentro de intervalos esperados e cadeias que atingem comprimentos mínimos e máximos. A coleção Postman pode ser importada directamente para o cliente de API que usa para testes manuais, e o ficheiro de rotas brutas pode ser servido por um servidor de mock leve (como Mirage JS ou json‑server) com zero configuração.

A etapa de geração é determinística: dado o mesmo ficheiro de contrato, sempre obtém a mesma saída mock. Isso permite que comite os artefactos gerados para o seu repositório se quiser um mock estático, ou pode executar o MockDeck como parte do arranque do servidor de desenvolvimento para manter o mock na memória. Como o mock é derivado do contrato, nunca tem de manter duas fontes de verdade separadas; qualquer alteração ao contrato propaga-se automaticamente ao mock quando regenera.

O MockDeck também adiciona algumas funcionalidades de conveniência fora da caixa: define cabeçalhos CORS apropriados para desenvolvimento local, adiciona um controlo deslizante de latência para que possa simular atrasos de rede e regista cada pedido no console para que possa verificar se a interface de utilizador está a atingir o endpoint esperado com a carga útil correcta.

Integração de mocks no fluxo de trabalho frontend

Nos meus projetos, adiciono um script de inicialização que lança o servidor de mock antes do servidor de desenvolvimento frontend. O script lê a pasta de contrato, executa o MockDeck para produzir o ficheiro de rotas, e então inicia um servidor node-express que serve essas rotas em http://localhost:3001. O proxy frontend é configurado para encaminhar todas as solicitações /api para essa porta, de modo que a base de código vê uma camada de API suave sem alterações na fonte.

- Adicione um diretório de contratos na raiz do repositório. - Para cada endpoint, crie um ficheiro.yaml que segue a estrutura descrita anteriormente. - Adicione um script start:mock em package.json que executa mockdeck build./contracts --out./mock e, em seguida, node./mock/server.js. - Configure o servidor de desenvolvimento frontend (por exemplo, Vite, CRA) para proxy /api para http://localhost:3001. - Execute npm run start:mock em um terminal e npm run dev em outro.

Quando um contrato muda, você só precisa reiniciar o script de mock; o frontend pega o novo comportamento instantaneamente porque o proxy encaminha para o servidor de mock atualizado. Este loop apertado encoraja os desenvolvedores a tratar o contrato como o primeiro artefato que modificam quando uma funcionalidade evolui.

Também escrevo um simples teste Jest que importa o documento OpenAPI gerado e afirma que o formato da solicitação corresponde às chamadas de API do componente. Isso fornece uma rede de segurança extra: se um desenvolvedor mudar acidentalmente a carga útil da solicitação na interface do usuário, o teste falha e aponta o contrato como a fonte de verdade.

Versionamento de contratos e tratamento de deriva

Os contratos evoluem assim como o código. Trato cada arquivo de contrato como versionado ao lado da branch de funcionalidade. Quando uma alteração de quebra é necessária — como renomear um campo ou alterar uma flag obrigatória — crio uma nova versão do contrato (por exemplo, v2/pedido-criar.yaml) e atualizo o gerador OpenAPI para incluir um bloco de servidores que aponta para o caminho versionado. O servidor de simulação serve então ambas as versões simultaneamente, permitindo que o frontend opte pela nova contrato alterando a URL base.

Para detectar deriva, executo um trabalho noturno que compara a especificação OpenAPI do backend ao vivo (gerada a partir do código real) com a especificação gerada pelo contrato. Qualquer discordância é relatada como um aviso no nosso painel de CI. Esta abordagem detectou casos em que um desenvolvedor backend adicionou um novo campo opcional sem atualizar o contrato, o que teria causado erros de validação frontend em produção.

Quando um contrato é depreciado, adiciono uma data de pôr do sol em um comentário no topo do arquivo e mantenho o simulador ativo por duas semanas após a data para dar tempo às equipes de migrar. Após esse período, o servidor de simulação retorna uma resposta 410 Gone com uma breve explicação, tornando o ciclo de vida do contrato explícito.

Testes de contrato como uma rede de segurança

Os testes de contrato verificam se o MockDeck e a implementação real falam a mesma linguagem. Eu uso uma ferramenta como Pact ou Dredd para executar o contrato contra ambos o servidor mock e o backend de staging. A suíte de testes envia cada solicitação definida no contrato, verifica o código de status da resposta, cabeçalhos e esquema do corpo, e registra qualquer desvio.

Incorporar esta etapa no fluxo de trabalho de solicitação de pull significa que uma alteração no backend que quebre o contrato fará com que a compilação falhe antes de alcançar o master. Da mesma forma, se um desenvolvedor frontend atualizar a carga útil da solicitação sem atualizar o contrato, o teste falhará porque o mock não reconhecerá a nova forma.

Para equipes focadas em segurança, eu também executo o contrato contra as diretrizes OWASP Top-10 (https://owasp.org/www-project-top-10-for-large-language-model-applications) para garantir que os mocks gerados não expõem inadvertidamente padrões perigosos, como upload de arquivo irrestrito ou vazamento excessivo de dados.

A suíte de testes de contrato é executada em menos de dois segundos em um laptop típico, então adiciona uma sobrecarga negligenciável ao pipeline de CI enquanto entrega alta confiança de que o mock permanece fiel à especificação acordada, com o auxílio de ferramentas como o conforme descrito em.

O que isto não é

Esta abordagem não garante que o backend será entregue no prazo. Um mock pode apenas simular comportamento; não pode substituir a lógica de negócios real, as interações com o banco de dados ou as chamadas de serviço externas que a implementação real irá realizar.

Não é um substituto de 100 % para testes de ponta a ponta. Ainda é necessário verificar que o sistema integrado funciona corretamente com dados autênticos, características de desempenho e condições de erro que podem aparecer apenas sob carga.

Não remove a necessidade de comunicação clara entre equipes. O contrato é uma ferramenta para facilitar a discussão, mas não substitui as reuniões regulares, revisões de design ou documentação compartilhada.

Por fim, o uso de mocks de contrato em primeiro lugar não tornará o seu produto imune a erros de especificação. Se o contrato em si for ambíguo ou incompleto, o mock implementará fielmente essas lacunas e o frontend será construído com base em uma suposição defeituosa. Trate o contrato como um documento vivo que evolui com feedback de ambos os lados.

Referências

- https://owasp.org/www-project-top-10-for-large-language-model-applications - https://www.nist.gov/itl/ai-risk-management-framework

Perguntas frequentes

Isto é um servidor mock em execução?

Não. O MockDeck gera a especificação da API mock — OpenAPI 3, Postman ou rotas brutas. Servi-la é um passo separado.

Pode chamar o nosso backend real?

Não. Ele não proxy ou executa o seu backend; a saída é uma especificação e respostas de amostra.

Quais formatos ele produz?

OpenAPI 3, coleções do Postman ou rotas brutas.

Por que se preocupar com respostas de erro em um mock?

Porque é aí que o código frontend geralmente quebra. Um mock que só retorna 200s esconde os estados que você mais precisa lidar.

Quão realista é o dados de amostra?

Ele é gerado para parecer com payloads reais, o que é suficiente para capturar bugs de formatação e estado vazio cedo. Não é dados de produção.

Ele valida a nossa API existente contra o contrato?

Não. Testes de contrato e validação são ferramentas separadas.

Sim, esses tópicos são considerados no desenvolvimento do MockDeck.

Referências

- Especificação OpenAPI - Esquema JSON

Experimente o produto: MockDeck

2026-09-20 · apenas fontes primárias · nenhum tráfego métrico fabricado · apenas suporte à decisão

Artigos relacionados

- Servidores Mock vs exemplos OpenAPI - Explore a matriz completa de tópicos de micro-SaaS de IA →