Repository navigation
graphql
Home > 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.
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 objetoAInfo.Args. - Para responder, use
ReturnJSON,ReturnText,ReturnInteger,ReturnFloat,ReturnBoolean,ReturnValueouReturnNull.AInfo.Fail('mensagem')(ou uma exceção) deixa o campo nulo e põe o erro emerrors, compathelocations. -
AInfo.Requesté oTRALRequest(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 noOnResolveType.
| 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) |
-
POSTcomapplication/json({"query", "variables", "operationName"}) ou comapplication/graphql(o corpo é a consulta). -
GET ?query=...&variables=...só para consultas. - Quem pede
Accept: application/graphql-response+jsonrecebe 400 quando o pedido nem roda (erro de sintaxe ou validação); comapplication/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.
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;
orderBysó aceita uma coluna da tabela comascoudesc;limitnunca passa deMaxRows. - O seu SDL pode acrescentar campos ao tipo gerado com
extend type Cliente { ... }e ligar resolvers a eles (eles leem a linha emAInfo.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.
| 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 |
- Recursos REST sobre tabelas: o mesmo banco em REST
- Exemplo:
GraphQLExample(Delphi e Lazarus)
Começar
Servidor
- Rotas e parâmetros
- Rotas avançadas: tipos, grupos, versões 🚧
- Ler o pedido e responder
- Objetos no corpo 🚧
- Resposta em fluxo 🚧
- Plugins 🚧
- Serviços (contêiner de dependências) 🚧
- Barramento de eventos 🚧
- Tarefas em segundo plano 🚧
- Recursos com estado 🚧
- Autenticação
- Banco de dados (DBWare)
- Servir site e arquivos
- JSON-RPC 2.0 🚧
- GraphQL 🚧
- Servidor MCP (IA) 🚧
-
Protocol Buffers 🚧
- gRPC 🚧
- WebSocket 🚧
- Hubs (WebSocket) 🚧
- SignalR 🚧
- Swagger e Postman
- Servidor SOAP 🚧
- WS-Security 🚧
- HTTPS
- Criptografia ponto a ponto
- Segurança para produção
- Colocar no ar
- Desempenho
- Testes em memória 🚧
MQTT 🚧
- O que é e quando usar 🚧
- Cliente MQTT 🚧
- Broker MQTT 🚧
- MQTT-SN 🚧
- Ponte REST 🚧
- Segurança 🚧
- Rede ruim 🚧
E-mail 🚧
- Mensagens 🚧
- Enviar 🚧
- Enviar por REST e ação 🚧
- Receber 🚧
- Ler a caixa postal 🚧
- Verificar o que chega 🚧
- Servir caixas postais 🚧
- S/MIME 🚧
- OpenPGP 🚧
Chatbot 🚧
- O robô e os canais 🚧
- Telegram 🚧
- Gateways REST (WhatsApp não oficial) 🚧
- Discord 🚧
- Slack 🚧
- Microsoft Teams 🚧
- Conversa em etapas 🚧
Cliente
Motores
- Qual motor escolher?
- Compatibilidade
- Recursos
- QUIC
- Motor NgHttp2 (HTTP/2) 🚧
- Motor XSocket 🚧
- Motor AdvancedHTTP (experimental) 🚧
Avançado
Ajuda
- Problemas comuns
- Atualizar o Indy
- Várias versões do Delphi
- Vídeos e guias
- Módulos de terceiros
- Licenças
- Contribuir
- Roadmap e changelog
🚧 = em desenvolvimento, pode mudar