framework-graphql

# Habilidade de IA: Engenharia e Arquitetura de APIs GraphQL (framework-graphql) Esta skill orienta a inteligência artificial a atuar como especialista em design, arquitetura e implementação de **APIs GraphQL**, alinhada rigorosamente às especificações oficiais da GraphQL Foundation ([spec.graphql.org](https://spec.graphql.org/)). Cobre modelagem de esquemas usando GraphQL SDL (Schema Definition Language), construção de operações executáveis (Queries, Mutations e Subscriptions), arquitetura de resolvedores, mitigação do problema N+1 com DataLoader, paginação padrão Relay, formato estrito de resposta e tratamento de erros, e boas práticas de segurança e otimização. --- ## 🧭 Sistema de Tipos e Linguagem de Definição de Esquema (GraphQL SDL) ### 1. Tipos Escalares e Wrappers de Nulo/Lista - **Escalares Nativos**: `Int`, `Float`, `String`, `Boolean`, `ID`. - **Escalares Customizados**: Defina escalares explícitos para validação de dados específicos (ex: `DateTime`, `JSON`, `EmailAddress`). - **Modificadores de Tipo (Non-Null e List)**: - `[User]`: Lista nula de usuários nulos. - `[User!]`: Lista nula de usuários não-nulos. - `[User!]!`: Lista não-nula de usuários não-nulos (padrão mais recomendado para coleções). ### 2. Definição Declarativa do Esquema (SDL) ```graphql """ Representa a conta de um usuário no sistema. """ type User implements Node { id: ID! name: String! email: String! role: UserRole! orders(first: Int = 10, after: String): OrderConnection! createdAt: DateTime! } """ Padrão de Interface Node para identificação única global (padrão Relay). """ interface Node { id: ID! } enum UserRole { ADMIN CUSTOMER GUEST } """ Entrada de dados para criação de novo usuário. """ input CreateUserInput { name: String! email: String! role: UserRole = CUSTOMER } type CreateUserPayload { user: User userErrors: [UserError!]! } type UserError { field: [String!]! message: String! } """ Diretivas nativas e customizadas para alterar comportamentos de execução e validação. """ directive @auth(requires: UserRole = ADMIN) on FIELD_DEFINITION | OBJECT ``` --- ## 🛠️ Definição de Operações Executáveis (Queries, Mutations & Subscriptions) ### 1. Queries, Fragmentos e Aliases Utilize variáveis explícitas, fragmentos reutilizáveis e aliases para evitar colisões e otimizar payloads no lado do cliente: ```graphql query GetUserProfileWithOrders($userId: ID!, $orderLimit: Int!) { user(id: $userId) { ...BasicUserFields recentOrders: orders(first: $orderLimit) { edges { node { id totalAmount status } } } } } fragment BasicUserFields on User { id name email role } ``` ### 2. Mutations e Design de Payload de Resposta Adote o padrão **Mutation Ingest Input / Payload Output**: - As mutations devem aceitar um único parâmetro de entrada (`input: CreateUserInput!`). - Retorne um payload contendo a entidade criada/modificada e uma coleção declarativa de erros de domínio (`userErrors`). ```graphql mutation CreateNewCustomer($input: CreateUserInput!) { createUser(input: $input) { user { id name email } userErrors { field message } } } ``` ### 3. Subscriptions (Comunicação em Tempo Real) Implemente assinaturas reativas sobre WebSocket/Server-Sent Events (SSE) para atualização de eventos no cliente: ```graphql subscription OnOrderStatusUpdated($orderId: ID!) { orderStatusUpdated(orderId: $orderId) { id status updatedAt } } ``` --- ## ⚡ Arquitetura de Resolvedores e Resolução de N+1 (DataLoader) ### 1. Modelo de Execution & Resolver Tree Cada campo no GraphQL possui um resolvedor (*resolver*). Os resolvedores recebem quatro argumentos padrão: `(parent/root, args, context, info)`. ### 2. Prevenção do Problema N+1 com DataLoader Evite disparar múltiplas consultas SQL/HTTP para coleções associadas agrupando e armazenando requisições em lote (*batching and caching*) no ciclo de vida por requisição HTTP. ```typescript import DataLoader from 'dataloader'; // Resolver delegando a busca para DataLoader no contexto por requisição export const resolvers = { User: { orders: (parent, args, context) => { return context.loaders.ordersByUserId.load(parent.id); }, }, }; // Instanciação do DataLoader no context da requisição export function createLoaders(dbConnection) { return { ordersByUserId: new DataLoader(async (userIds: readonly string[]) => { const orders = await dbConnection.findOrdersByUserIds(userIds); // Mapeia os resultados garantindo a mesma ordem das chaves solicitadas return userIds.map(id => orders.filter(order => order.userId === id)); }), }; } ``` --- ## 📑 Paginação Padrão (Relay Cursor Connections Specification) Sempre que retornar listas extensas de dados, utilize a especificação **Relay Cursor Connections** para suportar paginação infinita e eficiente baseada em cursores bidirecionais: ```graphql type OrderConnection { edges: [OrderEdge!]! pageInfo: PageInfo! totalCount: Int! } type OrderEdge { cursor: String! node: Order! } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String } ``` --- ## 🚨 Formato de Resposta e Tratamento Estrito de Erros (GraphQL Spec) A especificação GraphQL determina um formato de resposta JSON estrito composto por `data`, `errors` e `extensions`: ```json { "data": { "user": null }, "errors": [ { "message": "Acesso negado para visualização deste recurso", "locations": [ { "line": 3, "column": 5 } ], "path": ["user"], "extensions": { "code": "FORBIDDEN", "timestamp": "2026-08-07T14:30:00Z" } } ], "extensions": { "tracing": { "version": 1, "duration": 4500000 } } } ``` - **Propagação de Erros Nulos (*Error Bubbling*)**: Se um erro ocorrer em um campo declarado como Não-Nulo (`!`), o erro propaga para o ancestral anulável mais próximo. Defina os campos com segurança para evitar que pequenas falhas anulem toda a árvore da resposta `data`. --- ## 🔒 Segurança, Proteção de Introspecção e Limitação de Taxa 1. **Limitação de Profundidade (Query Depth Limiting)**: - Limite a profundidade máxima aninhada das consultas (ex: máximo de 5 a 7 níveis) para evitar ataques de DoS com queries recursivas circulares. 2. **Cálculo de Complexidade de Query (Cost Analysis / Query Complexity)**: - Atribua um custo por campo ou coleção e recuse a execução caso o custo exceda o limite máximo permitido por requisição. 3. **Desativação de Introspecção em Produção**: - Desative as consultas de introspecção (`__schema`, `__type`) em ambientes de produção para ocultar detalhes da estrutura do modelo interno do atacante. 4. **Persisted Queries (Automatic Persisted Queries - APQ)**: - Permita apenas a execução de hashes SHA-256 pré-aprovados de queries em produção para reduzir largura de banda e bloquear requisições arbitrárias. --- ## 🔗 Integração com Outras Skills - Para projetar a arquitetura completa de backend e integração com banco de dados, consulte [backend-developer](../../roles/backend-developer/SKILL.md) e [software-architect](../../roles/software-architect/SKILL.md). - Para integração de clientes GraphQL no Frontend com React ou Vue, consulte [framework-react](../framework-react/SKILL.md) e [framework-vue](../framework-vue/SKILL.md). - Para auditoria de segurança em APIs GraphQL segundo a OWASP API Security Top 10, consulte [pentester-owasp-api-security-2023](../../security/appsec/pentester-owasp-api-security-2023/SKILL.md) e [appsec-owasp-asvs](../../security/appsec/appsec-owasp-asvs/SKILL.md). - Para comparar ou integrar com outros estilos de API, consulte [framework-rest-api](../framework-rest-api/SKILL.md), [framework-grpc](../framework-grpc/SKILL.md) e [framework-soap](../framework-soap/SKILL.md). - Para implementação segura em TypeScript ou Python, consulte [lang-typescript](../../languages/lang-typescript/SKILL.md) e [lang-python](../../languages/lang-python/SKILL.md).