Mock de API com contrato primeiro

Por que começar com um contrato

Eu criei o MockDeck após ver equipes desperdiçarem semanas esperando por um backend que nunca chegava no prazo. O primeiro passo que dou com qualquer nova funcionalidade é escrever uma breve descrição do endpoint que tanto os engenheiros frontend quanto backend possam revisar. Essa descrição se torna o contrato. Quando o contrato está definido, 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 em um artefato concreto, cortamos o loop de feedback de dias para horas e evitamos a rework custosa que acontece quando suposições sobre a forma da carga ou 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 se torna uma única fonte de verdade que reduz a comunicação errada entre disciplinas. Ferramentas como o o o o podem ser úteis nesse processo, e é fundamental documentar tudo claramente, como no arquivo.

Escrevendo 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 de solicitação: strings de consulta, cabeçalhos e campos de corpo, marcando cada um como obrigatório ou opcional. Para cada campo, adiciono um tipo (string, número, booleano, array, 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. Finalmente, adiciono casos de erro que o frontend deve lidar: erros de validação (400), não encontrado (404), não autorizado (401), limitado de taxa (429) e erros de 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 (string, uuid) | Deve existir no banco de dados Corpo da solicitação – opcional | nota (string, máximo 500) | Comentário em 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 exibir 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 do 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 backend antes que qualquer código seja escrito. Ferramentas como o MockDeck, o o o podem ser úteis nesse processo.

Gerando a especificação mock

Uma vez que o contrato é escrito em um arquivo simples de markdown ou JSON, o MockDeck lê e produz três artefatos: um documento OpenAPI 3, uma coleção Postman e um arquivo de rotas brutos (JSON simples com caminho, método e respostas de exemplo). A saída OpenAPI inclui os esquemas exatos que você definiu, mais exemplos automaticamente gerados que parecem com dados reais — pense em nomes que seguem padrões típicos, números que caem dentro de faixas esperadas e strings que atingem comprimentos mínimos e máximos. A coleção Postman pode ser importada diretamente para o cliente de API que você usa para testes manuais, e o arquivo de rotas brutos 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 arquivo de contrato, você sempre obtém a mesma saída de mock. Isso permite que você commite os artefatos gerados para o seu repositório se você quiser um mock estático, ou você pode executar o MockDeck como parte do startup do seu servidor de desenvolvimento para manter o mock na memória. Como o mock é derivado do contrato, você nunca precisa manter duas fontes de verdade separadas; qualquer alteração no contrato é automaticamente propagada para o mock quando você regenera.

O MockDeck também adiciona algumas funcionalidades de conveniência embutidas: ele define cabeçalhos CORS apropriados para desenvolvimento local, adiciona um controle deslizante de latência para que você possa simular atraso de rede e registra cada solicitação no console para que você possa verificar se o frontend está atingindo o endpoint esperado com a carga útil correta.

Integrando mocks no fluxo de trabalho frontend

Nos meus projetos, eu 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 arquivo de rotas, 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, então o código-fonte 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 arquivo.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. Esse loop apertado encoraja os desenvolvedores a tratar o contrato como o primeiro artefato que eles modificam quando uma funcionalidade evolui.

Eu 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.

Controle de versão de contratos e tratamento de divergência

Os contratos evoluem assim como o código. Trato cada arquivo de contrato como versionado ao lado da branch de recurso. Quando uma alteração disruptiva é 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 divergência, 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 divergência é relatada como um aviso em nosso painel de CI. Essa abordagem capturou 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 ocaso em um comentário no topo do arquivo e mantenho a simulação ativa 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 explicação breve, tornando o ciclo de vida do contrato explícito. O é utilizado para documentar os processos e o é utilizado para melhorar a experiência do usuário. O é utilizado para auxiliar na criação de contratos e o é utilizado para testar a robustez dos contratos.

Teste de contrato como uma rede de segurança

O teste de contrato verifica 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 essa etapa no fluxo de trabalho de pull request 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 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 (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 teste 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 a ajuda de ferramentas como o e em conformidade com a documentação de.

O que isso não é

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

Não é um substituto de 100% para testes de ponta a ponta. Você ainda precisa 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.

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

Por fim, usar mocks de contrato em primeiro lugar não tornará 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

Isso é um servidor mock em execução?

Não. O MockDeck gera a especificação da API mock — OpenAPI 3, Postman ou rotas raw. Servi-la é uma etapa separada.

Ele pode chamar nosso backend real?

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

Quais formatos ele produz?

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

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

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

Quão realista são os dados de amostra?

Eles são gerados para parecerem com payloads reais, o que é suficiente para capturar bugs de formatação e estado vazio cedo. Não é dados de produção.

Ele valida nossa API existente contra o contrato?

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

Sim, o MockDeck pode ser utilizado para ajudar a atender às regulamentações de segurança.

O que o tem a ver com o MockDeck?

O é um modelo de linguagem que pode ser utilizado em conjunto com o MockDeck.

Sim, o MockDeck é projetado para atender às regulamentações de privacidade de dados.

O é compatível com o MockDeck?

Sim, o pode ser utilizado em conjunto com o MockDeck.

O o podem ser utilizados com o MockDeck?

Sim, o o podem ser utilizados em conjunto com o MockDeck.

O é compatível com o MockDeck?

Sim, o pode ser utilizado em conjunto com o MockDeck.

Referências

- Especificação OpenAPI - Esquema JSON

Experimente o produto: MockDeck

20-09-2026 · somente fontes primárias · sem métricas de tráfego fabricadas · somente para suporte à decisão

Artigos relacionados

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