GraphQL Subscriptions: Guia Passo a Passo Prático

GraphQL subscriptions resolvem um problema específico: entregar dados atualizados sem o cliente ficar perguntando de novo. Se você já tem um servidor GraphQL rodando, o caminho é curto. Antes de começar, garanta Node.js instalado, um servidor GraphQL funcional (Apollo Server ou similar) e noções básicas de schema. O resultado esperado ao final: um cliente recebendo mensagens em tempo real via WebSocket.

Passo 1: Defina a subscription no schema

No seu schema, adicione um tipo Subscription com o evento que você quer transmitir. Algo como postAdded: Post. O erro comum aqui é esquecer que subscriptions não retornam listas: elas emitem um evento por vez. Se você precisa de vários itens, o cliente acumula.

Passo 2: Configure o pubsub no servidor

Instale o pacote graphql-subscriptions (disponível no npm, conforme o registro do Wikidata) e crie uma instância do PubSub. No resolver da mutation, publique o evento; no resolver da subscription, use pubsub.asyncIterator. A dica que economiza horas: não use o PubSub em memória em produção com múltiplas instâncias. Ele não compartilha estado entre processos. Para isso, o caminho é Redis ou outro backend externo.

Passo 3: Conecte o cliente via WebSocket

No cliente, troque o link HTTP por um link WebSocket (graphql-ws é a opção mais atual). Assine a operação e trate reconexão. Erro comum: esquecer de fechar a subscription ao desmontar o componente. Isso vaza conexão e derruba o servidor em pouco tempo.

Checklist rápido

• Tipo Subscription definido no schema
• PubSub configurado e publicado na mutation
• Resolver da subscription usando asyncIterator
• Cliente com link WebSocket ativo
• Cleanup da subscription no unmount

FAQ

Preciso de WebSocket para GraphQL subscriptions?

Na prática, sim. O protocolo padrão usa WebSocket para manter a conexão aberta. Existem alternativas com SSE, mas o suporte é menos uniforme entre bibliotecas e servidores.

Qual a diferença entre subscription e query?

Query busca dados uma vez. Subscription mantém um canal aberto e envia novos dados quando o evento ocorre. É push, não pull.

Posso usar subscriptions em produção com múltiplos servidores?

Sim, mas não com PubSub em memória. Use Redis ou outro broker para que todos os processos recebam os eventos.

O que é o pacote graphql-subscriptions?

É uma biblioteca Node.js que conecta o GraphQL a um sistema pubsub, permitindo implementar subscriptions sem escrever a camada de eventos do zero.

Subscriptions funcionam com Apollo Client?

Funcionam, mas você precisa configurar um link WebSocket separado do link HTTP. Sem isso, a subscription simplesmente não conecta.