Entrada

Salida

¿Qué es el Formateador de Consultas GraphQL?

Cada solicitud GraphQL que alguien escribe a mano empieza como un muro de llaves de una sola línea. Pegarla en una revisión de código sin formatearla antes es una forma segura de recibir "reformatea por favor" como primer comentario. Lo mismo pasa con las consultas que salen de un build de frontend, las que registra un servidor o las que aterrizan en un hilo de Slack cuando un compañero pregunta "¿por qué esto devuelve null?". Esta página toma una consulta, mutación, suscripción o fragmento y lo embellece: sangría de dos espacios, un campo por línea, argumentos en línea cuando caben, variables ordenadas y la gramática de operaciones de la especificación GraphQL respetada de principio a fin.

Ten en cuenta que esta página es la complementaria del lado de operaciones de GraphQL Formatter. Esa herramienta formatea el lenguaje de definición de esquemas — tu type Order, interface Node, enum Status. Esta herramienta formatea lo que tu cliente envía y lo que tu servidor recibe: query OrderDetails($id: ID!) { order(id: $id) { ... } }, mutaciones, suscripciones y definiciones de fragmentos. Las dos gramáticas comparten tokens pero las reglas estructurales son distintas — los selection sets, los alias, los fragment spreads, los inline fragments y la aplicación de directivas son exclusivos de operaciones. Si pegaste SDL por error, ve al formateador de esquemas en su lugar.

El formateo está hecho a mano en TypeScript — no se carga ningún bundle de graphql-js en la página, así que el primer pintado se mantiene ligero. La salida coincide con la que produce Prettier con su plugin de GraphQL para los casos comunes, así que pegar la consulta formateada en una base de código que ya usa Prettier no debería generar ningún diff. Todo se ejecuta localmente — tu consulta nunca sale del navegador.

Cómo Usar el Formateador de Consultas GraphQL

Tres pasos. No hay un botón Convertir — el formateo se dispara automáticamente un instante después de que dejas de escribir.

Pega, Sube o Carga un Ejemplo

Pega una operación GraphQL en el panel Entrada de la izquierda. Haz clic en Subir para un archivo .graphql o .gql, o pulsa Ejemplo para una consulta realista de comercio electrónico OrderDetails más un pequeño fragmento. Un pegado típico desordenado se ve así:

query OrderDetails($id:ID!,$includeItems:Boolean=true){order(id:$id){id placedAt status customer{id name email}items @include(if:$includeItems){sku quantity unitPrice{amountCents currency}}total{amountCents currency}}}

El formateador maneja todas las construcciones de operación que aparecen en código de cliente real: definiciones de variables con valores por defecto, valores por defecto de tipo lista, directivas @include / @skip / personalizadas, alias, fragment spreads (...Money) e inline fragments (... on PaidOrder { ... }). Múltiples operaciones o fragmentos en un mismo documento se mantienen separados, con una línea en blanco entre ellos — que es cómo Apollo Client y la mayoría del tooling GraphQL espera que los documentos estén dispuestos.

Lee la Salida Embellecida

