Arquitetura9 min de leitura

GraphQL vs REST: Quando usar e quando evitar

Over-fetching e under-fetching na prática, o problema N+1 e como o DataLoader resolve, caching com persisted queries, schema tipado com resolvers, e quando REST ainda é a escolha certa.

12 de agosto de 2026

O Facebook criou o GraphQL em 2012 para resolver um problema concreto: o app mobile do Facebook estava lenificando porque cada tela precisava de múltiplas chamadas REST para montar a UI — o feed, os amigos online, as notificações. Em conexões 3G lentas da época, cada round-trip adicional custava segundos de latência.

GraphQL não é substituto do REST — é uma solução para problemas específicos. Entender quando ele resolve e quando cria mais problemas do que resolve é a diferença entre uma decisão de arquitetura fundamentada e uma adoção por hype.

O Problema Central: Over-fetching e Under-fetching

A diferença fundamental é quem decide o shape da resposta. Em REST, o servidor decide: GET /users/1 retorna o que o endpoint foi programado para retornar. Em GraphQL, o cliente decide: a query especifica exatamente quais campos quer. Para um app com múltiplos clientes (mobile, web, TV, parceiros) com necessidades muito diferentes, o GraphQL elimina a proliferação de endpoints especializados. Para uma API simples usada por um único cliente, REST é mais simples de implementar, cachear e depurar.

Over-fetching — a API retorna mais dados do que o cliente precisa. GET /users/1 retorna 40 campos, mas a tela de listagem usa apenas name e avatar. Em mobile, isso desperdiça banda e bateria.
Under-fetching — a API não retorna dados suficientes, exigindo múltiplas requisições. Para montar a tela de perfil: GET /users/1, depois GET /users/1/posts, depois GET /users/1/followers. São 3 round-trips que poderiam ser 1.
Múltiplos clientes com necessidades diferentes — o app mobile precisa de campos diferentes da versão web que precisa de campos diferentes do app de TV. Com REST, você cria endpoints especializados para cada um, ou todos sofrem de over-fetching.

Como o GraphQL Resolve

Query declarativa — cliente define o shape da resposta

1# O cliente pede EXATAMENTE o que precisa em uma única requisição
# O cliente pede EXATAMENTE o que precisa em uma única requisição
2# Todos os campos são declarados explicitamente
# Todos os campos são declarados explicitamente
3

4query GetUserProfile($userId: ID!) {
query GetUserProfile($userId: ID!) {
5  user(id: $userId) {
  user(id: $userId) {
6    id
    id
7    name
    name
8    avatar   # Apenas estes 3 campos, não os 40 que o banco tem
    avatar   # Apenas estes 3 campos, não os 40 que o banco tem
9

10    # Relacionamentos resolvidos no mesmo round-trip
    # Relacionamentos resolvidos no mesmo round-trip
11    posts(limit: 3, orderBy: { createdAt: DESC }) {
    posts(limit: 3, orderBy: { createdAt: DESC }) {
12      id
      id
13      title
      title
14      likesCount
      likesCount
15    }
    }
16

17    # Campos calculados pelo servidor
    # Campos calculados pelo servidor
18    followersCount
    followersCount
19    isFollowedByMe
    isFollowedByMe
20  }
  }
21}
}

Schema e Resolvers no Node.js

typeDefs.ts

1import { gql } from 'graphql-tag';
import { gql } from 'graphql-tag';
2

3export const typeDefs = gql`
export const typeDefs = gql`
4  type User {
  type User {
5    id: ID!
    id: ID!
6    name: String!
    name: String!
7    email: String!
    email: String!
8    avatar: String
    avatar: String
9    posts(limit: Int, offset: Int): [Post!]!
    posts(limit: Int, offset: Int): [Post!]!
10    followersCount: Int!
    followersCount: Int!
11  }
  }
12

13  type Post {
  type Post {
14    id: ID!
    id: ID!
15    title: String!
    title: String!
16    content: String!
    content: String!
17    author: User!
    author: User!
18    likesCount: Int!
    likesCount: Int!
19    createdAt: String!
    createdAt: String!
20  }
  }
21

22  type Query {
  type Query {
23    user(id: ID!): User
    user(id: ID!): User
24    users(page: Int, pageSize: Int): [User!]!
    users(page: Int, pageSize: Int): [User!]!
25    post(id: ID!): Post
    post(id: ID!): Post
26  }
  }
27

28  type Mutation {
  type Mutation {
29    createPost(title: String!, content: String!): Post!
    createPost(title: String!, content: String!): Post!
30    followUser(userId: ID!): Boolean!
    followUser(userId: ID!): Boolean!
31  }
  }
32`;
`;

resolvers.ts

1import type { Resolvers } from './__generated__/resolvers-types';
import type { Resolvers } from './__generated__/resolvers-types';
2

