Gerador de schema GraphQL mock

Mock schemas em GraphQL: SDL, tipos e desenvolvimento front-end paralelo

GraphQL é uma linguagem de consulta e um runtime para APIs, criada por Lee Byron e colegas dentro do Facebook em 2012 para resolver os problemas de over-fetching e under-fetching do REST. Foi liberada como open source em 2015 e hoje é mantida pela GraphQL Foundation, parte da Linux Foundation. Em vez de várias requisições para endpoints diferentes, uma única consulta GraphQL descreve exatamente os campos que o cliente precisa, e o servidor devolve um JSON com o mesmo formato da consulta. Um schema mock é um schema com resolvers de mentirinha que devolvem dados falsos mas bem tipados, permitindo que o front-end avance sem esperar a implementação do back-end ficar pronta.

Este gerador monta um esqueleto SDL mínimo para um recurso; a referência abaixo cobre os fluxos schema-first vs code-first, o sistema de tipos, as principais ferramentas de mock e os padrões de produção que separam uma API GraphQL séria de um exemplo de tutorial.

Schema-first vs code-first

Duas filosofias dominam o ecossistema. Schema-first declara o contrato da API primeiro em SDL (Schema Definition Language) e depois conecta resolvers que atendem o contrato — usado pelo Apollo Server, GraphQL Yoga e a maior parte do stack JavaScript. Code-first gera o SDL a partir de classes ou funções tipadas — usado por TypeGraphQL, Pothos, NestJS GraphQL e Hot Chocolate (.NET). Schema-first mantém designers e back-end alinhados em torno de um documento único; code-first elimina o desalinhamento entre tipos e resolvers, mas o schema só aparece depois do build.

type Query {
  user(id: ID!): User
  users(limit: Int = 10): [User!]!
}
type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}
type Post {
  id: ID!
  title: String!
  author: User!
}

Sistema de tipos

• Escalares: Int, Float, String, Boolean, ID. Escalares customizados (DateTime, JSON, UUID) são comuns via graphql-scalars.
• Object types: entidades do domínio com campos nomeados, o feijão com arroz de qualquer schema.
• Enums: conjuntos fechados como enum Role { ADMIN USER GUEST }.
• Input types: pacotes de argumentos para mutations (input CreateUserInput { ... }).
• Interfaces e unions: polimorfismo — interface Node { id: ID! } ou union SearchResult = User | Post.
• Listas e non-null: [Post!]! é uma lista não-nula de posts não-nulos. A riqueza de nullability é uma das maiores vantagens do GraphQL sobre REST.

Estratégias e ferramentas de mock

Existem três estratégias comuns, conforme o realismo necessário:

• Aleatório a cada chamada: cada query retorna dados novos. Setup mais simples — use Apollo Server com mocks: true, GraphQL Faker ou @graphql-tools/mock addMocksToSchema.
• Determinístico por ID: faça o seed do PRNG pelo ID consultado para que o mesmo lookup devolva o mesmo payload entre reloads — ideal para Storybook e regressão visual.
• Estado persistido: guarde os mocks em IndexedDB / LocalForage para que create/update/delete se comportem como um backend real. MSW (Mock Service Worker) intercepta requisições no nível de rede e é o padrão moderno para test suites de front-end.

Para fixtures de Storybook, mocks determinísticos são essenciais — um avatar aleatório quebra teste de pixel-diff. Para ambientes de demo, mocks persistidos deixam product managers clicarem em fluxos ponta a ponta sem banco de verdade.

REST vs GraphQL e padrões de produção

GraphQL resolve over-fetching (REST devolve mais campos do que o necessário) e under-fetching (REST força várias requisições). O custo é uma nova classe de problemas: o N+1 (um resolver pai carrega N filhos um por um) é mitigado pelo DataLoader, um cache com batching do Facebook. Autorização sai do nível de URL (middleware REST) para o nível de campo (guards no resolver). Paginação deve usar a spec cursor do Relay (edges, pageInfo, cursor) em vez de offset/limit. Erros são cada vez mais modelados como union types (Result pattern) para o cliente lidar com eles com a mesma type-safety dos casos de sucesso. Em microsserviços, Apollo Federation e GraphQL Mesh compõem subgraphs em um único supergraph.

FAQ

GraphQL substitui REST? Não — ele complementa. Muitas empresas mantêm APIs REST públicas e adicionam um gateway GraphQL para clientes internos e parceiros. Os dois podem coexistir atrás do mesmo load balancer.

Mock ajuda mesmo no trabalho paralelo? Sim. Uma vez que o SDL está acordado, time de front e back desenvolvem contra o mesmo contrato de forma independente. Contract tests (ex.: graphql-codegen contra o SDL) pegam desalinhamento antes da integração.

Qual ferramenta de mock escolher? Para testes unitários dentro de um app JS, MSW. Para um backend fake durante dev local, Apollo Server com mocks: true. Para explorar um schema público, GraphQL Faker. Para Storybook, mocks customizados por story.

Onde aprender a spec oficial? graphql.org/learn para o tutorial e spec.graphql.org para a gramática formal. The Guild mantém um ecossistema enorme (Codegen, Mesh, Yoga, Inspector).