Fundamentos de GraphQL para desarrolladores de React

REST expone endpoints con una estructura fija: GET /users/:id devuelve el objeto de usuario completo, independientemente de lo que necesite el cliente. GraphQL permite que los clientes especifiquen exactamente qué campos desean, lo que elimina la sobrecarga de datos (recibir demasiados datos) y la falta de datos (no recibir suficientes y tener que realizar varias solicitudes).

Una sola consulta de GraphQL puede obtener un usuario, sus publicaciones y el autor de cada publicación en una sola ida y vuelta.

Toda API de GraphQL se define mediante un esquema escrito en Schema Definition Language (SDL). El esquema declara los tipos, sus campos y los tipos raíz Query, Mutation y Subscription con los que pueden operar los clientes.

El esquema es el contrato entre el cliente y el servidor. Los equipos de frontend y backend pueden trabajar en paralelo una vez acordado el esquema.

Una consulta de GraphQL selecciona campos: { user(id: "1") { name email posts { title } } }. Los campos anidados recorren las relaciones en una sola solicitud. Los alias cambian el nombre de los campos: { me: user(id: "1") { name } }. Los fragmentos reutilizan selecciones de campos en varias consultas.

Las variables permiten reutilizar las consultas: query GetUser($id: ID!) { user(id: $id) { name } } con variables: { id: "1" }.

Cada campo del esquema de GraphQL tiene una función resolver en el servidor. Cuando un cliente consulta user.name, el resolver de user obtiene el objeto de usuario y el resolver de name (o el resolver predeterminado) devuelve el campo name.

Esta resolución a nivel de campo es la que permite a GraphQL obtener con precisión solo los datos solicitados.

Si consulta una lista de 100 publicaciones y cada publicación incluye a su autor, la implementación ingenua ejecuta 100 consultas independientes a la base de datos para obtener los autores. Este problema N+1 hace que las API de GraphQL sean lentas si no se optimizan.

DataLoader resuelve el problema N+1 agrupando todas las búsquedas de autores en una sola consulta a la base de datos mediante una caché por solicitud y una función de agrupación.

Apollo Studio y GraphQL Playground son interfaces de usuario basadas en el navegador para explorar interactivamente una API de GraphQL. Autocompletan los campos a partir del esquema, muestran los resultados de las consultas y presentan la documentación de los tipos integrada en la interfaz.

Usar el playground es la forma más rápida de comprender una API de GraphQL desconocida antes de escribir código del cliente.

Las API de GraphQL exponen su propio esquema mediante una consulta de introspección: { __schema { types { name } } }. Los clientes pueden consultar el propio esquema para descubrir los tipos, campos y argumentos disponibles.

Las herramientas de generación de código como graphql-codegen usan la introspección para generar automáticamente tipos de TypeScript que coinciden con el esquema de la API.

Las mutaciones de GraphQL modifican los datos: mutation CreatePost($input: PostInput!) { createPost(input: $input) { id title } }. Las suscripciones establecen una conexión persistente (normalmente mediante WebSocket) y envían actualizaciones: subscription { postAdded { id title } }.

Los tres tipos raíz (Query, Mutation, Subscription) utilizan la misma sintaxis de selección de campos.

GraphQL resulta excelente en aplicaciones con requisitos de datos complejos y anidados, varios tipos de clientes (móvil, web y TV) que necesitan distintos subconjuntos de campos, o API que evolucionan rápidamente y en las que se prefiere retirar campos en desuso en lugar de versionar endpoints.

REST es más sencillo para API CRUD con formas de recursos predecibles y planas, además de ofrecer excelentes posibilidades de caché HTTP mediante ETags y encabezados de caché.

Apollo Client es el cliente de GraphQL con más funcionalidades: caché normalizada, gestión del estado local, suscripciones y enlaces para gestionar errores. URQL es más ligero, con una caché de documentos y una API más sencilla. React Query con graphql-request es el enfoque más simple para consultas y mutaciones básicas sin una gestión avanzada de la caché.

Elija en función de sus requisitos de caché: use una caché normalizada para entidades compartidas entre consultas (Apollo), o una caché de documentos más sencilla para consultas independientes (URQL o React Query).

Un SDL sencillo: type User { id: ID! name: String! posts: [Post!]! } type Post { id: ID! title: String! author: User! } type Query { user(id: ID!): User users: [User!]! }. Los signos de exclamación indican campos que no admiten valores nulos.

Este esquema indica al cliente exactamente qué campos existen en cada tipo y qué consultas están disponibles, lo que permite generar código con seguridad de tipos.

¿Qué significa "over-fetching" en el contexto de REST frente a GraphQL?

GraphQL permite que los clientes soliciten exactamente los campos que necesitan (sin over-fetching ni under-fetching) mediante un lenguaje de consultas definido por un esquema. Los resolvers responden a cada campo; DataLoader resuelve el problema N+1. La introspección permite generar tipos de TypeScript. Apollo Client, URQL y React Query son los principales clientes de GraphQL compatibles con React.

Elija GraphQL para requisitos de datos complejos, anidados y destinados a varios clientes; elija REST para operaciones CRUD sencillas con formas predecibles.