El panel Salida de la derecha renderiza la operación formateada. Cada campo recibe su propia línea. Los argumentos se quedan en línea cuando el campo cabe en 80 caracteres y se rompen en líneas separadas cuando no — la misma regla que usa el plugin de GraphQL en Prettier. Las definiciones de variables siguen la misma regla en la cabecera de la operación. Los alias mantienen un único espacio después de los dos puntos (aliasedAs: fieldName). Los comentarios (# ...) se preservan en la sangría de la línea a la que estaban adjuntos. Si la entrada está mal formada — llaves sin pareja, un $ suelto, un : faltante — el formateador escribe un error amistoso en línea en lugar de lanzar una excepción.

Copia o Descarga

Pulsa Copiar para llevarte la consulta formateada a un PR, doc o mensaje de chat. Pulsa Descargar para guardar como query.graphql. Limpiar reinicia la entrada. Toda la cadena es del lado cliente — útil cuando estás depurando una consulta contra una API interna y prefieres no pegarla en una herramienta de terceros.

Cuándo lo Usarías Realmente

Revisión de Código e Higiene de PRs

Un PR de frontend añade una nueva mutación. La cadena de consulta fue emitida por un paso del build que quitó los espacios en blanco y ahora el diff es un muro de 400 caracteres. Pasa la mutación por el formateador, mete la versión embellecida en la descripción del PR y el revisor podrá ver de verdad qué campos estás leyendo. El mismo truco funciona para graphql-react, urql, Relay y cualquier otro cliente donde las consultas vayan en línea como template literals.

Depurar una Consulta en Producción

Una consulta en producción está devolviendo null para un campo que esperabas. Coges el cuerpo de la solicitud desde la pestaña de red, lo pegas aquí y ya puedes ver los valores de las variables, qué campos usan @include y dónde caen los fragment spreads. Mejor que entrecerrar los ojos sobre una línea larguísima. Combínalo con la guía oficial sobre servir GraphQL sobre HTTP cuando necesites reproducir la solicitud manualmente con curl o Postman.

Aprender e Incorporación

¿Nuevo en operaciones GraphQL? Pega una consulta que encontraste en un tutorial, formatéala y la estructura se vuelve obvia — cabecera de operación, selection set, selection sets anidados, definiciones de fragmento al final. La salida refleja la disposición que verás en la guía de consultas de graphql.org, así que es fácil mapear de vuelta a la documentación mientras aprendes.

Pre-commit y Puertas de CI

Como el formateador es determinista — las consultas ya embellecidas vuelven sin cambios — puedes usar esta página como una comprobación rápida de "¿está mi consulta ya bonita?" antes de hacer commit. Para una pipeline totalmente automatizada, pasa la misma fuente por Prettier con su plugin de GraphQL y haz que el build falle si hay un diff distinto de cero. Misma idea, pero a escala.

Preguntas Frecuentes

¿En qué se diferencia esto de la página GraphQL Formatter?

La página GraphQL Formatter formatea el lenguaje de definición de esquemas — tus declaraciones de type, interface, enum, union, scalar y directive. Esta página formatea operaciones: query, mutation, subscription y fragment. Las dos gramáticas comparten tokens pero tienen reglas estructurales muy distintas, así que intentar formatear una operación en la página de esquema (o al revés) da una salida confusa. Elige la herramienta adecuada según lo que hayas pegado.

¿Valida mi consulta contra un esquema?

No. El formateador comprueba el balance de llaves, paréntesis y corchetes lo suficiente para imprimir bonito, pero no conoce tu esquema, así que no puede decirte que order recibe id: ID! en lugar de id: Int!. Para validación real, pasa tu operación por las comprobaciones de arranque de tu servidor o contra el validador de referencia de graphql-js en el enlace de GitHub de arriba.

¿Mi consulta se envía a un servidor?

No. El formateo es JavaScript puro del lado cliente — nada se sube, nada se registra. Seguro para consultas internas, consultas que incluyen valores de variables sensibles o consultas contra APIs privadas.

¿Tocará mis valores de variables o argumentos?

No. Los valores de argumento, valores por defecto y valores por defecto de tipo lista se emiten exactamente como los escribiste, solo con espaciado consistente alrededor de :, = y ,. El formateador nunca inventa, descarta ni reordena campos, argumentos o variables — lo que pegaste es lo que sale, solo dispuesto limpiamente.

¿Maneja inline fragments y fragment spreads?

Sí. Los inline fragments (... on PaidOrder { ... }) reciben el tratamiento estándar de selection set con sangría de dos espacios. Los fragment spreads (...Money) se quedan en una sola línea con la sangría del campo, y cualquier directiva se mantiene en la misma línea. Múltiples definiciones de fragmento en un documento se mantienen como definiciones separadas de nivel superior con una línea en blanco entre ellas.

¿Y las consultas anónimas — <code>{ field }</code> — las expande a <code>query { field }</code>?

No. La forma abreviada es parte de la especificación y el formateador la preserva tal cual. Si quieres una consulta con nombre, ponle el nombre tú mismo — el formateador no reescribe operaciones en silencio.

Otras Herramientas GraphQL

Un formateador de consultas es una porción del trabajo con GraphQL. Las otras herramientas GraphQL del sitio: