Skip to content
mobius1qwe edited this page Nov 16, 2026 · 1 revision

Home > GraphQL 🚧

GraphQL

Important

Em desenvolvimento (2.0). Ainda não está numa versão lançada e pode mudar.

Vale para a 2.0 · Delphi XE em diante e Lazarus/FPC 3.2 em diante · Nível: intermediário

Em uma frase: o TRALGraphQLModule é um endpoint GraphQL (especificação de outubro de 2021): você escreve o esquema em SDL, liga um resolver a cada campo que precisa de um, e o RAL valida, executa e responde. Abrindo o endereço no navegador aparece o GraphiQL.

Você vai precisar: o pacote RALModuleGraphQLPackage (componente TRALGraphQLModule, paleta RAL - Modules). Para ter tabelas do banco como tipos, também o RALModuleGraphQLDBPackage (TRALGraphQLDBBinding), que requer o DBWare.

O esquema e os resolvers

uses RALGraphQLExecutor, RALGraphQLModule;

GraphQL := TRALGraphQLModule.Create(Self);
GraphQL.Schema.Text :=
  'type Book { id: ID! title: String! author: Author }'#10 +
  'type Author { name: String! }'#10 +
  'type Query { books(author: String): [Book!]! book(id: ID!): Book }';
GraphQL.Resolvers.AddResolver('Query', 'books', ListarLivros);
GraphQL.Resolvers.AddResolver('Book', 'author', AutorDoLivro);
GraphQL.Server := Servidor;      // POST e GET em /graphql (Path)

procedure TForm1.ListarLivros(AInfo: TRALGraphQLResolve);
begin
  // o resolver responde JSON; os campos de baixo (id, title) leem esse JSON
  AInfo.ReturnJSON('[{"id":"1","title":"Dom Casmurro","author":"Machado"}]');
end;

procedure TForm1.AutorDoLivro(AInfo: TRALGraphQLResolve);
begin
  // AInfo.Parent é o livro que o resolver de cima devolveu
  AInfo.ReturnJSON('{"name":' + TRALJSONObject(AInfo.Parent).Find('author').ToJSON + '}');
end;
  • Um campo sem resolver lê o campo do mesmo nome no JSON do pai. Só precisa de resolver o que é calculado, vem de outro lugar ou recebe argumentos.
  • Os argumentos chegam já convertidos para o tipo e com os valores padrão: AInfo.Arg('id'), ArgAsString, ArgAsInteger, ou o objeto AInfo.Args.
  • Para responder, use ReturnJSON, ReturnText, ReturnInteger, ReturnFloat, ReturnBoolean, ReturnValue ou ReturnNull. AInfo.Fail('mensagem') (ou uma exceção) deixa o campo nulo e põe o erro em errors, com path e locations.
  • AInfo.Request é o TRALRequest (cabeçalhos, usuário autenticado); GraphQL.Context é um objeto seu que chega em todos os resolvers.
  • Interfaces e unions: o valor diz o tipo em "__typename", ou responda no OnResolveType.

O que o executor faz

Consultas aliases, argumentos com padrão, fragmentos (nomeados e inline), @skip/@include, variáveis (com padrão e conversão), operationName, __typename
Mutações rodam em série; só por POST (um GET de mutação é 405)
Erros o campo com erro fica null; um campo não nulo que falha anula o objeto de cima, até achar um campo que aceite nulo
Validação campos e argumentos que não existem, argumentos obrigatórios, seleção em folha ou faltando, fragmentos desconhecidos ou em ciclo, variáveis não declaradas, diretivas desconhecidas: o pedido nem roda
Introspecção __schema, __type, descrições, @deprecated, @specifiedBy: o GraphiQL e os geradores de código leem o esquema
Limites MaxDepth (15) e MaxComplexity (1000 campos) barram a consulta abusiva antes de rodar; a introspecção não conta
Assinaturas ainda não (ficam para o WebSocket)

HTTP

  • POST com application/json ({"query", "variables", "operationName"}) ou com application/graphql (o corpo é a consulta).
  • GET ?query=...&variables=... só para consultas.
  • Quem pede Accept: application/graphql-response+json recebe 400 quando o pedido nem roda (erro de sintaxe ou validação); com application/json é sempre 200, como os clientes antigos esperam.
  • GraphiQL (ligado): um GET do navegador sem consulta recebe a página do GraphiQL (carregada da CDN unpkg). Desligue em produção se não quiser expor o editor.

Tabelas do banco como tipos (TRALGraphQLDBBinding)

uses RALGraphQLDB;

Binding := TRALGraphQLDBBinding.Create(Self);
Binding.DBModule := RALDBModule1;       // driver e pool do DBWare
Binding.Tables.Add('clientes=Cliente'); // tabela=Tipo (só a tabela: o nome com maiúscula)
Binding.MaxRows := 100;
Binding.Module := GraphQL;

Para cada tabela, o catálogo do banco vira um tipo (uma coluna, um campo, com o tipo e o "não nulo" da coluna; a chave é ID!) e entram dois campos em Query:

clientes(limit: Int = 100, offset: Int = 0, orderBy: String, id: ID, nome: String, ...): [Cliente!]!
cliente(id: ID!): Cliente
  • Os filtros são por igualdade de coluna, sempre com parâmetros; orderBy só aceita uma coluna da tabela com asc ou desc; limit nunca passa de MaxRows.
  • O seu SDL pode acrescentar campos ao tipo gerado com extend type Cliente { ... } e ligar resolvers a eles (eles leem a linha em AInfo.Parent).
  • O catálogo é lido quando o esquema é montado (servidor subindo ou primeiro pedido): uma tabela que não existe para o servidor ali, com a mensagem.

Erros comuns

Sintoma Causa Solução
o servidor não sobe o SDL tem erro (tipo que não existe, sintaxe) a mensagem diz qual tipo ou linha
Cannot query field o campo não está no esquema, ou está em outro tipo confira o SDL e o tipo de cima
Abstract type ... must resolve um valor de interface ou union sem __typename ponha "__typename" no JSON ou use OnResolveType
Query is too deep / too complex passou de MaxDepth/MaxComplexity aumente o limite ou divida a consulta
405 no GET mutação por GET mande por POST

Veja também

Começar

Servidor

MQTT 🚧

E-mail 🚧

Chatbot 🚧

Cliente

Motores

Avançado

Ajuda

🚧 = em desenvolvimento, pode mudar

Clone this wiki locally