3export const resolvers: Resolvers = {
export const resolvers: Resolvers = {
4  Query: {
  Query: {
5    user: async (_parent, { id }, context) => {
    user: async (_parent, { id }, context) => {
6      return context.usersRepo.findById(id);
      return context.usersRepo.findById(id);
7    },
    },
8    users: async (_parent, { page = 1, pageSize = 20 }, context) => {
    users: async (_parent, { page = 1, pageSize = 20 }, context) => {
9      return context.usersRepo.findAll({ page, pageSize });
      return context.usersRepo.findAll({ page, pageSize });
10    },
    },
11  },
  },
12

13  // Resolvers de campo: executados apenas se o campo for solicitado
  // Resolvers de campo: executados apenas se o campo for solicitado
14  User: {
  User: {
15    // Este resolver só roda se o cliente pedir 'posts' no query
    // Este resolver só roda se o cliente pedir 'posts' no query
16    posts: async (user, { limit = 10, offset = 0 }, context) => {
    posts: async (user, { limit = 10, offset = 0 }, context) => {
17      return context.postsRepo.findByAuthor(user.id, { limit, offset });
      return context.postsRepo.findByAuthor(user.id, { limit, offset });
18    },
    },
19    // Contador calculado em tempo real
    // Contador calculado em tempo real
20    followersCount: async (user, _args, context) => {
    followersCount: async (user, _args, context) => {
21      return context.followsRepo.countFollowers(user.id);
      return context.followsRepo.countFollowers(user.id);
22    },
    },
23  },
  },
24

25  Post: {
  Post: {
26    // Resolver de relacionamento — cuidado com o problema N+1 aqui!
    // Resolver de relacionamento — cuidado com o problema N+1 aqui!
27    author: async (post, _args, context) => {
    author: async (post, _args, context) => {
28      // Sem DataLoader: N queries para N posts
      // Sem DataLoader: N queries para N posts
29      // Com DataLoader: 1 query batched para todos os posts
      // Com DataLoader: 1 query batched para todos os posts
30      return context.loaders.user.load(post.authorId);
      return context.loaders.user.load(post.authorId);
31    },
    },
32  },
  },
33

34  Mutation: {
  Mutation: {
35    createPost: async (_parent, { title, content }, context) => {
    createPost: async (_parent, { title, content }, context) => {
36      if (!context.user) throw new Error('Não autenticado');
      if (!context.user) throw new Error('Não autenticado');
37      return context.postsRepo.create({ title, content, authorId: context.user.id });
      return context.postsRepo.create({ title, content, authorId: context.user.id });
38    },
    },
39  },
  },
40};
};

O Problema N+1 e DataLoader

O maior risco do GraphQL: quando o cliente pede uma lista de posts com os autores, o resolver Post.author é chamado uma vez por post. Com 100 posts, isso é 100 queries ao banco. O DataLoader resolve isso com batching: acumula todos os authorId solicitados e faz uma única query com WHERE id IN (...):

bash

1npm install dataloader
npm install dataloader

loaders.ts

1import DataLoader from 'dataloader';
import DataLoader from 'dataloader';
2import type { IUsersRepository } from '../domain/repositories/IUsersRepository';
import type { IUsersRepository } from '../domain/repositories/IUsersRepository';
3

4// Um DataLoader por tipo de entidade
// Um DataLoader por tipo de entidade
5export function createLoaders(usersRepo: IUsersRepository) {
export function createLoaders(usersRepo: IUsersRepository) {
6  return {
  return {
7    user: new DataLoader(async (userIds: readonly Array<string>) => {
    user: new DataLoader(async (userIds: readonly Array<string>) => {
8      // Uma única query para todos os IDs solicitados no mesmo tick
      // Uma única query para todos os IDs solicitados no mesmo tick
9      const users = await usersRepo.findByIds([...userIds]);
      const users = await usersRepo.findByIds([...userIds]);
10

11      // O DataLoader exige que o resultado seja mapeado na mesma ordem dos IDs
      // O DataLoader exige que o resultado seja mapeado na mesma ordem dos IDs
12      const usersMap = new Map(users.map((u) => [u.id, u]));
      const usersMap = new Map(users.map((u) => [u.id, u]));
13      return userIds.map((id) => usersMap.get(id) ?? new Error(`User ${id} not found`));
      return userIds.map((id) => usersMap.get(id) ?? new Error(`User ${id} not found`));
14    }),
    }),
15  };
  };
16}
}
17

18// O DataLoader é criado POR REQUISIÇÃO (no contexto do Apollo Server)
// O DataLoader é criado POR REQUISIÇÃO (no contexto do Apollo Server)
19// para evitar cache entre requisições de usuários diferentes:
// para evitar cache entre requisições de usuários diferentes:
20// context: () => ({ ..., loaders: createLoaders(usersRepo) })
// context: () => ({ ..., loaders: createLoaders(usersRepo) })

Desvantagens Reais do GraphQL

Cache HTTP — REST caches por URL (CDN, browser cache, HTTP headers). GraphQL usa um único endpoint POST /graphql — o cache convencional não funciona. Solução: Persisted Queries (queries pré-registradas com ID), APQ (Automatic Persisted Queries) do Apollo.
Complexidade operacional — rate limiting por operação é difícil (uma query pode ser mais cara que outra). Depth limiting, complexity limiting e query whitelisting adicionam camadas de config.
Superficie de ataque — um endpoint exposto que aceita queries arbitrárias pode ser alvo de denial-of-service via queries excessivamente complexas. Sem complexity limits, um cliente malicioso pode derrubar o servidor.
Curva de aprendizado — schema, resolvers, DataLoader, N+1, context, field policies, code generation. REST é mais simples de entender e debugar.
Over-engineering para CRUDs simples — se sua API é basicamente GET/POST/PUT/DELETE em recursos simples com poucos clientes, REST é mais adequado.

Quando usar GraphQL: múltiplos clientes (web, mobile, TV) com necessidades diferentes de dados, APIs com muitos relacionamentos entre entidades, product teams que querem autonomia para compor seus próprios dados sem coordenar com o backend. Quando usar REST: APIs simples, APIs públicas consumidas por terceiros (REST é mais familiar), microserviços comunicando entre si, arquiteturas onde CDN cache é crítico.

Conclusão

GraphQL brilha em plataformas complexas com múltiplos clientes — é por isso que Facebook, GitHub, Shopify e Twitter o adotaram. Para projetos mais simples ou APIs públicas, REST é mais simples de implementar, debugar, cachear e documentar. A escolha não é ideológica — é sobre qual ferramenta resolve o problema específico com menos trade-offs.